Skip to main content brightness_auto motion_photos_off palette download more_vert
toc

Dialogs

Dialogs provide important prompts in a user flow.

HTMLJS
<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>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-dialog.json (setup)

  • 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.

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>

Put an md-gb-icon in the icon slot to center the headline under a hero icon.

HTMLJS
<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>

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.

HTMLJS
<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>

A button's value becomes the dialog's returnValue when it closes the dialog through its form. Read it in the closed event.

HTMLJS
<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>

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.

HTMLJS
<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>
  • The headline names the dialog. Add aria-label to a dialog without a headline.
  • A basic dialog is an alert dialog (role="alertdialog") by default, as M3 asks for on the web. Set type="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-label to name the close button.
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.

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):

WAI-ARIAaxe and ARIA 1.3 passAlert and Message DialogsButton
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.

A Material Design dialog component.

Property Attribute Type Default
alwaysFullScreen
Full-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
closeLabel
Accessible label of the full-screen close icon button.
close-label string 'Close'
fullScreen
Uses 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
noFocusTrap
Turns off focus trapping, which keeps Tab and Shift+Tab cycling inside the dialog. Trapping is recommended for accessibility.
no-focus-trap boolean false
open
Opens the dialog when set to true and closes it when set to false.
open boolean
quick
Skips the opening and closing animations.
quick boolean false
returnValue
The 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 ''
type
The 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 ''
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.
Event Description
cancel
Event
Fired when the dialog is canceled with Escape, a scrim click or the full-screen close button. Cancelable; canceling keeps the dialog open.
close
Event
Fired when the dialog begins closing; returnValue is already set. Cancelable.
closed
Event
Fired when the dialog has closed and animations finished.
open
Event
Fired when the dialog begins opening. Cancelable.
opened
Event
Fired when the dialog has opened and animations finished.
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.
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.
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.
Install Material Web 3.0

Your browser did not offer to install the docs as an app. Install them from the browser instead:

Close
Send feedback
Bug Documentation Idea

Opens a new GitHub issue for material-components/material-web in a new tab, with this filled in.

Cancel Open issue