Dialogs

Dialogs are a type of modal window that appears in front of app content to provide critical information or ask for a decision. They disable app functionality until the user interacts with them.

Dialogs are typically used for:

• Confirming a user action (e.g., deleting an item)
• Displaying important information that requires user acknowledgment
• Gathering user input without navigating away from the current page

Dialogs should be used sparingly to avoid disrupting the user experience. They should be clear, concise, and provide a straightforward way for users to complete the required action or dismiss the dialog.

Regular dialogs work best for short decisions or confirmations: keep titles clear, lead with the primary action, and always provide a close button: a <button> with the class control close and an aria-label, because it only shows an icon. Use the native <dialog> element to inherit accessibility features, and rely on motion or subtle dimming—not surprise—to draw attention.

Common pitfalls: trapping focus without escape, hiding the close control, or placing destructive actions in the left-most position (which many readers treat as “safe”). Always restore focus to the triggering element after closing, and ensure keyboard users can reach every control inside the dialog.

<dialog>
  ...
  <button type="button" class="control close" aria-label="Close"><svg>...</svg></button>
</dialog>

<dialog>
  ...
  <button type="button" class="control close" aria-label="Close"><svg>...</svg></button>
  <footer>
    <button class="primary">...</button>
    <button>...</button>
  </footer>
</dialog>

E-ink: in the e-ink theme a dialog has a solid black border instead of a shadow, opens without fading in, and the page behind it is covered by a white veil instead of a dark, blurred one.

Dialog width should match the task: small for terse confirmations, medium for short forms, wide for rich text or summaries, and full-width for immersive previews. Avoid stuffing wide dialogs with single-line content—choose the smallest size that keeps copy readable without awkward wrapping.

Backdrops: use ::backdrop to soften the page behind the dialog, and keep contrast high so the active dialog remains obvious. If you allow backdrop clicks to close, make sure keyboard users have an equivalent escape path (Esc or a close button), and prevent background scrolling while the dialog is open.

<dialog class="small"></dialog>
<dialog class="medium"></dialog>
<dialog class="wide"></dialog>
<dialog class="full-width"></dialog>

To see a dialog box in action, please press below button:

A popover is a box that a button opens on top of the page, for a short explanation or a few choices. Give any element the popover attribute and an id, and give the button popovertarget with that id. The browser does the rest, without a script: the popover closes with Esc or a click elsewhere, the focus goes back to the button, and screen readers hear whether it is open.

<button type="button" popovertarget="isbn">What is an ISBN?</button>
<div popover id="isbn">
  <p>...</p>
</div>

A <dialog popover> works the same way and is placed in the middle of the screen. Unlike a modal dialog, the page behind it stays usable.

Browser support: popovers need Chrome and Edge 114, Safari 17 or Firefox 125. Older browsers ignore the attribute and show the popover where it is in the page, so write it so that it still makes sense there, or use a modal dialog instead. A popover is placed in the middle, not next to its button: placing it next to the button needs CSS anchor positioning, which is newer still.