# Dialogs **This documentation is fully rendered on the [Material Web catalog](https://material-web.dev/components/dialog/)** [Dialogs](https://m3.material.io/components/dialogs) provide important prompts in a user flow. A dialog displaying phone ringtone options. * [Design article](https://m3.material.io/components/dialogs) * [API Documentation](#api) * [Source code](https://github.com/material-components/material-web/tree/main/dialog) ## Usage Dialogs behave like [``](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement) elements, and can be closed with a `
` element. Dialogs have three optional sections: the headline title, the main content, and action buttons. ```html
Dialog title
A simple dialog with free-form content.
Ok
``` > Tip: use `margin`, `height`, and `width` CSS properties to control the > dialog's size and position. ### Opening and closing Dialogs are opened and closed by setting the `open` attribute or property. ```html
A dialog that is opened by default.
``` Dialogs are also opened and closed by calling `dialog.show()` and `dialog.close()`. Both return a Promise that resolves after the dialog's animation finishes. ```ts closeButton.addEventListener('click', async () => { await dialog.close(); }); ``` ### Return value A button's value attribute will set the dialog's `returnValue` property to identify which button closed it. ```html
...
Cancel Ok
``` ```ts dialog.addEventListener('close', () => { const cancelClicked = dialog.returnValue === 'cancel'; const okClicked = dialog.returnValue === 'ok'; }); ``` ## Accessibility Dialogs are labelled by their headlines. Add an [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute to dialogs without a headline. ```html
An error occurred, details ...
 ``` ### Alerts Add a [`type="alert"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) attribute to dialogs that need to communicate an important message and require a user's response. Common examples include error messages that require confirmation and other action confirmation prompts. ```html
Confirm deletion
Are you sure you wish to delete this item?
Cancel Delete
``` ## Theming Dialogs supports [Material theming](../theming/README.md) and can be customized in terms of color, typography, and shape. ### Tokens Token | Default value ----------------------------------- | --------------------------------------- `--md-dialog-container-color` | `--md-sys-color-surface-container-high` `--md-dialog-headline-color` | `--md-sys-color-on-surface` `--md-dialog-headline-font` | `--md-sys-typescale-headline-small-font` `--md-dialog-supporting-text-color` | `--md-sys-color-on-surface-variant` `--md-dialog-supporting-text-font` | `--md-sys-typescale-body-medium-font` * [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-dialog.scss) ### Example ```html
Title
Dialog content
 ``` ## API ### MdDialog <md-dialog> #### Properties Property | Attribute | Type | Default | Description --- | --- | --- | --- | --- `returnValue` | | `string` | `''` | Gets or sets the dialog's return value, usually to indicate which button a user pressed to close it.
https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue `type` | `type` | `string` | `undefined` | The type of dialog for accessibility. Set this to `alert` to announce a dialog as an alert dialog. `open` | `open` | `boolean` | `undefined` | `getOpenAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the opening animation for a dialog. Set to a new function to customize the animation. `getCloseAnimation` | | `() => DialogAnimation` | `function { ... }` | Gets the closing animation for a dialog. Set to a new function to customize the animation. #### Methods Method | Parameters | Returns | Description --- | --- | --- | --- `show` | _None_ | `Promise` | Opens the dialog and fires a cancelable `open` event. After a dialog's animation, an `opened` event is fired.
Add an `autocomplete` attribute to a child of the dialog that should receive focus after opening. `close` | `returnValue` | `Promise` | Closes the dialog and fires a cancelable `close` event. After a dialog's animation, a `closed` event is fired. #### Events Event | Description --- | --- `open` | Dispatched when the dialog is opening before any animations. `opened` | Dispatched when the dialog has opened after any animations. `close` | Dispatched when the dialog is closing before any animations. `closed` | Dispatched when the dialog has closed after any animations. `cancel` | Dispatched when the dialog has been canceled by clicking on the scrim or pressing Escape.