Overlays

Accessible Alert & Alert Dialog

A message interrupting the user with important, often time-sensitive, information requiring acknowledgment.

Last verified against WCAG 2.2 and WAI-ARIA APG 1.2 on 2026-07-02.

Implementation

role="alertdialog", focus trap, Escape handling, and focus forced to Cancel on open.

<button id="delete-trigger">Delete 12 items</button>

<!-- role="alertdialog" (not "dialog") tells AT this needs a decision;
     aria-describedby points at the consequence text. There is NO
     click-outside to close, the user must choose. Starts hidden. -->
<div id="alert-overlay" class="overlay" hidden>
  <div id="alert" role="alertdialog" aria-modal="true"
       aria-labelledby="alert-title" aria-describedby="alert-desc">
    <h2 id="alert-title">Delete 12 items?</h2>
    <p id="alert-desc">This can't be undone.</p>
    <button id="alert-cancel">Cancel</button>
    <button id="alert-confirm">Delete</button>
  </div>
</div>

Required roles, states & properties

Required roles, states, and properties
Element	Attribute	Why
Dialog container	role="alertdialog"	Distinct from role="dialog", tells AT this interruption carries urgent, often destructive, information requiring explicit acknowledgment.
Dialog container	aria-modal="true"	Same as Dialog: marks background content inert, backed by a manual focus trap.
Dialog container	aria-labelledby	Points at the visible heading so the accessible name matches on-screen text.
Dialog container	aria-describedby	Points at the consequence text (e.g. "This can't be undone") so it's read immediately after the name, critical context for a destructive confirmation.
Cancel button	Receives focus on open	APG requirement specific to alertdialog: default focus goes to the least destructive action so accidental Enter/Space never confirms a destructive one.

Keyboard interaction model

Keyboard interaction model
Key	Behavior
`Tab`	Moves focus to the next focusable element inside the dialog. Wraps from last to first.
`Shift+Tab`	Moves focus to the previous focusable element. Wraps from first to last.
`Escape`	Closes the dialog without taking the destructive action (equivalent to Cancel) and returns focus to the trigger.
`Enter / Space`	Activates whichever button has focus. Because focus starts on Cancel, this is safe by default.

Focus management rules

On open: focus moves to the least destructive action (typically Cancel), never to the confirm/destroy button.
While open: Tab/Shift+Tab cycle only within the dialog's focusable elements.
On close (Escape, confirm, or cancel): focus returns to the element that opened the dialog.
Unlike a plain Dialog, clicking the scrim/overlay does not close a true alert dialog, the interruption should be resolved deliberately, not brushed aside accidentally.

WCAG 2.2 success criteria mapping

WCAG 2.2 success criteria that apply to this component
SC	Name	Level	Why it applies
2.1.1	Keyboard	A	All functionality is operable through a keyboard interface with no specific timing.
2.1.2	No Keyboard Trap	A	Keyboard focus can always be moved away from a component using standard navigation.
2.4.3	Focus Order	A	Focusable components receive focus in an order that preserves meaning and operability.
4.1.2	Name, Role, Value	A	For all UI components, name, role, and value are programmatically determinable; states and changes are announced.
4.1.3	Status Messages	AA	Status messages can be programmatically determined via role or properties (e.g. aria-live) without receiving focus.

Find what you need, instantly