Dialog

A dialog is a modal window that overlays the page and waits for the user to act. Use it for focused tasks like confirming a destructive action, editing a record, or completing a short form without leaving the current view.

Preview

Installation

npx shadcn@latest add @cubby-ui/dialog

Usage

import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/cubby-ui/dialog";

<Dialog>
  <DialogTrigger />
  <DialogContent>
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogBody />
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogContent>
</Dialog>

Composition

Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    ├── DialogBody
    └── DialogFooter
        └── DialogClose

DialogContent composes the portal, viewport, backdrop, and popup internally, so you wrap your content directly inside it.

Examples

Controlled

Use open and onOpenChange on Dialog to drive open state yourself.

With Form

Place form elements inside DialogBody and close on submit.

Scrollable Content

DialogBody scrolls its content while the header and footer stay pinned.

No Close Button

Set showCloseButton={false} on DialogContent to hide the default close button.

Nested Dialogs

Open a dialog from within another to stack them.

Inset Footer

Use the inset variant for a muted footer background that extends to the dialog edges.

Detached Trigger

Place the trigger outside of the Dialog component using createDialogHandle().

Non-Modal

Pass modal={false} for a floating dialog that keeps the page interactive. The backdrop is hidden, pointer events pass through the empty area around the popup, and outside clicks don't dismiss the dialog.

Elements Outside Popup

Place elements visually outside the popup card while keeping them inside the popup component for accessibility (tab order, screen reader support). The popup uses pointer-events: none so backdrop clicks work, while inner content uses pointer-events: auto.

API Reference

The Dialog component is built on top of Base UI's Dialog. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Dialog documentation.

Utilities

createDialogHandle

Creates a handle that connects a dialog to one or more external DialogTrigger components. Useful when the triggers need to live outside the Dialog, for example when each row in a list has its own trigger but they all share one dialog.

import { createDialogHandle } from "@/registry/default/dialog/dialog";
 
const handle = createDialogHandle();

Passing data from the trigger to the dialog

The handle accepts an optional <Payload> generic that types a value each trigger can pass along. The dialog reads it through a render-prop child, so you can render different content per trigger without duplicating the dialog markup.

type User = { id: string; name: string };
 
const handle = createDialogHandle<User>();
 
// Multiple triggers, each with its own payload:
users.map((user) => (
  <DialogTrigger key={user.id} handle={handle} payload={user}>
    Edit {user.name}
  </DialogTrigger>
));
 
// One shared dialog that renders based on the active trigger:
<Dialog handle={handle}>
  <DialogContent>
    {({ payload: user }) => (
      <DialogHeader>
        <DialogTitle>{user?.name}</DialogTitle>
      </DialogHeader>
    )}
  </DialogContent>
</Dialog>;

Without the <User> generic, payload inside the render prop resolves to unknown.

Props

Dialog

Root component. Forwards all props to Base UI's Dialog.Root, with modified defaults for the modal prop.

DialogContent

Dialog container with centered positioning. Composes Dialog.Portal, Dialog.Viewport, and Dialog.Popup. Also renders Dialog.Backdrop when the dialog is modal. Props are forwarded to Dialog.Popup.

DialogBody

Scrollable content area within the dialog.