---
system: material
category: guidance
topic: components/dialog
content_type: guidance
status: latest
version_label: "M3"
retrieved: 2026-05-12
source_url: https://m3.material.io/components/dialogs
derived_from:
  - kb/design-systems/material/guidance/foundations/color-roles
  - kb/design-systems/material/guidance/foundations/shape
  - kb/design-systems/material/guidance/foundations/typography
tags: [component, dialog, modal, overlay, material]
---

# 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

```css
--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