lit-modal

A small Lit web component for modal dialogs, built on the native <dialog> element.

The component provides a simple custom element API while keeping native dialog behavior for modality, focus restoration, and accessibility semantics.

Usage

Install the package:

npm install @theres_thormaehlen/lit-modal

Import the component into your app:

import '@theres_thormaehlen/lit-modal';

Use the custom element in HTML:

<button id="open-modal">Open modal</button>

<lit-modal title="Example modal">
	<p>Hello from the modal.</p>

	<button id="close-modal" slot="footer">Close</button>
</lit-modal>

Open and close it from JavaScript:

const modal = document.querySelector('lit-modal');

document.querySelector('#open-modal')?.addEventListener('click', () => {
	modal.showModal();
});

document.querySelector('#close-modal')?.addEventListener('click', () => {
	modal.close();
});

API

Attributes and Properties

| Attribute | Property | Type | Default | Description | | ---------------------- | -------------------- | --------- | ------------------ | ----------------------------------------------------------------------------------------- | | open | open | boolean | false | Reflects whether the modal is open. | | title | title | string | 'Untitled Modal' | Text used for the modal heading and accessible label. | | dismiss-return-value | dismissReturnValue | string | '' | Return value used when the modal is dismissed by Escape, backdrop click, or close button. | | no-dismiss | noDismiss | boolean | false | Disables Escape, backdrop, and close-button dismissal. |

Methods

| Method | Description | | ----------------------------- | ---------------------------------------------------------- | | showModal() | Opens the modal. | | close(returnValue?: string) | Requests the modal to close with an optional return value. |

Events

All events have the same detail. The returnValue property is set to the value passed to close() or the dismiss-return-value attribute.

modal-closing

Fired before the modal closes. This event is cancelable and can be used to prevent the modal from closing, different from native dialog behavior.

modal?.addEventListener('modal-closing', (event) => {
	event.preventDefault();
});

modal-closed

Fired after the modal has closed.

modal?.addEventListener('modal-closed', (event) => {
	console.log(event.detail.returnValue);
});

Accessibility

• The component uses a native <dialog> element.
• The title is rendered as a heading and used for the accessible label.
• Focus restoration is handled by the browser's native dialog behavior.
• Initial focus inside slotted modal content follows native browser behavior and may differ between Chromium, Firefox, and WebKit.

Compatibility

This component targets modern browsers with native <dialog> and crypto.randomUUID() support.

Development

npm install
npm run build
npm run test

WebKit tests are opt-in:

npm run test:webkit

Other checks:

npm run lint
npm run format:check