Overlays

Dialog

A modal over a blurred backdrop, for a short task that needs the whole of someone's attention. Closes on Escape and outside click.

packages/design-system/components/ui/dialog.tsx

Examples

A form in a dialog. Click to open
No close button, a confirm

Anatomy

  1. 01Backdrop, black/30 with blur
  2. 02Popup, rounded-4xl, max-w-md
  3. 03Header: title and description
  4. 04Body
  5. 05Footer, actions right
  6. 06Close

Usage

import {
  Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger,
} from "@repo/design-system/components/ui/dialog";

<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger render={<Button variant="outline" />}>Send proposal</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Send the proposal</DialogTitle>
      <DialogDescription>We will email a link.</DialogDescription>
    </DialogHeader>
    ...
    <DialogFooter showCloseButton>
      <Button>Send</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Props

PropTypeDefaultDescription
open / defaultOpenbooleannoneControlled or uncontrolled open state, on the root.
onOpenChange(open: boolean, details) => voidnoneCalled when the popup opens or closes.
DialogTrigger renderReactElement | (props, state) => ReactElementnoneBase UI's replacement for asChild: render the part as another element, such as a Button or a Link.
DialogContent showCloseButtonbooleantrueThe round X in the corner.
DialogFooter showCloseButtonbooleanfalseAdds an outline Close button before the footer's actions.
classNamestringnoneMerged last with cn(). Use it for layout (width, margin), not to restyle the component.

Guidance

Do

  • Always give it a DialogTitle, even if you hide it with sr-only.
  • Keep it to one task.

Don't

  • Stack dialogs.
  • Use it for something people need to compare with the page behind. Use a popover.

Where it's used