Chapter 21: Dialog

Core Idea

A general-purpose modal (by default) window — the base primitive most custom "Modal" components build from — sharing AlertDialog's full anatomy (Backdrop/Viewport/Popup/Title/Description/Close, Handle/createHandle for detached triggers) but for non-interrupting content; reach for Drawer instead once gesture support or snap points are needed.

Key Concepts

• Usage guideline: Dialog doesn't support gestures. A panel sliding in from a screen edge with no gesture/snap-point need is "a positioned Dialog"; once swipe-to-dismiss or snap points matter, use Drawer (ch022) instead.
• Anatomy: Root → Trigger, Portal → Backdrop, Viewport → Popup → Title, Description, Close. Identical shape to AlertDialog (ch012).
• modal prop: default true. false disables the focus-trap/outside-inert behavior for a non-blocking dialog that coexists with page interaction.
• disablePointerDismissal: prevents closing via outside pointer press — keep the dialog open until an explicit action, without going as far as AlertDialog's semantics.
• Same detached-trigger system as AlertDialog: Handle/createHandle(), handle prop on Root/Trigger, triggerId/defaultTriggerId, payload on Trigger.
• Nested dialogs: same data-nested/data-nested-dialog-open attributes and --nested-dialogs variable as AlertDialog.

Reference Tables

Part	Notable props	Notable data attributes
Root	open/onOpenChange, modal, disablePointerDismissal, handle, actionsRef, triggerId/defaultTriggerId	—
Trigger	handle, payload, id, nativeButton	data-popup-open, data-disabled
Backdrop	forceRender	data-open, data-closed, data-starting-style/data-ending-style
Popup	initialFocus, finalFocus	data-open, data-closed, data-nested, data-nested-dialog-open, animation attrs
Close	nativeButton	data-disabled

Key Takeaways

1. Default to Dialog for any general modal content; only reach for AlertDialog when the interaction genuinely requires a forced confirm/cancel response.
2. Set modal={false} for non-blocking auxiliary panels (e.g. a persistent inspector) that should coexist with normal page interaction rather than trapping focus.
3. Switch to Drawer the moment product requirements mention swipe-to-dismiss or snap points — Dialog explicitly does not support gestures, per the docs' own guidance.

Connects To

• ch012 (Alert Dialog): near-identical API for the interrupt-required variant — most props/parts documented there apply here unchanged.
• ch022 (Drawer): the gesture-capable sibling for edge-sliding panels.
• ch003 (Accessibility): initialFocus/finalFocus focus-management guidance.