# 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

- 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 | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Whether the dialog is open, when controlled. |
| `defaultOpen` | `boolean` | `false` | Whether the dialog is open on mount, when uncontrolled. |
| `onOpenChange` | `(open: boolean, details: DialogOpenChangeDetails) => void` |  | Called with the new open state and `details` naming the trigger and event behind it. |
| `modal` | `boolean` | `true` | Traps focus and blocks the rest of the page. |
| `closedBy` | `DialogClosedBy` | `'any'` | `any` closes on Escape and outside press, `closerequest` on Escape only, `none` only programmatically. |
| `role` | `DialogRole` | `'dialog'` | `dialog` or `alertdialog` for the popup. |
| `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 | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DialogHandle<Payload>` |  | Drives a root rendered elsewhere. Not needed inside a root. |
| `id` | `string` | `a generated id` | Names the trigger for the root's `triggerId`. |
| `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 | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| React.RefObject<HTMLElement \| null>` | `` the `PortalProvider` container, else `document.body` `` | The element to portal into. |

### 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 | Default | Description |
| --- | --- | --- | --- |
| `lockScroll` | `boolean` | `true` | Locks body scroll while open. |
| `overlay` | `boolean` | `true` | Set `false` to render in flow, with no fixed overlay and no scroll lock. |

### 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 | Default | Description |
| --- | --- | --- | --- |
| `initialFocus` | `DialogFocusTarget` | `the first tabbable element` | Where focus goes on open: `true`, `false`, a ref, or a function of the interaction type. |
| `finalFocus` | `DialogFocusTarget` | `the trigger, unless a pointer closed it` | Where focus goes on close, in the same forms as `initialFocus`. |

### 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>
```

## Related

- [Drawer](/docs/components/drawer.md)
- [Popover](/docs/components/popover.md)
