Skip to content
Mosaic
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

GuidancePractice
Don’tUse the primitive in a feature. Use the styled Dialog from src/components/dialog instead.
DoRender Dialog.Popup inside Dialog.Viewport, which owns the fixed overlay and scroll lock.
DoPass closedBy='closerequest' when the dialog holds input or confirms a destructive action, so a stray outside press does not discard it.
DoStyle a stack with data-stacked and data-stack-base, not data-nested, which any floating ancestor such as a menu sets.
DoType 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.
DoFor an inline dialog, pass overlay={false} on the viewport, modal={false} and closedBy='none' on the root, and initialFocus={false} on the popup.
Don’tUse 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.

PropTypeDescription
openbooleanWhether the dialog is open, when controlled.
defaultOpenbooleanWhether the dialog is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean, details: DialogOpenChangeDetails) => voidCalled with the new open state and details naming the trigger and event behind it.
modalbooleanTraps focus and blocks the rest of the page.Default: true
closedByDialogClosedByany closes on Escape and outside press, closerequest on Escape only, none only programmatically.Default: 'any'
roleDialogRoledialog or alertdialog for the popup.Default: 'dialog'
handleDialogHandle<Payload>Connects triggers rendered outside the root. From Dialog.createHandle().
triggerIdstring | nullThe trigger the open is attributed to, when controlled. Focus returns to it on close.
childrenReactNode | ((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.

PropTypeDescription
handleDialogHandle<Payload>Drives a root rendered elsewhere. Not needed inside a root.
idstringNames the trigger for the root's triggerId.Default: a generated id
payloadPayloadData the root's children function receives when this trigger opens it.

Dialog.Portal

Portals its children while the dialog is mounted.

PropTypeDescription
rootHTMLElement | 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.

PropTypeDescription
lockScrollbooleanLocks body scroll while open.Default: true
overlaybooleanSet 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.

PropTypeDescription
initialFocusDialogFocusTargetWhere focus goes on open: true, false, a ref, or a function of the interaction type.Default: the first tabbable element
finalFocusDialogFocusTargetWhere 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

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

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