Chapter 16: Dialog

Core Idea

A general-purpose modal window that renders content underneath inert, with automatic focus trapping and Escape-to-close — the base primitive most custom "Modal" components are built from.

Key Concepts

• Anatomy: Root → Trigger, Portal → Overlay, Content → Title, Description, Close.
• modal prop (default true): when false, disables the focus-trap/outside-inert behavior, useful for non-blocking dialogs.
• Title/Description: same announcement contract as AlertDialog; hide visually (not from AT) via the VisuallyHidden utility, or omit Description entirely by also passing aria-describedby={undefined} to Content.
• Outside-interaction callbacks: onPointerDownOutside, onInteractOutside, onEscapeKeyDown, onOpenAutoFocus, onCloseAutoFocus on Content — hooks for intercepting/customizing dismiss and focus-restoration behavior.

Code Examples

export const DialogContent = React.forwardRef(({ children, ...props }, ref) => (
  <DialogPrimitive.Portal>
    <DialogPrimitive.Overlay />
    <DialogPrimitive.Content {...props} ref={ref}>
      {children}
      <DialogPrimitive.Close aria-label="Close"><Cross1Icon /></DialogPrimitive.Close>
    </DialogPrimitive.Content>
  </DialogPrimitive.Portal>
));
export const Dialog = DialogPrimitive.Root;
export const DialogTrigger = DialogPrimitive.Trigger;

• What it demonstrates: the standard pattern for building your own reusable <Dialog> API by abstracting Overlay/Close into a wrapper component.

Reference Tables

Part	Notable props
Root	open/onOpenChange, defaultOpen, modal
Content	onOpenAutoFocus, onCloseAutoFocus, onEscapeKeyDown, onPointerDownOutside, onInteractOutside
Portal	container (default document.body)

Key Takeaways

1. Build your own Dialog/DialogTrigger/DialogContent wrapper early in a project — abstracting Overlay + Close into Content is the idiomatic Radix pattern shown in the official docs.
2. Esc closes and returns focus to Trigger automatically — no manual focus restoration needed in the common case.
3. Use AlertDialog instead when the interaction is a required response (confirm/cancel) rather than general content.

Connects To

• Alert Dialog: the interrupting-confirmation specialization of this same overlay pattern.
• Visually Hidden: used to hide Title/Description visually while keeping them announced.
• Animation: data-state on Overlay/Content drives open/close animation the same way as other overlay primitives.