How to build an accessible AlertDialog in React

Uses role="alertdialog" with aria-modal and labelled/described-by wiring so assistive tech announces it as an interruptive decision; focus moves to the cancel button on open so the safe default is selected, and popover="manual" prevents accidental dismissal that would skip the decision

When to use a AlertDialog

• Confirming a destructive or irreversible action (delete, overwrite, sign out) before it happens
• Interrupting a flow to force an explicit decision the user must acknowledge

When not to use it

• Showing non-critical information or forms — use Modal, which supports light-dismiss and arbitrary content
• Confirming a low-stakes action where an undoable Toast is friendlier and less interruptive

Keyboard interactions

Role alertdialog, verified at WCAG 2.2-AA.

• Tab
• Shift+Tab
• Enter
• Space

Common mistakes

Avoid: Using AlertDialog for a multi-field form or rich content

Prefer: Use Modal for content; reserve AlertDialog for a title + description + confirm/cancel decision

AlertDialog only renders a title, description, and two action buttons, and is role="alertdialog" with no light-dismiss — it is built to demand a yes/no answer, not host content

Avoid: Adding a backdrop/Escape close to dismiss the dialog without choosing

It uses popover="manual" so it cannot be light-dismissed by design — closing must go through onConfirm/onCancel so the decision is always explicit

Example

<AlertDialog
  open={isOpen}
  variant="destructive"
  title="Delete project?"
  description="This permanently removes the project and cannot be undone."
  onConfirm={remove}
  onCancel={() => setIsOpen(false)}
/>

See the full AlertDialog reference →