On this page
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
| Guidance | Practice |
|---|---|
| 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 | Description |
|---|---|---|
role | 'dialog' | 'alertdialog' | dialog, or alertdialog for an interruption that needs an answer.Default: 'dialog' |
shouldCloseOnInteractOutside | boolean | Whether an outside press closes the dialog. Always false for alertdialog.Default: true for 'dialog', false for 'alertdialog' |
showCloseButton | boolean | Whether the surface renders its dismiss.Default: true for 'dialog', false for 'alertdialog' |
Dialog.Trigger
Opens the dialog.
| Prop | Type | 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 | Description |
|---|---|---|
variant | 'card' | 'profile' | 'fullscreen' | card for a Card, profile for a Profile at full height, fullscreen for a Profile filling the viewport.Default: 'card' |
compactPlacement | 'sheet' | 'center' | Under 40rem, sheet anchors to the bottom edge and center keeps it centered. card only.Default: 'sheet' |
initialFocus | DialogFocusTarget | Where focus moves on open.Default: the first tabbable element |
finalFocus | DialogFocusTarget | Where focus returns on close.Default: the trigger |
Dialog.Close
A button that closes the dialog.
Dialog.CloseButton
The icon dismiss button.
Slot: cl-dialog-close-button
| Prop | Type | Description |
|---|---|---|
aria-label | string | Names the button. Pass a localized string. |
Examples
A controlled dialog
<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>