An alertdialog is a dialog that interrupts, and it is the role for a message somebody has to answer before anything else happens. ARIA builds it out of two parents at once. From alert it takes the urgency, so the browser is meant to fire a system alert event the moment the dialog is drawn, wherever the platform has such an event. From dialog it takes the ability to be answered, which a plain alert never has. Three obligations come with the role. It needs an accessible name, and that name has to come from aria-label or aria-labelledby rather than from the words inside it. Its message belongs in aria-describedby, pointed at the element holding those words, because a screen reader left to work the message out for itself is guessing. And it should be modal, meaning nothing outside it answers the keyboard or the mouse while it is open. Reach for it when unsaved work is about to go, and use a plain dialog for everything else.
In practice
Use it rarely, and the test for whether this is the moment is whether the reader has to answer before carrying on. Unsaved work about to be discarded. A session about to expire. A deletion that cannot be undone. Everything else is a plain dialog, and a plain dialog is the right answer far more often than teams assume, because the whole value of this role is that it interrupts and a role that interrupts constantly stops meaning anything.
Three pieces of markup carry the pattern and none of them is optional in practice. The name goes in aria-label or aria-labelledby, because this role takes its name from the author rather than from its contents, so a heading inside the dialog and nothing else leaves it unnamed. The message goes in aria-describedby pointing at the element that holds it, and the specification says plainly that a screen reader left without one falls back on its own recovery mechanism, which is a polite way of saying it guesses. And the dialog should be modal, which means keyboard and pointer only reach inside it while it is open.
Focus goes to an active element inside the dialog when it opens, and the specification asks for something that can be acted on, such as a form control or the confirmation button. Where the dialog finishes something you cannot undo, put focus on the least destructive control, so a mistaken Enter cancels rather than deletes. Moving focus in like that is a change of context, which is allowed here and is also the reason the message does not need a live region on top of it.
Why it matters
This role is the one place where a dialog is supposed to interrupt, and getting that wrong runs in both directions. Marking every confirmation as an alert dialog trains people to hear urgency where there is none, which is the same failure as an assertive live region left switched on. Leaving it off the one dialog that really is urgent means a screen reader user reaches a warning about unsaved work at their own pace, which for this particular message is too late. It is also worth being exact about the mechanism, because a shorthand does the rounds saying the role carries a live region. It does not. ARIA classes it as a window role and the interruption comes from a platform alert event fired when the dialog is drawn, which is why adding aria-live to it by hand is a change nobody asked for.
The dialog that has no name
A confirmation opens with an h2 reading Delete this project and two buttons under it. The heading is inside the dialog, so a screen reader announces the container as dialog and nothing else, and the reader has to go looking for what it is about. One aria-labelledby pointing at that same heading fixes it, and one aria-describedby pointing at the paragraph beneath fixes the rest.
Where this shows up on the site
Related terms
- Modal dialogA modal dialog is a window that opens over the page and blocks everything behind it until it closes.
- Live regionA live region is a part of the page marked so that assistive technology announces changes to it without the user having to go and look.
- Accessible descriptionAn accessible description is the extra line a screen reader reads out after the name, and the word the specification uses for what it does is complements.
- Change of contextA change of context is one of four things, and only four.
Knowing the word is the easy part.
Find out where your own site stands. The free scan checks 10 pages in a real browser against all 90 supported automated rules, separates 27 best-practice checks from its WCAG findings, and names the rule behind every result.