On this page
Dialog
Headless, unstyled dialog over the page, modal or not. Traps focus, locks scroll, wires aria-labelledby and aria-describedby, and keeps the popup mounted through its exit transition. Nested dialogs stack. Dialog.createHandle() connects a root to triggers rendered outside it.
Use for
- the base for a styled modal or sheet
- a dialog opened from a trigger elsewhere in the tree
- one dialog that renders per-trigger content from a payload
- a dialog presented inline in a page slot
Practices
| Guidance | Practice |
|---|---|
| Don’t | Use the primitive in a feature. Use the styled Dialog from src/components/dialog instead. |
| Do | Render Dialog.Popup inside Dialog.Viewport, which owns the fixed overlay and scroll lock. |
| Do | Pass closedBy='closerequest' when the dialog holds input or confirms a destructive action, so a stray outside press does not discard it. |
| Do | Style a stack with data-stacked and data-stack-base, not data-nested, which any floating ancestor such as a menu sets. |
| Do | Type a payload through the handle, Dialog.createHandle<Payload>(). It is captured at open, so for data that changes while open pass an id and read live state. |
| Do | For an inline dialog, pass overlay={false} on the viewport, modal={false} and closedBy='none' on the root, and initialFocus={false} on the popup. |
| Don’t | Use closedBy='none' unless the user must finish or acknowledge. It removes the Escape exit. |
API reference
Dialog.Root
Holds the open state, the active trigger and its payload. Renders no element.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the dialog is open, when controlled. |
defaultOpen | boolean | Whether the dialog is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean, details: DialogOpenChangeDetails) => void | Called with the new open state and details naming the trigger and event behind it. |
modal | boolean | Traps focus and blocks the rest of the page.Default: true |
closedBy | DialogClosedBy | any closes on Escape and outside press, closerequest on Escape only, none only programmatically.Default: 'any' |
role | DialogRole | dialog or alertdialog for the popup.Default: 'dialog' |
handle | DialogHandle<Payload> | Connects triggers rendered outside the root. From Dialog.createHandle(). |
triggerId | string | null | The trigger the open is attributed to, when controlled. Focus returns to it on close. |
children | ReactNode | ((ctx: { payload: Payload | undefined }) => ReactNode) | Content, or a function of { payload } from the active trigger or handle.open(payload). |
Dialog.Trigger
A button that toggles the dialog and gets focus back on close. Carries aria-haspopup="dialog", aria-expanded, aria-controls while open, and data-open or data-closed.
| Prop | Type | Description |
|---|---|---|
handle | DialogHandle<Payload> | Drives a root rendered elsewhere. Not needed inside a root. |
id | string | Names the trigger for the root's triggerId.Default: a generated id |
payload | Payload | Data the root's children function receives when this trigger opens it. |
Dialog.Portal
Portals its children while the dialog is mounted.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | null | React.RefObject<HTMLElement | null> | The element to portal into.Default: the `PortalProvider` container, else `document.body` |
Dialog.Backdrop
A div behind the popup. Carries data-open or data-closed, data-nested and data-stacked.
Dialog.Viewport
A fixed div that centers the popup and locks scroll. Carries data-open or data-closed, and data-nested.
| Prop | Type | Description |
|---|---|---|
lockScroll | boolean | Locks body scroll while open.Default: true |
overlay | boolean | Set false to render in flow, with no fixed overlay and no scroll lock.Default: true |
Dialog.Popup
The dialog div, with its role and ARIA wiring, inside the focus manager. Carries data-nested, data-stacked and data-stack-base. Its children freeze at their last frame while it exits.
| Prop | Type | Description |
|---|---|---|
initialFocus | DialogFocusTarget | Where focus goes on open: true, false, a ref, or a function of the interaction type.Default: the first tabbable element |
finalFocus | DialogFocusTarget | Where focus goes on close, in the same forms as initialFocus.Default: the trigger, unless a pointer closed it |
Dialog.Title
An h2 that names the popup through aria-labelledby.
Dialog.Description
A p that describes the popup through aria-describedby.
Dialog.Close
A button that closes the dialog.
Examples
A modal
<Dialog.Root>
<Dialog.Trigger>Open</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Backdrop />
<Dialog.Viewport>
<Dialog.Popup>
<Dialog.Title>Confirm</Dialog.Title>
<Dialog.Close>Cancel</Dialog.Close>
</Dialog.Popup>
</Dialog.Viewport>
</Dialog.Portal>
</Dialog.Root>A detached trigger with a payload
const detail = Dialog.createHandle<{ name: string }>();
<Dialog.Trigger handle={detail} payload={{ name: 'Alice' }}>Alice</Dialog.Trigger>
<Dialog.Root handle={detail}>
{({ payload }) => (
<Dialog.Portal>
<Dialog.Backdrop />
<Dialog.Viewport>
<Dialog.Popup>
<Dialog.Title>{payload?.name}</Dialog.Title>
</Dialog.Popup>
</Dialog.Viewport>
</Dialog.Portal>
)}
</Dialog.Root>