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

GuidancePractice
DoPut a Card.Root in Dialog.Popup, with Card.Title to name the dialog.
DoUse role='alertdialog' for a question the user must answer. It never closes on an outside press.
DoPass shouldCloseOnInteractOutside={false} when an accidental press would throw work away.
Don’tBuild 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.

PropTypeDescription
role'dialog' | 'alertdialog'dialog, or alertdialog for an interruption that needs an answer.Default: 'dialog'
shouldCloseOnInteractOutsidebooleanWhether an outside press closes the dialog. Always false for alertdialog.Default: true for 'dialog', false for 'alertdialog'
showCloseButtonbooleanWhether the surface renders its dismiss.Default: true for 'dialog', false for 'alertdialog'

Dialog.Trigger

Opens the dialog.

PropTypeDescription
handleDialogHandle<Payload>Connects a trigger to a root rendered elsewhere. Create with Dialog.createHandle().
payloadPayloadDelivered to the root's children-as-function as { payload }.

Dialog.Popup

Renders the backdrop, viewport and popup.

Slot: cl-dialog-popup

PropTypeDescription
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'
initialFocusDialogFocusTargetWhere focus moves on open.Default: the first tabbable element
finalFocusDialogFocusTargetWhere 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

PropTypeDescription
aria-labelstringNames 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>