Skip to main content

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 (default true).
  • The Escape key, wired through the close utility via data-close-esc and 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​

SlotRequiredDescription
title-Dialog title rendered inside the header.
contentYesMain content rendered inside the body.
footer-Footer content, typically action buttons.

Props​

PropTypeDefaultDescription
idstring-HTML id for the dialog. Buttons target it via commandfor.
has_closebooleantrueWhether to render a close button in the header.
is_openboolean-Whether the dialog renders with the open attribute.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.xlSize-Extra large.
.fullscreenLayout-Fills the entire viewport.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.
.flatElevation-No elevation.
.raisedElevation-Slight elevation.
.elevatedElevationYesHigh elevation.

Events​

EventDirectionDescription
modal-openedEmitsFired on the dialog after it transitions to the open state.
modal-closedEmitsFired on the dialog after it transitions to the closed state.
modal-commandEmitsFired on the dialog when a trigger button uses a custom command (one starting with two leading hyphens, e.g. command="--save").
close-dismissListensListened 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 carrying commandfor and command opens 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 commandfor triggers already in the markup, so no extra attribute is needed.
  • drawer - sliding edge panel using the same <dialog> base
  • dropdown - lightweight floating panel for menus
  • close - the dismiss button used inside the header