Containers & Overlays

Dialog

Dialog is a modal overlay that interrupts workflow for focused attention, information, or a decision.

Single component

betaReact AvailableFigma AvailableDocs Partial

React last updated: 2026-07-11
Documentation last updated: 2026-06-01
Accessibility target: WCAG 2.2 AA (target)
Version: 0.5.0-beta

Known open questions

Destructive alertdialog variant not confirmed as a separate Figma pattern — use Dialog with danger actions for now.
Full-screen mobile Dialog layout not confirmed — viewport padding and max-height cap used instead.

Live preview

Modal dialog with background inert, focus trap, and backdrop dismissal.

Informational

Long content

Purpose

A modal window that interrupts the current flow, requiring the user's attention or a decision before returning to the page.

Anatomy

Dialog = scrim + dialog surface + title + optional description + body + optional footer + close control.

Variants and states

modal

When to use

Destructive action confirmation, a focused task, collecting required information before proceeding.

When not to use

Non-critical supplementary information — use Popover.

Accessibility

Must trap focus while open, return focus to trigger on close, support Escape-to-close, role="dialog" with aria-modal="true".

Keyboard behavior

Escape closes the topmost overlay. Tab cycles within Dialog. Background content is inert while open. Focus returns to trigger or finalFocusRef on close.

Common mistakes

Not trapping focus, allowing Tab to escape to obscured page content behind the scrim.

Properties

Title (text), Body (text). Footer uses real Button instances. Demonstrated with a real scrim + centered composition.

What is the difference between Dialog and Popover?

Dialog is modal, inerts the background, and traps focus. Popover is non-blocking supplementary content attached to a trigger.

Should clicking the overlay close a Dialog?

Yes when closeOnOverlayClick is enabled and the pointer down occurs on the backdrop, not when dragging out of content.

Why does a Dialog require an accessible title?

Modal dialogs must expose an accessible name through DialogTitle or aria-label so screen-reader users know what interrupted the page.

How does nested overlay Escape work?

Escape closes only the topmost overlay. Tooltip inside Popover inside Dialog closes in that order.

Tokens used

semantic/surface/defaultcomponent/radius/containershadow-blur/5shadow-color/5

Component API

Prop	Type	Default	Description
open	boolean	—	Controlled open state.
defaultOpen	boolean	—	Initial open state.
onOpenChange	(open: boolean, reason?: DialogCloseReason) => void	—	Closure requests always emit false with a reason.
closeOnOverlayClick	boolean	true	Backdrop dismissal.
initialFocusRef	RefObject<HTMLElement>	—	Preferred initial focus target on DialogContent.
finalFocusRef	RefObject<HTMLElement>	—	Preferred focus restoration target on close.

React example

Copy React example

"use client";

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

export function Example() {
  return (
    <Dialog>
      <DialogTrigger>
        <Button type="button">Open dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Save changes?</DialogTitle>
          <DialogClose />
        </DialogHeader>
        <DialogDescription>Review updates before publishing documentation.</DialogDescription>
        <DialogBody>
          <p>Dialog body content.</p>
        </DialogBody>
        <DialogFooter>
          <Button type="button" variant="secondary">Cancel</Button>
          <Button type="button">Save</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}