# Dialogs

> Important prompts in a user flow. Dedicated to a single task.

## Anatomy

Use a dialog so people act on information — confirm a high-risk action, finish one task, or read the copy that belongs to that task. Two variants, same element: a basic dialog and a full-screen dialog. There is no `modal-header`, `modal-content`, or `modal-footer` class.

Tokens follow the [M3 dialog spec](https://m3.material.io/components/dialogs/specs). The basic container is `surface-container-high`, 28dp corners, 280–560dp, elevation 3. The headline is `headline-small` / `on-surface`; supporting text is `body-medium` / `on-surface-variant`. Actions are text buttons, end aligned, with an 8dp gap. Padding is 24dp (16dp between the headline and the body). The scrim is `--md-comp-scrim-color` with a 12px blur. Opening with `showModal()` also stops the page behind it from scrolling.

Open it with `showModal()` and close it with `close()` — the Dialog API, not a plugin.

## Basic

A `<dialog>` is the surface. A heading is the headline, a `<p>` (or a wrapping `<div>`) is supporting text, and the last child `<form method="dialog">` or `<nav>` is the action row. An optional leading icon centers the headline. An `<hr>` is the divider when extra content follows the copy.

Show Show with icon Show with extra content

## Basic dialog title

A dialog is a modal window that appears in front of app content to provide critical information or ask for a decision.

Text button Text button

## Use location services?

Let the app use your location to suggest nearby stops and live arrival times.

Disagree Agree

## Reset settings?

This will reset your app preferences back to their default settings. The following accounts will also be signed out:

* * *

-   leevillanuevanotes@google.com
-   alloalejandro@google.com
-   oliortega@google.com

* * *

Cancel Accept

```
<button type="button" onclick="document.getElementById('dialog1').showModal()">
  Show
</button>

<dialog id="dialog1" aria-labelledby="basic-dialog-title-title">
  <h2 id="basic-dialog-title-title">Basic dialog title</h2>
  <p>A dialog is a modal window that appears in front of app content.</p>
  <form method="dialog">
    <button type="submit" value="cancel">Cancel</button>
    <button type="submit" value="accept">Accept</button>
  </form>
</dialog>
```

A `<form method="dialog">` closes the dialog when a submit button is pressed and sets `dialog.returnValue` from the button’s `value`. Action buttons are text buttons by default — add `filled`, `tonal`, or `outlined` if you need more emphasis. Tapping the scrim closes it too, but only if the press and the release both miss the dialog. Docked panes are [Side sheet](/side-sheet.html.md) and [Bottom sheet](/bottom-sheet.html.md).

## Full-screen

Add `max` when the task needs the whole viewport — typically on compact windows, or any time the dialog holds a form. There is no scrim and no corner radius. A `<header>` is the 64dp top bar: a close icon, a `title-large` headline, and the confirming text button. Body content is inset 24dp.

Show full-screen

## Full-screen dialog title

Save

 Event name

 From

 To

 All day

```
<dialog class="max" aria-labelledby="full-screen-dialog-title-title">
  <header>
    <button type="button" aria-label="Close">
      <span class="material-symbols" aria-hidden="true">close</span>
    </button>
    <h2 id="full-screen-dialog-title-title">Full-screen dialog title</h2>
    <form method="dialog">
      <button type="submit" value="save">Save</button>
    </form>
  </header>
  <div>…</div>
</dialog>
```

## Methods

Call these on the `<dialog>` element. See [HTMLDialogElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement) for the full API.

### .showModal()

Open as a modal, with the scrim (basic) or as the page (full-screen).

```
dialog.showModal();
```

### .close()

Close the dialog.

```
dialog.close();
```

A tap or click on the scrim also closes a basic dialog. Both ends of the gesture have to land outside the dialog’s box, so a drag that starts on the dialog — selecting text, missing a button — cannot dismiss it. Set `closedby="none"` or `closedby="closerequest"` to opt out.

## Tokens

Override these on the `<dialog>` if you need a different surface or width.

| Token | Default |
| --- | --- |
| `--md-comp-basic-dialog-container-color` | `--md-sys-color-surface-container-high` |
| `--md-comp-basic-dialog-container-shape` | 28px |
| `--md-comp-basic-dialog-container-min-width` | 280px |
| `--md-comp-basic-dialog-container-max-width` | 560px |
| `--md-comp-basic-dialog-scrim-blur` | 12px |
| `--md-comp-scrim-color` | `--md-sys-color-scrim` at 32% |