role="dialog"

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

Use dialog for content layered over the page that wants dealing with before the reader goes back. Name it, usually from its own heading with aria-labelledby, and set aria-modal when the rest of the page really is inert. The hard part is not the role. It is moving focus in, keeping it in, and putting it back where it came from.

The HTML element behind role="dialog"

The dialog element is a dialog, and showModal gives you the focus trap, the top layer, the backdrop and closing on Escape without any of it being your code. Of every native element on these pages, it is the one that hands back the most.

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="dialog" sits in the model

Inherits from

window → 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.

More specific roles below it

alertdialog

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

How a checker tests role="dialog"

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

• alertdialog An urgent dialog carrying a message that has to be answered before anything else.