Dialog
A small centered layer that interrupts to ask for one short input or decision, then gets out of the way. Use rarely: most tasks belong on the page, in a sheet or in a drawer.
Usage
Use it when
- One short input that must happen before going on: rename a course, set a due date, name a new folder.
- A short decision with two clear outcomes that is not destructive.
- Inside a contained region that is already positioned (
.viewport), such as a canvas, a preview or a phone frame.
Use something else when
- Confirming something destructive or irreversible (delete, remove, discard): use Alert dialog.
- A page-level form or report over the whole window, or a dialog that must sit above everything: use Modal. Native
<dialog>in the top layer; turns into a bottom sheet on phones. - A task on a phone that keeps the page in view (choose, filter, attendance): use Sheet.
- Filters or details beside a list on wide screens: use Drawer.
- Telling people something happened: use Toast.
- A few extra fields or options anchored to a button: use Popover.
Where it goes. Centered in its positioned container (.viewport, or a position: fixed; inset: 0 wrapper for the page), 340 px wide, above a scrim. On phones prefer a sheet; for the whole page prefer a modal.
Examples
<button class="btn btn--secondary" data-lds-open="rename" aria-haspopup="dialog">Rename course</button>
<div class="scrim" data-lds-scrim="rename"></div>
<div class="dialog" id="rename" role="dialog" aria-modal="true" aria-labelledby="rename-t" data-lds-layer>
<button class="icon-btn dialog__close" aria-label="Close" data-lds-close><span class="ic" aria-hidden="true">close</span></button>
<h2 class="dialog__title" id="rename-t">Rename course</h2>
<p class="dialog__body">Students see the new name the next time they open the app.</p>
<div class="control" style="margin-top: 16px;"><input aria-label="Course name" value="Database Systems" data-lds-autofocus></div>
<div class="dialog__actions">
<button class="btn btn--secondary" data-lds-close>Cancel</button>
<button class="btn btn--primary" data-lds-close>Save name</button>
</div>
</div>data-lds-autofocus.<div class="viewport docs-box">
<div class="viewport__content">
<button class="btn btn--secondary btn--md" data-lds-open="dlg-publish" aria-haspopup="dialog">Publish results</button>
</div>
<div class="scrim" data-lds-scrim="dlg-publish"></div>
<div class="dialog" id="dlg-publish" role="dialog" aria-modal="true" aria-labelledby="dlg-publish-t" aria-describedby="dlg-publish-b" data-lds-layer>
<h3 class="dialog__title" id="dlg-publish-t">Publish results now?</h3>
<p class="dialog__body" id="dlg-publish-b">32 students get a notification with their score. You can still edit scores afterwards.</p>
<div class="dialog__actions"><button class="btn btn--secondary btn--md" data-lds-close>Not yet</button><button class="btn btn--primary btn--md" data-lds-close data-lds-autofocus>Publish</button></div>
</div>
</div>Anatomy
| Part | What it is |
|---|---|
.scrim[data-lds-scrim="id"] | Required. The dim layer behind; a click on it closes the dialog. |
.dialog[role=dialog][aria-modal=true] | Required. The layer, with an id, data-lds-layer and aria-labelledby its title. |
.dialog__close | Optional close icon button in the top right, with data-lds-close. |
.dialog__title | Required. The question or task, as an <h2> or <h3>. |
.dialog__body | One or two sentences of context. |
.dialog__actions | Required. Two buttons sharing the width: secondary (dismiss) then primary. |
[data-lds-open="id"] | Required. The trigger, with aria-haspopup="dialog". |
States
| State | How |
|---|---|
.is-open | Visible and interactive; the scrim with the same id gets .is-open too. Set by openLayer. |
closed | aria-hidden="true" and inert, invisible after the exit finishes. |
Motion and microinteractions
- Enter: opacity over
--d-fast(160 ms) on--ease-enter; transform fromtranslateY(4px) scale(0.98)to none on--spring-smooth(560 ms). Add.is-enteringfirst for a deeper start (translateY(8px) scale(0.96)). - Exit: shorter and quieter, opacity and transform over
--d-exit(180 ms) on--ease-exit, thenvisibility: hidden. Both are transitions, so closing mid-entrance reverses from where it is. - Scrim: fades in over
--d-standard(240 ms), out over--d-exit. - Reduced motion: no transform at all, opacity only in 120 ms.
Accessibility
role="dialog",aria-modal="true",aria-labelledbythe title (andaria-describedbythe body when it carries the point).- On open, focus moves to
[data-lds-autofocus](or[autofocus]), else to the first focusable element. Tab and Shift+Tab are trapped inside whilearia-modal="true". - Escape closes the top layer only; the scrim and every
[data-lds-close]close it too. Focus returns to the element that opened it. - The trigger carries
aria-haspopup="dialog".
Do and don't
Do
- Ask one thing; title it as the question or the task.
- Name the primary button for its outcome ("Save name", "Publish").
- Autofocus the field, or the primary for a non-destructive choice.
Don't
- Open a dialog from a dialog; finish or close the first one.
- Put long forms, tables or scrolling content in it; use a modal, sheet or a page.
- Use it to confirm a delete; that is an alert dialog.
Behavior and code
Plain HTML. [data-lds-open="id"] calls openLayer(id, trigger); [data-lds-close] inside and [data-lds-scrim="id"] call closeLayer. Escape closes the top layer. Events lds:open and lds:close fire on the layer. Programmatic: openLayer(id), closeLayer(id or element).