role="alertdialog"

What role="alertdialog" means, and when to use it

Use alertdialog for a dialog carrying an urgent message that has to be answered, like a warning that unsaved work is about to be lost. The difference from dialog is that its message is announced when it opens, so put the message in the accessible description with aria-describedby.

The HTML element behind role="alertdialog"

HTML has no urgent dialog. Use the dialog element for the behavior and add role="alertdialog" on top, which is one of the few places where overriding an element's own role is the right call.

Window roles mark content layered over the page

A dialog is content stacked on top of the page that wants an answer before the reader goes back to what they were doing. The role tells assistive technology that this is now the thing to deal with.

The role is the easy part. Dialog accessibility is focus management, which means moving focus into the dialog when it opens, keeping it inside while it is open, and putting it back on the trigger when it closes. None of that arrives with the role.

Use alertdialog when the message needs an answer right now, like confirming that unsaved changes are about to go. Use dialog for everything else.

Where role="alertdialog" sits in the model

Inherits from, in no single line

alert, dialog, section, window, structure, roletype

The name can come from

aria-labelledby or aria-label. Its own text does not become the name, so text inside it will not be read as one.

The normative definition stays with the W3C, so it cannot go stale here. alertdialog in the ARIA specification.

How a checker tests role="alertdialog"

Getting this one wrong is easy to assume is a 4.1.2 Name, Role, Value problem, and mostly it is not. These are the published test rules that apply.

• Role attribute has valid value

The other window roles

• dialog Content layered over the page that wants a response before you go back.