Modal Dialog

Built with: dialog · showModal() · command=show-modal · closedby · form method=dialog

Open in Storybook: Modal Dialog (opens in a new tab)

Overview

Native dialog opened with showModal(), for an answer the person just asked for.

How it works

showModal() brings the top layer, ::backdrop, an inert page, Esc and focus return. Modal only: non-modal dialogs, popovers, toasts and banners are not covered.

• Use it when the page must stop for an answer the person just asked for.
• Never on page load or a timer: it steals the caret from someone reading.
• Don’t ask when nothing changed, or for a choice that can be undone: do it and offer Undo.
• Extra detail that can sit beside the content is a details or a toggletip.

Types

alertdialog only when the answer is required to finish what was just started. If the flow can go on without it, dialog: one attribute apart.

Live example

Anatomy

Specs

Measurements

Adapting to viewports

The panel shrinks to the viewport, then fills it and scrolls inside. Close and the actions stay reachable; the page behind never scrolls.

Motion

Animate in and out without breaking the exit or reduced motion.

dialog[open] { display: grid; }          /* display only when open */
dialog, dialog::backdrop {
  transition: opacity .2s, translate .2s, overlay .2s allow-discrete, display .2s allow-discrete;
}
dialog:not([open]) { opacity: 0; translate: 0 1rem; }
@starting-style { dialog[open] { opacity: 0; translate: 0 1rem; } }

@media (prefers-reduced-motion: reduce) {
  dialog, dialog::backdrop {
    transition: opacity 1ms, overlay 1ms allow-discrete, display 1ms allow-discrete;   /* keep display and overlay */
    translate: none;
  }
}

Markup

<button command="show-modal" commandfor="del" id="opener">Delete draft</button>

<dialog id="del" closedby="any" aria-labelledby="del-h" aria-describedby="del-d">
  <h2 id="del-h">Delete this draft?</h2>
  <p id="del-d">“Spring menu” and its 3 photos will be deleted. You can’t undo this.</p>
  <form method="dialog">
    <button value="cancel" autofocus>Cancel</button>
    <button value="delete">Delete draft</button>
  </form>
</dialog>

Script

HTML first, then the script for what native does not do: the opener when a key or state opens it, the Tab wrap (a custom focus trap), the cancel guard and returnValue.

const dialog = document.getElementById('del')
const leave = document.getElementById('leave')    // the sibling alertdialog
let dirty = false
let opener                                        // only when a key or state opens it

const open = () => { opener = document.activeElement; dialog.showModal() }

// Tab wrap, a custom focus trap: wrap only, nothing more
dialog.addEventListener('keydown', (e) => {
  if (e.key !== 'Tab' || e.target.matches('video, audio')) return
  const f = [...dialog.querySelectorAll('button, input, select, textarea, a[href], [tabindex="0"]')]
    .filter((el) => !el.disabled)
  if (e.shiftKey && e.target === f[0]) { e.preventDefault(); f.at(-1).focus() }
  else if (!e.shiftKey && e.target === f.at(-1)) { e.preventDefault(); f[0].focus() }
})

// Guard: ask once, in a sibling dialog. Close calls the same guard.
const guard = (e) => { if (dirty) { e.preventDefault(); leave.showModal() } }
dialog.addEventListener('cancel', guard)
dialog.addEventListener('command', (e) => e.command === 'close' && guard(e))

dialog.addEventListener('close', () => {
  if (dialog.returnValue === 'delete') removeDraft()   // the exact word
  opener?.focus()
})

Tokens

Component tokens

The values of the Figma components Dialog / Button and Dialog / Close button.

Guidelines

Ways to open and close

Native first. Script only when state, a key or a promise opens it.

closedby

How much it costs to leave decides which exits exist.

Guarding a close

returnValue

A string, "" at first. close(100) gives "100"; objects go through JSON.stringify and JSON.parse.

Forms

A form first: required fields block a submit, never an exit.

Stacked modals

Siblings in the DOM, never nested. Call order is the stack.

Accessibility

Requirements

Focus management

Focus trap

My choice. The native modal considers the interactive widgets of the browser, such as its address bar and its toolbar, part of the focus flow: after the last control of the dialog, Tab goes out to the browser interface. In my opinion this is a blocker for keyboard and screen reader users, who have to cross it every time. I decided to keep the browser interface out of the focus flow, so the wrap is a custom focus trap that I wrote on purpose.

Keyboard

Announcements

A message nothing on the page moves for is said with ariaNotify(), not a live region. The same words are on the page as text. Called once per event, after the focus has moved, on the dialog or an element inside it: a call on the inert page says nothing. Where ariaNotify is missing, nothing is said and nothing replaces it.

WCAG criteria

Related

• Modal Dialog (opens in a new tab)

References

The post is still in progress.