Alert Dialog

Purpose

An alert dialog interrupts the user’s workflow to convey an urgent message that requires acknowledgment or a decision. Unlike a standard dialog, the alert dialog is announced immediately by screen readers.

Usage Guidance

Use alert dialogs for irreversible or high-stakes actions such as:

• Confirming data deletion
• Warning about session expiration
• Requiring agreement before proceeding

Do not use alert dialogs for informational messages that do not require a decision.

Accessibility Considerations

• Use role="alertdialog" (not role="dialog") so screen readers announce it immediately
• aria-modal="true" informs AT that content outside the dialog is inert
• aria-labelledby associates the visible heading with the dialog
• aria-describedby associates the body text with the dialog for context
• Focus must be trapped within the dialog while open
• On close, return focus to the trigger that opened it

Keyboard Support

Screen Reader Behavior

Screen readers announce the dialog immediately upon opening, including the label and description. Focus is placed on the first focusable element or the dialog container itself.

ARIA Requirements

• role="alertdialog" on the dialog container
• aria-modal="true" on the dialog container
• aria-labelledby pointing to the dialog’s heading
• aria-describedby pointing to the descriptive paragraph

Common Mistakes

• Using role="dialog" instead of role="alertdialog" for urgent messages
• Not trapping focus within the dialog
• Not returning focus to the trigger on close
• Closing the dialog automatically on a timer (always require user action)

Live Example

Code Example

<!-- Trigger -->
<button data-dialog-open="confirm-delete">Delete Record</button>

<!-- Alert Dialog -->
<div
  id="confirm-delete"
  role="alertdialog"
  aria-modal="true"
  aria-labelledby="confirm-title"
  aria-describedby="confirm-desc"
  hidden
>
  <div class="dialog__inner">
    <h2 id="confirm-title">Delete this record?</h2>
    <p id="confirm-desc">This action cannot be undone.</p>
    <div class="dialog__actions">
      <button data-dialog-close>Cancel</button>
      <button data-dialog-close>Confirm Delete</button>
    </div>
  </div>
</div>