Material Design 3 — Dialogs

Overview

Dialogs are modal windows that appear in front of app content to provide critical information or ask for a decision. They disable all app functionality when open and remain on screen until confirmed, dismissed, or a required action is taken.

Dialogs are intentionally interruptive — use sparingly. For lower-priority choices, prefer a dropdown menu.

Two variants: basic and full-screen.

---

Variants

Basic dialog

• Interrupts with urgent information, details, or actions
• Floats above the scrim, centered on screen
• Used for: alerts, confirmations, quick selections, error acknowledgments
• Dismissible via scrim tap or explicit close action
• Contains 0–2 action buttons

Full-screen dialog

• Fills the entire screen
• Used when completing a task requires a series of sub-steps (e.g., creating a calendar entry)
• Cannot be dismissed by tapping outside — requires explicit close or confirm
• Contains a close icon button + a confirm action in the top bar

---

Anatomy

Basic dialog

1. Container — surface-container-high, shape-extra-large corner radius (28dp)
2. Icon (optional) — centered, 24dp, secondary color
3. Headline — title-large type style; on-surface
4. Body text — body-medium type style; on-surface-variant
5. Divider (optional) — appears when content scrolls
6. Actions — right-aligned text buttons; maximum 2

Full-screen dialog

1. Top app bar — contains close icon (left), title (center/left), confirm button (right)
2. Body — scrollable content area
3. Divider — separates header from scrollable content when scrolled

---

Color tokens

--md-sys-color-surface-container-high   /* dialog container */
--md-sys-color-on-surface               /* headline and body text */
--md-sys-color-on-surface-variant       /* secondary body text */
--md-sys-color-secondary                /* icon (if present) */
--md-sys-color-scrim                    /* backdrop overlay */

Scrim opacity: 32% (scrim color role).

---

Actions (basic dialog)

• Maximum 2 buttons
• Both are text buttons (lowest emphasis — the dialog headline carries the emphasis)
• Placement: right-aligned in a row at the bottom
• Negative/dismissive action on the left; positive/confirming action on the right
• For destructive confirmations: use error color on the confirming button

[Cancel]  [Delete]   ← destructive confirm uses error color
[Cancel]  [Save]     ← standard confirm

Do not use filled buttons in dialogs — they compete with the headline.

---

Behavior

• Opens with a scale + fade transition from center
• Scrim appears simultaneously
• Focus moves to the first interactive element inside the dialog on open
• Tab cycling stays within dialog bounds (focus trap)
• Esc key dismisses basic dialogs; does not dismiss full-screen
• Scrollable body content: show divider below headline when content overflows

---

When to use each variant

Scenario	Variant
Delete confirmation	Basic
Alert with required acknowledgment	Basic
Quick selection (time picker, color picker)	Basic
Multi-step form (event creation)	Full-screen
Content creation with many fields	Full-screen

---

Accessibility

• Role: dialog with aria-modal="true"
• aria-labelledby pointing to the headline
• aria-describedby pointing to body text (if present)
• Focus trap: keyboard navigation must not leave the dialog while open
• Return focus to the trigger element on close
• Avoid dialogs for non-critical information — use snackbars or inline messages instead