Dialog
Present a labeled modal task with structured content and dismissal.
Anatomy#
Content is portaled and renders inside the overlay element. With overlay={false}, that element is an unstyled wrapper without the overlay slot.
Usage#
Use Dialog for a labeled modal task with title, description, body, and footer. Use BaseDialog when you compose backdrop and content yourself. Use Sheet or Drawer for a panel from a viewport edge. Use Popover for anchored interactive content that should not take over the page. Use Tooltip for a brief non-interactive hint. Use DropdownMenu or ContextMenu for an action list. Use Alert Dialog for confirm, info, warning, error, and success prompts opened from an event handler.
The trigger and content share disclosure state through the root.
Content composition#
Use Content title and description for simple cases:
For a custom header layout, compose the anatomy parts:
An explicit Dialog.Header replaces the header generated by Content’s title and description.
Dialog.Title and Dialog.Description connect their IDs to the surface’s accessible name and
description. Without a visible title, set aria-label or aria-labelledby on Content.
Dialog.Close is an explicit close control you can place inside the root; it is separate from
Content’s automatic corner close button. Set root closable={false} to hide the corner button, or
closeIcon to replace its icon. Its accessible label comes from the close message; override it
with root translations. See Localization. Root transition={false} turns
off the enter and exit animations, so content and overlay unmount as soon as the dialog closes.
Focus and outside interaction#
modal defaults to true: focus stays inside the surface, outside content is hidden from assistive
technology, and native outside pointer actions are prevented. Closing restores focus to the trigger.
Use initialFocus to choose the element that receives focus on open, or false to skip the move,
and finalFocus to choose where focus returns. Both apply only while modal is true.
Setting modal={false} allows focus to leave the surface, but does not disable Escape or outside
dismissal. closeOnOverlayClick and closeOnEscape control those close requests. Both default to
true. Scroll locking is independent: preventScroll defaults to true. For interaction with the
background page, also set preventScroll={false} and overlay={false}.
Styling and portal placement#
Apply class and object style directly to each rendered part. Root classes and styles set
slot defaults for every part: trigger, overlay, content, header, title, description,
contentClose, body, and footer. See
Customization for precedence.
Set root mount to place Content in a chosen container. This also works for controlled
surfaces without a Trigger.
Nested overlays#
Nested roots keep dismissal and focus restoration local to the active layer. Escape closes the topmost dialog or popover, then returns focus to its trigger inside the parent dialog.
State and dismissal#
Use controlled open with onOpenChange when the surrounding flow owns visibility.
closeOnOverlayClick={false} blocks an outside pointer press, and closeOnEscape={false} blocks
Escape. Both report the attempt through onClosePrevented. Provide a clear explicit close path when
either one is blocked.
Structure and lifecycle#
Use root scrollable for long content or fullscreen for a full-viewport task. onExitComplete
runs after the overlay and content finish their exit animations.
Keyboard interaction#
| Key | Description |
|---|---|
| Esc | Requests dismissal when closeOnEscape is not false. |
| ⇥ | Moves focus forward through focusable controls inside the dialog. |
| Shift + Tab | Moves focus backward through focusable controls inside the dialog. |
Examples#
Delete a saved filter#
Keep the filter visible until the user confirms. Cancel and backdrop dismissal leave it intact.
Confirm workspace changes from settings#
Nest a confirmation dialog and a help popover inside a parent dialog. Escape closes the topmost layer and restores focus to its trigger.
Save unsaved configuration#
Own visibility from the page. Toggle closeOnOverlayClick and closeOnEscape together to block
outside clicks and Escape. onClosePrevented counts blocked attempts until Save or Discard.
Read long release notes#
Use scrollable so long content scrolls with the overlay, or fullscreen for a full-viewport
task.
Provision a cluster and wait for exit#
Open a provisioning dialog from its trigger. onExitComplete updates status after overlay and
content finish their exit animations.
Open a dialog from page state#
A page button owns open. The completed-exit count updates after exit motion finishes.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-overlay-scrolldata-transitiondata-footerdata-headerdata-scrollProps#
Dialog#
Trigger#
Renders a <button> element by default.
Content#
Props for Dialog.Content. Renders a <div> element by default.
Header#
Renders a <div> element by default.
Title#
Renders a <h2> element by default.
Description#
Renders a <p> element by default.
Body#
Renders a <div> element by default.
Footer#
Renders a <div> element by default.
Close#
Renders a <button> element by default.