Dialog
A modal dialog for one decision or short task.
Guidance
Dialogs ask for one decision or one short task without leaving the page: a native modal
<dialog> on mm-raised with radius-lg and shadow-dialog, over a flat ink scrim (no blur).
The heading is a real heading in the 20px heading style and names the dialog; the optional
description is announced with it. Actions go in the footer slot with the primary last, after
Cancel. Long content scrolls inside the body while the header and footer stay put, gaining a
hairline once content runs under them.
Opening uses showModal(), so the page behind is inert and the dialog sits in the top layer.
Focus goes to the first autofocus element, otherwise the first control in the body or footer
(scroll areas such as a code sample or a log are skipped), otherwise the close button. Tab and Shift+Tab wrap inside the dialog. Escape, the close button
and (with dismissible) a click on the backdrop fire a cancelable mm-request-close first, so
a form with unsaved changes can keep the dialog open. Closing returns focus to the element that
opened it, and page scrolling is locked while it is open. It fades and rises over
--mm-dur-dialog, appears instantly when opened from the keyboard, and does not move under
reduced motion.
Any slotted element with a data-close attribute closes the dialog when clicked, with the
attribute's value as returnValue (<mm-button slot="footer" data-close="cancel">).
Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
heading | heading | string | '' | The heading, which also names the dialog. Required unless the heading slot is used. |
description | description | string | '' | A sentence under the heading, announced with it. |
size | size | DialogSize | 'md' | sm (400px), md (560px, default), lg (800px) or full (the viewport less the page gutter). |
open | open | boolean | false | Opens and closes the dialog. Reflects. |
dismissible | dismissible | boolean | false | Lets a click on the backdrop close the dialog (through mm-request-close). Leave off for forms. |
headingLevel | heading-level | number | 2 | Heading level for the outline, 1 to 6. The look does not change. |
closeLabel | close-label | string | '' | Accessible name of the close button. Defaults to the close string. |
alert | alert | boolean | false | Announces the dialog as an alertdialog: an urgent interruption that needs a response, such as confirming a destructive action (mm-confirm-dialog sets it). Leave off for forms and tasks. Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/ |
returnValue | string | '' | The value the dialog last closed with. |
Methods
| Method | Description |
|---|---|
show() | Opens the dialog. |
close() | Closes the dialog with an optional return value, which mm-close carries. |
requestClose() | Asks to close as Escape would: fires a cancelable mm-request-close and closes unless it is cancelled. |
Events
| Event | Detail | Description |
|---|---|---|
mm-open | CustomEvent<Record<string, never>> | The dialog opened and focus moved into it. |
mm-close | CustomEvent<DialogCloseDetail> | The dialog closed. |
mm-request-close | CustomEvent<DialogRequestCloseDetail> | Escape, the close button or the backdrop asked to close. Cancel it to keep the dialog open. |
Slots
| Slot | Description |
|---|---|
| Default | The body. |
heading | A rich heading, in place of the heading attribute. |
description | A rich description, in place of the description attribute. |
footer | Actions, primary last. |
CSS parts
| Part | Description |
|---|---|
dialog | The native dialog element. |
header | The header row. |
heading | The heading. |
description | The description. |
close | The close button. |
body | The scrolling body. |
footer | The footer row. |
Examples
Every state of mm-dialog in Storybook, with keyboard and screen reader tests.