Alert Dialog
A modal dialog component requiring user confirmation
Related WCAG criteria — click to view details
Code example
Common baseline
Applies to all design systemsrole and modal attribute
Use role="alertdialog" and aria-modal="true" to indicate that the dialog requires user confirmation.
Connect label and description
Use aria-labelledby for the title and aria-describedby for the body description. The description should help the user make a decision.
Focus trap
When the dialog opens, Tab/Shift+Tab focus must cycle only within the dialog and must not escape to outside elements.
Initial focus and focus restoration
On open, place initial focus on the least destructive button (usually Cancel). On close, restore focus to the element that triggered the dialog.
Close with ESC
Pressing ESC must close the dialog, treated the same as a cancel action.
Deactivate background
Elements outside the dialog must be excluded from screen readers and focus using inert or aria-hidden.
Use descriptive button labels
Instead of "OK"/"Cancel", use action-describing labels like "Delete"/"Don't delete".
Highlight destructive actions
Use color and position to draw attention to destructive action buttons (delete, remove), and place default focus on Cancel.
Be careful with background click to close
Important confirmation dialogs should not close on overlay click alone, as users may accidentally skip the decision.
Using only role="dialog"
When user confirmation is required, use role="alertdialog" instead of role="dialog" so screen readers convey the urgency.
Buttons without description
Having only "Are you sure?" without explaining what will be deleted leaves users unable to make an informed decision. Specify the item name and consequences.
Auto-open on page load
Opening an alert dialog on page load without user action causes confusion due to lost context. Always open in response to a user action.
Additional checks
Explicitly add role="alertdialog"
MUI Dialog defaults to role="dialog". For user confirmation, explicitly add role="alertdialog" via slotProps.paper.
Set aria-labelledby and aria-describedby
Connect aria-labelledby to the DialogTitle id and aria-describedby to the DialogContentText id on the Dialog.
Code sample
Implementation notes
- –MUI Dialog defaults to role="dialog", so use slotProps.paper.role to change it to alertdialog.
- –Placing autoFocus on the Cancel button prevents accidental execution of destructive actions.
- –MUI Dialog automatically handles focus trapping, ESC to close, and focus restoration.
- –aria-labelledby and aria-describedby must be set manually.