Dialogs
Dialogs provide important prompts in a user flow.
<md-gb-button id="open-delete">Delete</md-gb-button>
<md-gb-dialog id="delete-dialog">
<span slot="headline">Permanently delete?</span>
Deleting the selected messages also removes them from your other devices.
<form id="delete-form" method="dialog"></form>
<md-gb-button slot="actions" form="delete-form" value="cancel">Cancel</md-gb-button>
<md-gb-button slot="actions" form="delete-form" value="delete">Delete</md-gb-button>
</md-gb-dialog>document.querySelector('#open-delete').addEventListener('click', () => {
document.querySelector('#delete-dialog').show();
});Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-dialog.json (setup)
Usage guidelines
Link to “Usage guidelines”- Use them sparingly. A dialog interrupts people to ask for a decision or to show critical information, so it blocks the rest of the app until it is dismissed.
- Pick the right priority. For low or medium priority information, use a snackbar instead.
- Choose basic or full-screen. Use a basic dialog by default. A full-screen dialog suits compact windows with a lot of content.
- Order the actions. Put the dismissive action first and the confirming action last.
Anatomy
Link to “Anatomy”A dialog has an optional icon and headline, supporting content, and actions.
<md-gb-dialog open quick>
<md-gb-icon slot="icon">info</md-gb-icon>
<span slot="headline">Discard draft?</span>
Your draft will be deleted.
<md-gb-button slot="actions">Cancel</md-gb-button>
<md-gb-button slot="actions">Discard</md-gb-button>
</md-gb-dialog>Examples
Link to “Examples”With an icon
Link to “With an icon”Put an md-gb-icon in the icon slot to center the headline under a hero icon.
<md-gb-button id="open-reset">Reset</md-gb-button>
<md-gb-dialog id="reset-dialog">
<md-gb-icon slot="icon">restart_alt</md-gb-icon>
<span slot="headline">Reset settings?</span>
This returns your preferences to their defaults.
<form id="reset-form" method="dialog"></form>
<md-gb-button slot="actions" form="reset-form" value="cancel">Cancel</md-gb-button>
<md-gb-button slot="actions" form="reset-form" value="reset">Reset</md-gb-button>
</md-gb-dialog>document.querySelector('#open-reset').addEventListener('click', () => {
document.querySelector('#reset-dialog').show();
});Full-screen
Link to “Full-screen”Set full-screen for a dialog that fills a compact window, with a close button and the confirming action in its header. Above compact sizes it falls back to a basic dialog; add always-full-screen to keep it.
<md-gb-button id="open-event">New event</md-gb-button>
<md-gb-dialog id="event-dialog" full-screen>
<span slot="headline">New event</span>
<md-gb-button slot="actions">Save</md-gb-button>
<label>
Event name
<input type="text">
</label>
</md-gb-dialog>document.querySelector('#open-event').addEventListener('click', () => {
document.querySelector('#event-dialog').show();
});Return value
Link to “Return value”A button's value becomes the dialog's returnValue when it closes the dialog through its form. Read it in the closed event.
<md-gb-button id="open-archive">Archive</md-gb-button>
<p id="result" role="status"></p>
<md-gb-dialog id="archive-dialog">
<span slot="headline">Archive this thread?</span>
It moves out of your inbox.
<form id="archive-form" method="dialog"></form>
<md-gb-button slot="actions" form="archive-form" value="cancel">Cancel</md-gb-button>
<md-gb-button slot="actions" form="archive-form" value="archive">Archive</md-gb-button>
</md-gb-dialog>const dialog = document.querySelector('#archive-dialog');
document.querySelector('#open-archive').addEventListener('click', () => {
dialog.show();
});
dialog.addEventListener('closed', () => {
document.querySelector('#result').textContent =
dialog.returnValue === 'archive' ? 'Archived' : 'Canceled';
});Opening and closing
Link to “Opening and closing”Open and close a dialog with show() and close(), or by setting open. Both methods return a promise that resolves after the animation. Cancel the cancel event to keep the dialog open.
<md-gb-button id="open">Open</md-gb-button>
<md-gb-dialog id="note-dialog">
<span slot="headline">Reminder</span>
This dialog closes itself after three seconds.
<md-gb-button slot="actions" id="close">Close now</md-gb-button>
</md-gb-dialog>const dialog = document.querySelector('#note-dialog');
document.querySelector('#open').addEventListener('click', async () => {
await dialog.show();
setTimeout(() => dialog.close(), 3000);
});
document.querySelector('#close').addEventListener('click', () => dialog.close());Accessibility
Link to “Accessibility”- The headline names the dialog. Add
aria-labelto a dialog without a headline. - A basic dialog is an alert dialog (
role="alertdialog") by default, as M3 asks for on the web. Settype="dialog"for a plain dialog. - Focus moves into the dialog and Tab cycles inside it. Escape closes it and focus returns to what opened it.
- Label buttons and fields inside the dialog as you would elsewhere. In a full-screen dialog, set
close-labelto name the close button.
Compatibility
Link to “Compatibility”Material Design 3Spec checked91% tokens
124 of 244 buildable spec units are tested, 19 are excluded with a written reason and 0 are uncovered (the target is 0). 41 of 45 token declarations match the spec (91%), and 4 have no spec token.
dialogs on m3.material.io (opens in a new tab) How compliance is measured
BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4
The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.
Newer features it uses where the browser has them (progressive enhancements):
- @starting-style (opens in a new tab) Newly available degrades safely where it is missing
- overscroll-behavior (opens in a new tab) Limited availability degrades safely where it is missing
- scrollbar-color (opens in a new tab) Newly available degrades safely where it is missing
- scrollbar-gutter (opens in a new tab) Newly available degrades safely where it is missing
- scrollbar-width (opens in a new tab) Newly available degrades safely where it is missing
Browser support Learn more about Baseline (opens in a new tab)
WAI-ARIAaxe and ARIA 1.3 passAlert and Message DialogsButton
Roles the component renders: alertdialog (opens in a new tab), button (opens in a new tab), dialog (opens in a new tab), separator (opens in a new tab).
Follows the WAI-ARIA Authoring Practices: Alert and Message Dialogs (opens in a new tab), Button (opens in a new tab), Dialog (Modal) (opens in a new tab).
3 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.
WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility
Lighthouse91 · 100 · 100 · 100
Performance Accessibility Best practices SEO
Audits under 90:
- First Contentful Paint
- Largest Contentful Paint
- Largest Contentful Paint element
- Eliminate render-blocking resources
- Minify JavaScript
- Reduce unused CSS
- Enable text compression
- Network dependency tree
- Render blocking requests
Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.
API reference
Link to “API reference”<md-gb-dialog>
Link to “<md-gb-dialog>”A Material Design dialog component.
Properties
Link to “Properties”| Property | Attribute | Type | Default |
|---|---|---|---|
alwaysFullScreenFull-screen dialogs are for compact windows only (dialogs.md: use a basic dialog at medium and expanded). So full-screen applies at compact windows and the dialog is a basic dialog above, with the same slots. The host gets adaptive-basic while it falls back. Set always-full-screen to keep the full-screen variant at every window size. |
always-full-screen |
boolean |
false |
closeLabelAccessible label of the full-screen close icon button. |
close-label |
string |
'Close' |
fullScreenUses the full-screen variant: the dialog fills the window, with a header holding a close icon button, the headline and the confirm action. Meant for compact windows; use a basic dialog at larger breakpoints. |
full-screen |
boolean |
false |
noFocusTrapTurns off focus trapping, which keeps Tab and Shift+Tab cycling inside the dialog. Trapping is recommended for accessibility. |
no-focus-trap |
boolean |
false |
openOpens the dialog when set to true and closes it when set to false. |
open |
boolean |
|
quickSkips the opening and closing animations. |
quick |
boolean |
false |
returnValueThe dialog's return value, usually which button closed it. Set by close(returnValue) and by <form method="dialog"> submitters' value. Canceling (Escape, scrim, close button) leaves it unchanged. https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue |
string |
'' |
|
typeThe dialog's accessibility role. alert (role="alertdialog") or dialog (role="dialog"). When empty, basic dialogs are alert dialogs, as the spec asks for on the web, and full-screen dialogs are dialogs. |
type |
DialogType |
'' |
Slots
Link to “Slots”| Slot | Description |
|---|---|
| default | The supporting text or custom content (lists, form fields). Scrolls between the pinned headline and actions when it overflows. |
actions |
The action buttons, dismissive first and confirming last. Basic: end-aligned below the content. Full-screen: the confirm action at the end of the header. |
headline |
The headline. Labels the dialog (aria-labelledby). |
icon |
An optional hero icon above the headline (basic only). Centers the headline. |
Events
Link to “Events”| Event | Description |
|---|---|
cancelEvent |
Fired when the dialog is canceled with Escape, a scrim click or the full-screen close button. Cancelable; canceling keeps the dialog open. |
closeEvent |
Fired when the dialog begins closing; returnValue is already set. Cancelable. |
closedEvent |
Fired when the dialog has closed and animations finished. |
openEvent |
Fired when the dialog begins opening. Cancelable. |
openedEvent |
Fired when the dialog has opened and animations finished. |
Methods
Link to “Methods”| Method | Description |
|---|---|
close(returnValue?: string, reason?: string) => Promise<void> |
Closes the dialog and fires a cancelable close event, then closed after the exit animation. Focus returns to the element focused before the dialog opened. |
show() => Promise<void> |
Opens the dialog as a modal and fires a cancelable open event, then opened after the enter animation. Focus moves to the first child with an autofocus attribute, else the first focusable element, else the dialog. |
CSS parts
Link to “CSS parts”| Part | Description |
|---|---|
::part(actions) |
The actions container. |
::part(close-button) |
The full-screen close icon button. |
::part(content) |
The content container. |
::part(header) |
The headline region (full-screen: the header bar). |
::part(headline) |
The headline element. |
::part(icon) |
The hero icon container. |
::part(scroller) |
The scroll container of the content. |
CSS custom properties
Link to “CSS custom properties”| Property | Description |
|---|---|
--action-focus-label-text-color |
Action label text color when focused. |
--action-hover-label-text-color |
Action label text color when hovered. |
--action-label-text |
Action label typography. |
--action-label-text-axes |
Action label typography font variation settings. |
--action-label-text-color |
Action label text color. |
--action-label-text-tracking |
Action label letter spacing. |
--action-pressed-label-text-color |
Action label text color when pressed. |
--container-color |
Container background color. |
--container-elevation |
Container box shadow elevation. |
--container-shape |
Container border radius. |
--header-action-label-text |
Full-screen action label typography. |
--header-action-label-text-axes |
Full-screen action label typography font variation settings. |
--header-action-label-text-color |
Full-screen action label color. |
--header-action-label-text-tracking |
Full-screen action label letter spacing. |
--header-container-color |
Full-screen header color. |
--header-container-elevation |
Full-screen header elevation. |
--header-container-height |
Full-screen header height. |
--header-headline |
Full-screen headline typography. |
--header-headline-axes |
Full-screen headline typography font variation settings. |
--header-headline-color |
Full-screen headline color. |
--header-headline-tracking |
Full-screen headline letter spacing. |
--header-icon-color |
Full-screen close icon color. |
--header-icon-size |
Full-screen close icon size. |
--header-on-scroll-container-color |
Full-screen header color when the content is scrolled. |
--header-on-scroll-container-elevation |
Full-screen header elevation when the content is scrolled. |
--headline |
Headline typography. |
--headline-axes |
Headline typography font variation settings. |
--headline-color |
Headline color. |
--headline-tracking |
Headline letter spacing. |
--max-width |
Basic dialog maximum width. |
--min-width |
Basic dialog minimum width. |
--scrim-color |
Scrim color. |
--scrim-opacity |
Scrim opacity. |
--supporting-text |
Supporting text typography. |
--supporting-text-axes |
Supporting text typography font variation settings. |
--supporting-text-color |
Supporting text color. |
--supporting-text-tracking |
Supporting text letter spacing. |
--with-icon-icon-color |
Hero icon color. |
--with-icon-icon-size |
Hero icon size. |