Installation

Barrel

// code example

Granular

// code example

Usage

export default function Example() {
  return (
    <Dialog.Root>
      <Dialog.Trigger render={(p) => <Button {...p}>Open</Button>} />
      <Dialog>
        <Dialog.Title>Dialog Title</Dialog.Title>
        <Dialog.Description>Dialog content goes here.</Dialog.Description>
        <div className="flex justify-end gap-2 mt-4">
          <Dialog.Close
            render={(p) => (
              <Button variant="secondary" {...p}>
                Cancel
              </Button>
            )}
/>
        </div>
      </Dialog>
    </Dialog.Root>
  );
}

Dialog vs Alert Dialog

The Dialog component supports two ARIA roles to properly convey semantic
meaning to assistive technologies:



<table class="w-full text-sm">
  <thead class="bg-kumo-elevated">
    <tr>
      <th class="px-4 py-3 text-left font-medium">Role</th>
      <th class="px-4 py-3 text-left font-medium">Use Case</th>
      <th class="px-4 py-3 text-left font-medium">Behavior</th>
    </tr>
  </thead>
  <tbody class="divide-y divide-kumo-hairline">
    <tr>
      <td class="px-4 py-3">
        `role="dialog"`
        (default)
      </td>
      <td class="px-4 py-3">
        General-purpose modals, forms, content display
      </td>
      <td class="px-4 py-3">Dismissible by default</td>
    </tr>
    <tr>
      <td class="px-4 py-3">`role="alertdialog"`</td>
      <td class="px-4 py-3">
        Destructive actions, confirmations, critical warnings
      </td>
      <td class="px-4 py-3">Requires explicit user acknowledgment</td>
    </tr>
  </tbody>
</table>

Examples

Basic Dialog

Alert Dialog (role="alertdialog")

For destructive or confirmation dialogs, use role="alertdialog" on Dialog.Root. This provides proper accessibility semantics by rendering the dialog with role="alertdialog" instead of role="dialog".

When to use role="alertdialog":

• Destructive actions (delete, discard, remove)
• Confirmation flows requiring explicit user acknowledgment
• Actions that cannot be undone
• Critical warnings or errors

Confirmation Dialog (with disablePointerDismissal)

For confirmation dialogs that should not be dismissed by clicking outside, use disablePointerDismissal on Dialog.Root. This can be combined with role="alertdialog" for proper accessibility.

With Actions

With Select

Dialog containing a Select dropdown.

With Combobox

Dialog containing a Combobox for searchable selection.

With Dropdown

Dialog containing a Dropdown menu.

API Reference

Dialog

The main dialog container that renders the modal overlay and popup.

Dialog.Root

Controls the open state of the dialog. Doesn't render its own HTML element.

Dialog.Trigger

A button that opens the dialog when clicked.

Dialog.Title

A heading that labels the dialog for accessibility.

Dialog.Description

A paragraph providing additional context about the dialog.

Dialog.Close

A button that closes the dialog when clicked.