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.
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.
<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
and
Bottom sheet.
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.
<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
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% |