Dialog

Choosing a pop-up surface⁠link

Five kinds of surface open over the page for a moment. Each suits a different job:

Three jobs belong elsewhere. A message about something that just happened is a toast, content that stays on the page is a card, and a short set of creation actions opened from a floating button is a FAB menu.

Choosing a variant⁠link

Two variants set how much of the screen a dialog takes, from least to most:

• Basic: one decision or a short task, such as confirming a deletion or renaming a file.
• Full screen: a series of tasks, such as filling in a new event's title, time, and guests on a phone.

Built in⁠link

• The page behind an open dialog is inert, and its scrolling is locked until the dialog closes.
• Tab and Shift+Tab stay inside the dialog, wrapping from its last control to its first.
• Escape and a click on the scrim close it, each firing a cancelable cancel event first; ignore-escape-key and ignore-scrim-click turn either off.
• A <form method="dialog"> in its content closes it and sets return-value to the value of the button that submitted it.
• Content taller than the dialog scrolls inside it, with a shadow or a divider at the edge that has more (scroll-indicator).
• The full-screen variant draws its own close button and moves the actions into its headline bar (actions-placement).

Hidden content renders when first shown⁠link

A dialog's panel, headline, content, and actions do not exist until it first opens. Each opening starts like the first, scrolled to the top. Your content stays as it was, so a half-filled form is still half filled, and returnValue stays readable after the dialog closes. After you open the dialog, wait for updateComplete and everything is there for your code to reach at once. See Hidden content renders when first shown.

Starting fresh each time⁠link

A dialog never clears what your app put in it, so a form the user abandoned is still filled when the dialog opens again. If each opening should start empty, reset the content when the dialog reports it has closed.

dialog.addEventListener("toggle", (event) => {
  if (event.newState === "closed") dialog.querySelector("form")?.reset();
});

React and Blazor use onToggle and OnToggle; see Starting each opening empty.

Using dialogs well⁠link

• Open a dialog only for a question the reader must answer now; show anything they can ignore in a Popover or a Menu.
• Give every dialog a headline that states its question, or an aria-label when it has no headline.
• Set type to alert only for an important message that needs a response, such as confirming a destructive action.
• Put the confirming action last, after the one that dismisses: Cancel, then Delete.
• Put autofocus on the control that should take focus when the dialog opens, usually the safest action.
• Open a dialog over another dialog only from a full-screen one.

These rules follow Material 3 Expressive's guidance for dialogs, on material.io.

Variants⁠link

variant has two values. basic, the default, can show an icon slot above its headline. full-screen fills the viewport, draws a close button in its headline bar, and puts the actions there too; set no-close-button to remove the close button. When to choose each is in Choosing a variant.

Opening and closing⁠link

Set open, or call show(), to open a dialog; clear open, or call close(), to close it. close() takes an optional value, which becomes return-value. Each change fires a beforetoggle event before its animation, and a toggle event after it; both carry oldState and newState. Cancel beforetoggle to keep the dialog shut when newState is "open", or to keep it open when newState is "closed". A listener on the dialog hears only its own beforetoggle and toggle, never those of an element inside it.

Dismissing⁠link

Escape and a click on the scrim both fire cancel on the dialog, then close it with the usual beforetoggle and toggle; cancel that cancel event to keep it open. cancel does not bubble, so listen on the dialog itself. Set ignore-escape-key or ignore-scrim-click to turn either path off, and then no cancel fires for it. Keep at least one way out: with both set, and no-close-button on a full-screen dialog, only the controls you put inside it can close it.

Forms⁠link

Put a <form method="dialog"> in the content slot, and give each button in the actions slot the form's id in its form attribute, a type of submit, and a value. Submitting the form closes the dialog, and return-value becomes the value of the button that submitted it; read it in a toggle listener once newState is "closed". A form that fails validation does not submit, so the dialog stays open. The preview blocks form submission in some browsers, so each button here also calls close() with its value; on your own page, the form alone closes the dialog.

Alert dialogs⁠link

With type set to alert, screen readers announce the dialog as an alert dialog rather than a plain one. Leave type unset for every other dialog; when to use it is in Using dialogs well.

Actions placement⁠link

actions-placement moves the actions slot independently of the variant. auto, the default, puts the actions in the footer row of a basic dialog and in the headline bar of a full-screen one. bottom and headline put them in one place whatever the variant. Slot each button directly; they sit at the end of the row and wrap when space runs short.

Animation⁠link

animation sets how a dialog appears and leaves: fade, slide, or none. Omit it and the dialog takes the animation from your style configuration, which is fade unless you have changed it. A reader who asks for reduced motion gets no animation, whatever the setting.

Scroll indicator⁠link

Content taller than the dialog scrolls inside it, vertically only. scroll-indicator marks the edge that has more to show: shadow, divider, or none. Omit it and the dialog takes the indicator from your style configuration, which is shadow unless you have changed it.

Each attribute value has its own tokens; a cell shows its token's value, and selecting the cell shows the token's fallback path, with each name and value ready to copy. For example, the basic column's container-color row is --ct-dialog-basic-container-color, which defaults to --ct-sys-color-surface-container-high.

Variant⁠link

Indicator⁠link

Names and states⁠link

A dialog is announced as a modal dialog and follows the WAI-ARIA Authoring Practices: Dialog (Modal) pattern.

• The headline's text names the dialog. A dialog with no headline takes its name from an aria-label on it; with neither, it has no name, so give it one or the other.
• aria-label is the only ARIA attribute a dialog accepts. Any other aria-* attribute, and role, has no effect.
• An alert dialog is announced with an urgent tone that a plain dialog lacks.
• The headline is announced as a level-two heading, so slot the headline as plain text in a <div> or <span>, never as a heading element.
• The icon slot is hidden from screen readers, so an icon adds nothing to the name or description; put any meaning in the headline.
• While its content overflows, the scrolling region is a named region landmark. The headline names it, or else the dialog's aria-label, or else the English words "Dialog content", which are not localized.
• The full-screen variant's close button is named by the localized word "Close".
• For content the reader can ignore, a Popover or a Menu suits better; see Choosing a pop-up surface.

Keyboard and focus⁠link

• On opening, focus moves to the first control in the dialog, or to the element that carries autofocus. Put autofocus on the safest action. With nothing focusable inside, the dialog itself takes focus.
• The page behind the dialog is inert while it is open, so Tab never reaches it. no-focus-trap removes the wrap, and Tab then moves on to the browser's own controls.
• Closing the dialog, by any route, returns focus to the control that had it before the dialog opened.
• While its content overflows, the scrolling region is a Tab stop, so a keyboard user can scroll it.
• The controls inside draw their own focus rings.

Pointer and touch⁠link

• A click or tap on the scrim fires cancel, then closes the dialog, unless ignore-scrim-click is set. A click inside the dialog, or inside a popover it contains, is not a scrim click.
• The only control the dialog draws itself is the full-screen variant's close button, a small icon button, whose target size against WCAG 2.5.8 (24 by 24 pixels) is the icon button's. Every other target is a control you slot in.

Display settings⁠link

• Forced colors: the dialog takes a 2-pixel outline in the system's text color, and the scrim drops its blur and keeps its opacity.
• Reduced motion: the open and close animation becomes none, whatever animation says.

Standards⁠link

With its defaults, a dialog meets two WCAG 2.2 success criteria:

• 2.1.2 No Keyboard Trap (A)
• 2.4.7 Focus Visible (AA)

Four more depend on how you use it:

• 2.4.3 Focus Order (A): put autofocus on the safest action, and check that focus returns to the control that opened the dialog when it closes.
• 4.1.2 Name, Role, Value (A): give the dialog a headline, or an aria-label when it has none.
• 2.4.6 Headings and Labels (AA): write a headline that states the dialog's question or task.
• 1.3.1 Info and Relationships (A): slot the headline as plain text, since the dialog already makes it a heading.