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.

Outside Scroll

Set scroll="outside" on DialogContent to let the popup grow past the viewport and scroll the area around it instead.

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.

Persistent Close Button

Combine scroll="outside" with the transparent frame above to keep the close button in the corner of the screen while the card scrolls past it.

The button stays inside DialogContent so it remains in the focus trap, which puts it inside the scroll area too. sticky is what pins it there; fixed would resolve against the popup, not the viewport, because the popup carries a transform for nested dialogs. It needs a gutter to sit in, so below sm it falls back into the card and scrolls away with the header.

Accessibility

Base UI handles the dialog role, labelling, focus trapping, and Escape. One thing is layered on top:

scroll="outside" moves initial focus to the popup itself rather than the first focusable child. Without it the browser scrolls whatever it focuses into view, so a tall dialog can open part-way down its own content. The popup's focus ring is suppressed in this mode because focus lands there on open rather than by user action. Pass initialFocus to choose a different target.

The close button sits at the top of the card, so under scroll="outside" it scrolls out of view on a tall dialog. Escape still closes it. Give a long dialog a footer close action, or see Persistent Close Button for one that stays on screen.

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.