Dialog
A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
Features
- Fully managed focus
- Can be controlled or uncontrolled
- Esc closes the component automatically
Anatomy
At a high level, the anatomy of a dialog looks like this:
- Trigger: The button(s) that open the dialog
- Portalled: The container that is portalled (to
body
, by default) - Overlay: The dim background that is typically behind a dialog element.
- Content: Container for the content within the dialog.
- Title: The title of the dialog
- Description: The description which supports the title
- Close: The button(s) that close the dialog
Usage
To create a dialog, use the createDialog
builder function. You can then reference the anatomy,
example above, or the Example Components below to create your dialog.
Dialog vs. Alert Dialog
You should use a dialog to display content that isn't critical to the user's workflow. For example, a user may need to select a color or a chart, but the chart will still be displayed even if the user does not select a color. In this case, a dialog would be appropriate.
On the other hand, an alert dialog should be used to display content that is critical to the user's workflow. For example, a user may need to confirm a decision before proceeding. In this case, an alert dialog would be appropriate.
By default, we set the role
attribute to dialog
. If you want it to be considered an alert
dialog, you can set the role
builder prop to alertdialog
.
Disable Scroll Prevention
By default, scrolling is prevented on the body when a dialog is open. You can disable this behavior
by setting the preventScroll
builder prop to false
.
Disable Close on Outside Click
By default, clicking outside of the dialog will close it. You can disable this behavior by setting
the closeOnOutsideClick
builder prop to false
.
Disable Close on Escape
By default, pressing the escape key will close the dialog. You can disable this behavior by setting
the escapeBehavior
builder prop to ignore
.
Example Components
Drawer
An overlay window can display various content, including dialogs, drawers, sidebars, and more. For example, here's a drawer component that slides in from the left side of the screen. A drawer could be used for a navigation menu, a settings panel, or any other content that you want to display in a drawer.
Alert Dialog
It's common to use a dialog as a pop-up decision window or alert dialog. For example, here's a pop-up that asks the user to confirm a decision.
Nested Dialogs
Dialogs can be nested. For example, here's a dialog that opens another dialog.
API Reference
createDialog
The builder function used to create the dialog component.
Props
Prop | Default | Type / Description |
role | 'dialog' | 'dialog' | 'alertdialog' The |
preventScroll | true | boolean Whether or not to prevent scrolling of the document when the dialog is open. |
escapeBehavior | 'close' | 'close' | 'ignore' | 'defer-otherwise-close' | 'defer-otherwise-ignore' Defines how the dialog reacts when the Escape key is pressed. close : Closes the dialog immediately.ignore : Prevents the dialog from closing and also blocks the parent element from closing in response to the Escape key.defer-otherwise-close : Delegates the action to the parent element. If no parent is found, it closes the element.defer-otherwise-ignore : Delegates the action to the parent element. If no parent is found, nothing is done. |
closeOnOutsideClick | true | boolean Whether or not to close the dialog when the user clicks outside of it. |
portal | body | string | HTMLElement | null The element or selector to render the dialog into. Nested floating elements are automatically rendered into their own portal if not specified. Pass in |
forceVisible | false | boolean Whether or not to force the dialog to always be visible. This is useful for custom transitions and animations using conditional blocks. |
openFocus | - | Override the default focus behavior on open |
closeFocus | - | Override the default focus behavior on close |
defaultOpen | false | boolean Whether the dialog is open by default or not. |
open | - | Writable<boolean> A writable store that controls whether or not the dialog is open. |
onOpenChange | - | ChangeFn<boolean> A callback called when the value of the See Change Functions |
ids | - | Record<'content' | 'title' | 'description', string> Override the internally generated ids for the elements. |
Elements
Element | Description |
The builder store used to create the dialog trigger. | |
The builder store used to create the portalled dialog container. | |
The builder store used to create the dialog overlay. | |
The builder store used to create the dialog content. | |
The builder store used to create the dialog close button. | |
The builder store used to create the dialog title. | |
The builder store used to create the dialog description. |
States
State | Description |
open | A writable store with the open state of the dialog. |
Options
Option | Description |
role | The |
preventScroll | Whether or not to prevent scrolling of the document when the dialog is open. |
escapeBehavior | Defines how the dialog reacts when the Escape key is pressed. close : Closes the dialog immediately.ignore : Prevents the dialog from closing and also blocks the parent element from closing in response to the Escape key.defer-otherwise-close : Delegates the action to the parent element. If no parent is found, it closes the element.defer-otherwise-ignore : Delegates the action to the parent element. If no parent is found, nothing is done. |
closeOnOutsideClick | Whether or not to close the dialog when the user clicks outside of it. |
portal | The element or selector to render the dialog into. Nested floating elements are automatically rendered into their own portal if not specified. Pass in |
forceVisible | Whether or not to force the dialog to always be visible. This is useful for custom transitions and animations using conditional blocks. |
openFocus | Override the default focus behavior on open |
closeFocus | Override the default focus behavior on close |
IDs
Option | Description |
content | The writable store that represents the id of the |
title | The writable store that represents the id of the |
description | The writable store that represents the id of the |
trigger
The element which triggers the dialog to open when clicked or pressed.
Data Attributes
Data Attribute | Value |
[data-melt-dialog-trigger] | Present on all trigger elements. |
Custom Events
Event | Value |
m-click | (e: ) => void |
m-keydown | (e: ) => void |
portalled
The element that will be portalled (or moved) to a different location in the DOM based on the portal
prop value.
Data Attributes
Data Attribute | Value |
[data-portal] | Present on all portalled elements. |
[data-melt-dialog-portalled] | Present on all portalled elements. |
overlay
The overlay element which covers the page when the dialog is open.
Data Attributes
Data Attribute | Value |
[data-state] |
|
[data-melt-dialog-overlay] | Present on all overlay elements. |
content
The element displayed within the dialog when it is open.
Data Attributes
Data Attribute | Value |
[data-state] |
|
[data-melt-dialog-content] | Present on all content elements. |
close
The element which closes the dialog when clicked or pressed.
Data Attributes
Data Attribute | Value |
[data-melt-dialog-close] | Present on all close elements. |
Custom Events
Event | Value |
m-click | (e: ) => void |
m-keydown | (e: ) => void |
title
The title of the dialog. Used for accessibility purposes.
Data Attributes
Data Attribute | Value |
[data-melt-dialog-title] | Present on all title elements. |
description
The description of the dialog. Used for accessibility purposes.
Data Attributes
Data Attribute | Value |
[data-melt-dialog-description] | Present on all description elements. |
Accessibility
Adheres to the Dialog WAI-ARIA design pattern and Alert Dialog WAI-ARIA design pattern
Key | Behavior |
Space | Opens/closes the dialog. |
Enter | Opens/closes the dialog. |
Tab | Moves focus to the next focusable element within the dialog. |
Shift + Tab | Moves focus to the previous focusable element within the dialog. |
Esc | Closes the dialog and moves focus to the trigger element. |
On This Page