alertdialog

When to use

Only for interruptions: an error that blocks the user from proceeding, a “Are you sure you want to delete?” confirmation, an unsaved-changes warning when navigating away. Reaching for alertdialog for routine modals is overkill — use plain role="dialog" for those.

The difference from role="dialog" is that an alertdialog is announced like an role="alert" — assertive, immediate — when it appears. This is appropriate for genuine interruptions; misuse leads to screen-reader fatigue.

aria-labelledby (pointing at the title) and aria-describedby (pointing at the body text) are both required. The alertdialog must contain at least one focusable button so the user can dismiss it.

Keyboard + focus contract

Per the APG alertdialog pattern:

• Focus moves to the alertdialog on open — typically to the safest button (Cancel) so an accidental Enter does not confirm a destructive action.
• Tab / Shift+Tab cycle focus within the dialog.
• Escape closes the alertdialog and returns focus to the trigger.
• The rest of the page is inert while the alertdialog is open.

Pick the initial focus carefully: for “Delete?” prompts, focus Cancel by default — never the destructive button.

Common failures

• Using role="alertdialog" for every modal. Screen readers blast the user with the assertive announcement on every modal open.
• Initial focus on the destructive button (Delete, Discard) — a stray Enter wipes the user’s work.
• Missing aria-describedby on the body text. The user hears the title and the buttons but not the warning.
• Alertdialog with no buttons — there’s no way to dismiss it, and the role mandates an actionable response.
• Auto-dismissing alertdialogs after a timeout. Defeats the “requires response” semantic.

Example

<div
  role="alertdialog"
  aria-modal="true"
  aria-labelledby="confTitle"
  aria-describedby="confDesc"
>
  <h2 id="confTitle">Delete draft?</h2>
  <p id="confDesc">"Untitled draft (March 12)" will be permanently deleted. This action cannot be undone.</p>
  <button type="button" autofocus>Cancel</button>
  <button type="button">Delete draft</button>
</div>