Dialog

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>

Examples

Controlled

Manage dialog open state programmatically.

With Form

Include form elements within the dialog.

Scrollable Content

Handle long content with scrolling.

No Close Button

Hide the default close button.

Nested Dialogs

Stack multiple dialogs on top of each other.

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.