Modal
Dialog overlay for focused content or actions. Uses the native <dialog> element and the Invoker Commands API for declarative open/close without bespoke JavaScript. Reach for a modal when a user needs to complete a task or confirm a decision without leaving the current page context.
Usage
When to use
- Confirming a destructive action before it happens
- Collecting a small amount of focused input without a full page
- Showing supplementary information that would disrupt the page flow if inlined
When not to use
- For non-blocking notifications - use a message or announcement
- For side panels that slide in from the edge - use a drawer
- For short contextual hints - use a tooltip
Do
- Give every modal a clear title in the header
- Provide an explicit close button in addition to the Escape key
- Return focus to the invoking element on close
Don't
- Stack modals on top of other modals
- Put long scrollable forms inside small modals - use a full page
- Auto-dismiss a modal without user action
The backdrop contract
A dialog opened with showModal() always paints a backdrop and makes the rest of the page inert. Neither is configurable: the backdrop's existence and the page being blocked are both consequences of the open method, not settings the component exposes. The --modal-backdrop-background-color token changes the backdrop's colour, but not whether it is there.
Because the page behind is unusable while a modal is open, every modal must offer two ways out, and both are on by default:
- A visible close button in the header, rendered by
has_close(defaulttrue). - The Escape key, wired through the close utility via
data-close-escand answered natively by the<dialog>element regardless.
Clicking the backdrop dismisses nothing. Light dismiss is easy to trigger by accident and discards whatever the dialog was collecting, so the modal asks for a deliberate gesture instead. A dialog that sets has_close: false should therefore supply its own explicit action - a footer button, or a form submitted with method="dialog".
API
Slots
| Slot | Required | Description |
|---|---|---|
title | - | Dialog title rendered inside the header. |
content | Yes | Main content rendered inside the body. |
footer | - | Footer content, typically action buttons. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | - | HTML id for the dialog. Buttons target it via commandfor. |
has_close | boolean | true | Whether to render a close button in the header. |
is_open | boolean | - | Whether the dialog renders with the open attribute. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.xl | Size | - | Extra large. |
.fullscreen | Layout | - | Fills the entire viewport. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
.flat | Elevation | - | No elevation. |
.raised | Elevation | - | Slight elevation. |
.elevated | Elevation | Yes | High elevation. |
Events
| Event | Direction | Description |
|---|---|---|
modal-opened | Emits | Fired on the dialog after it transitions to the open state. |
modal-closed | Emits | Fired on the dialog after it transitions to the closed state. |
modal-command | Emits | Fired on the dialog when a trigger button uses a custom command (one starting with two leading hyphens, e.g. command="--save"). |
close-dismiss | Listens | Listened on the dialog. Closes the dialog when a descendant close button dispatches this event. |
Examples
Small
Compact size for short confirmations.
Large
Wider size for richer content.
Extra large
Widest size for complex content.
Fullscreen
Full viewport modal for immersive content.
Accessibility
- WCAG 2.2 AA
- Escape key closes the modal
- A visible close button is rendered by default, so dismissal never depends on knowing a keyboard shortcut
- The page behind the modal stops scrolling while it is open
- Focus is trapped inside the modal while open
- Focus returns to the invoking element on close
- Screen readers announce the dialog as modal
- Reduced-motion disables the fade animation
Dependencies
- close - dismiss button used in the modal header
Progressive enhancement
- No JS: the native
<dialog>element opens, closes, traps focus and answers Escape on its own, and the scroll lock is a CSS rule, so all of that holds with JavaScript disabled. A trigger carryingcommandforandcommandopens the dialog natively on browsers that ship the Invoker Commands API. - With JS: a click handler stands in for the Invoker Commands API on browsers that have not shipped it, so the same trigger markup opens the dialog everywhere.
- How to enable: include the modal JS. It binds to the
commandfortriggers already in the markup, so no extra attribute is needed.