# Dialog

A modal surface over the page. The popup holds a `Card` or a `Profile`, and owns focus, scroll lock and the backdrop.

## Use for

- a modal over the page
- a dialog opened from a trigger elsewhere in the tree, with `createHandle`
- an alert that needs an answer

## Practices

- Do: Put a `Card.Root` in `Dialog.Popup`, with `Card.Title` to name the dialog.
- Do: Use `role='alertdialog'` for a question the user must answer. It never closes on an outside press.
- Do: Pass `shouldCloseOnInteractOutside={false}` when an accidental press would throw work away.
- Don't: Build a confirm dialog by hand. Use `useConfirmController` with `Confirmation` or `Destructive`.

## API reference

### Dialog.Root

Owns the open state, the role and how the dialog dismisses. Escape always closes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `role` | `'dialog' \| 'alertdialog'` | `'dialog'` | `dialog`, or `alertdialog` for an interruption that needs an answer. |
| `shouldCloseOnInteractOutside` | `boolean` | `true for 'dialog', false for 'alertdialog'` | Whether an outside press closes the dialog. Always `false` for `alertdialog`. |
| `showCloseButton` | `boolean` | `true for 'dialog', false for 'alertdialog'` | Whether the surface renders its dismiss. |

### Dialog.Trigger

Opens the dialog.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DialogHandle<Payload>` |  | Connects a trigger to a root rendered elsewhere. Create with `Dialog.createHandle()`. |
| `payload` | `Payload` |  | Delivered to the root's children-as-function as `{ payload }`. |

### Dialog.Popup

Renders the backdrop, viewport and popup.

Slot: `cl-dialog-popup`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'card' \| 'profile' \| 'fullscreen'` | `'card'` | `card` for a `Card`, `profile` for a `Profile` at full height, `fullscreen` for a `Profile` filling the viewport. |
| `compactPlacement` | `'sheet' \| 'center'` | `'sheet'` | Under `40rem`, `sheet` anchors to the bottom edge and `center` keeps it centered. `card` only. |
| `initialFocus` | `DialogFocusTarget` | `the first tabbable element` | Where focus moves on open. |
| `finalFocus` | `DialogFocusTarget` | `the trigger` | Where focus returns on close. |

### Dialog.Close

A button that closes the dialog.

### Dialog.CloseButton

The icon dismiss button.

Slot: `cl-dialog-close-button`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Names the button. Pass a localized string. |

## Examples

### A controlled dialog

```tsx
<Dialog.Root open={open} onOpenChange={onOpenChange}>
  <Dialog.Popup>
    <Card.Root elevation='overlay'>
      <Card.Header>
        <Card.Title>{m.title}</Card.Title>
      </Card.Header>
    </Card.Root>
  </Dialog.Popup>
</Dialog.Root>
```

## Related

- [Card](/docs/components/card.md)
- `useConfirmController`
- [Drawer](/docs/components/drawer.md)
