Windows

Dialog is a modal window. It renders centered over a scrim, traps focus, and blocks interaction with the page behind it until the user finishes or dismisses it. Reach for it when a task needs the user’s full attention but does not warrant a full page navigation, such as editing a record, confirming details, or filling a short form.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: dialog.tsx

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  Button,
  Input,
  Label,
} from "@beacon/design-system";

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open Dialog</Button>
  </DialogTrigger>
  <DialogContent className="sm:max-w-[425px]">
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>
        Make changes to your profile here. Click save when you're done.
      </DialogDescription>
    </DialogHeader>
    <div className="grid gap-4 py-4">
      <div className="grid grid-cols-4 items-center gap-4">
        <Label htmlFor="name" className="text-right">
          Name
        </Label>
        <Input id="name" defaultValue="Pedro Duarte" className="col-span-3" />
      </div>
    </div>
    <DialogFooter>
      <Button type="submit">Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Parts

Part	Role
Dialog	Root state container. Controls open/closed; accepts open and onOpenChange for controlled use.
DialogTrigger	Element that opens the dialog. Use asChild to wrap your own button.
DialogContent	The centered modal surface. Renders the overlay and a built-in close button.
DialogHeader	Layout wrapper for the title and description.
DialogTitle	Accessible heading announced to screen readers.
DialogDescription	Supporting text under the title.
DialogFooter	Action row, right-aligned on larger screens.
DialogClose	Dismisses the dialog. Use asChild to make a custom element close it.
DialogPortal	Renders content into a portal at the document root.
DialogOverlay	The backdrop scrim. Included automatically by DialogContent.

When to use

• Editing or creating a record that fits comfortably in a small focused form.
• Showing content that requires the user to act before continuing.
• Any task where you want to interrupt the page flow without navigating away.

Do not use a Dialog for a yes/no destructive confirmation: reach for the Alerts page’s AlertDialog instead, which is built for that pattern. For side-anchored panels use a Sheet.