Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 38 ยท Forms and Dynamic Content

Modals, Dialogs and Popovers

Build accessible modals with the native dialog element: focus management, Escape to close, inert backgrounds, labels, and when to use popovers or tooltips instead.

A modal dialog asks for attention and blocks the rest of the page until the user answers. It is one of the most common widgets and one of the most commonly broken. A bad modal lets keyboard focus wander into the page behind it, hides the title from screen readers, or cannot be closed without a mouse.

Good news: the native <dialog> element, opened with showModal(), does most of the work for you.

What a modal must do

  1. When opened, move focus into the dialog (to the first control, or the dialog itself if it has no controls).
  2. Keep focus inside while it is open (Tab and Shift+Tab cycle through its controls).
  3. Make the page behind inert: unreachable by keyboard, mouse and screen reader.
  4. Close with the Escape key and with a visible Close or Cancel button.
  5. On close, return focus to the element that opened it.
  6. Give the dialog an accessible name (and a description if helpful), exposed with role="dialog" (native <dialog> already has it).

The native dialog

dialog.showModal() opens it in the browser "top layer", adds a ::backdrop, traps focus, makes the rest of the document inert, closes on Escape, and restores focus to the trigger in current browsers. dialog.show() opens a non-modal dialog without those behaviors; use it sparingly.

Native modal dialog

Open it with the keyboard (Tab to the button, press Enter). Press Tab repeatedly: focus never leaves the dialog. Press Escape: it closes and focus goes back to "Delete project".

For destructive actions, many teams focus the safe button (Cancel) first with the autofocus attribute on that button, so a stray Enter does not confirm a deletion.

Names and descriptions

  • aria-labelledby pointing to the dialog's heading provides the name.
  • aria-describedby pointing to explanatory text is optional but helpful for confirmations.
  • Do not nest a second dialog inside a dialog if you can avoid it; stack them only when truly necessary.
  • Use role="alertdialog" for urgent confirmations that need an immediate response (the native dialog does not set this; add the attribute).

If you cannot use <dialog>

Older code uses a div with role="dialog" and aria-modal="true". Then you must do the work yourself: move focus on open, trap Tab, close on Escape, restore focus, and set inert on the background siblings (the inert attribute is now widely supported). aria-modal alone only hints to screen readers; it does not block keyboard focus in all browsers.

HTML
<div id="app" inert> ...page... </div>
<div role="dialog" aria-modal="true" aria-labelledby="t" tabindex="-1">...</div>

Popovers and tooltips

Not everything needs a modal. HTML now has a Popover API for non-modal overlays like menus and rich tooltips:

HTML
<button popovertarget="info">More info</button>
<div id="info" popover>
  <p>This panel closes with Escape or a click outside (light dismiss).</p>
</div>

Popovers appear in the top layer, close on Escape, and return focus to the invoker, but they do not trap focus or make the page inert. Use them for lightweight, optional content.

Tooltip rules (WCAG 1.4.13 Content on Hover or Focus, AA):

  • Dismissible: the user can close it without moving the pointer or focus (Escape).
  • Hoverable: the pointer can move onto the tooltip without it vanishing.
  • Persistent: it stays until dismissed, hover or focus is removed, or the info is no longer valid.

Tooltips must not hold essential information or interactive content; links and buttons belong in a popover or dialog.

Popover with a toggle button

Choosing the right pattern

Need Use
Must answer before continuing Modal <dialog> with showModal()
Optional extra info or menu Popover
One-line label for an icon A visible text label; avoid title-only tooltips
Result of an action Live region (see status messages)
Large task A new page, not a modal

Common mistakes

  • Opening a dialog without moving focus into it.
  • Letting Tab reach elements behind the modal.
  • A close icon with no accessible name (needs aria-label="Close").
  • Scrolling the page behind a long modal (lock body scroll with overflow: hidden on the root).
  • Auto-opening dialogs on page load (newsletter pop-ups): they trap people before they can read.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which call opens a native dialog as a true modal?

    showModal() puts the dialog in the top layer, makes the rest of the page inert and traps focus. show() is non-modal.
  2. 2. Where should focus go when a modal closes?

    Returning focus to the trigger keeps the user's place.
  3. 3. Which key must close a modal dialog?

    Escape is the standard dismissal key; there should also be a visible close or cancel button.
  4. 4. Which is true of the Popover API compared with a modal dialog?

    Popovers are non-modal: the rest of the page stays usable and focus is not trapped.

Summary

  • Prefer native <dialog> with showModal(); it handles focus trapping, inert background and Escape.
  • Name the dialog with aria-labelledby; return focus to the trigger on close.
  • Use popovers for optional content; keep tooltips dismissible, hoverable and persistent.
  • Avoid auto-opening dialogs and unnamed close buttons.

Next: Accessible Tabs, Accordions and Menus