Raise blocking errors in an alert dialog
role=alertdialog is for an error that has to stop somebody. A session about to expire, a payment that failed, a form that will lose data. It announces itself and takes focus, which is why W3C lists it as sufficient for 3.3.1 Error Identification and for the rule about suggesting a correction. Taking focus is also the reason it is only advisory for status messages, because a status message is by definition something that does not steal focus. Three behaviors have to be built. Focus moves to something inside the dialog when it opens. Tab order stays inside it while it is open, unless you used a real dialog element, which does that for you. And focus goes back where it came from when the dialog closes, if that element still exists. The last two are where most implementations break. Reserve it for the genuinely blocking case, because interrupting is the whole mechanism and it costs the reader their place.
How we find it in an audit
We trigger every blocking error by keyboard and follow the focus. Where it lands, whether we can tab out of the dialog into the page behind it, and where focus goes once we close it. Scanners spot an alertdialog with no accessible name and see none of that.
How affected users experience it
A modal that only looks like a modal is silent. A screen-reader user carries on reading the page underneath, unaware that a message opened, and submits a form that has already been rejected. With a real alertdialog, they hear the message, they are already inside it, and when it closes they are put back where they were standing rather than at the top of the page.
Passes vs. fails
Passes
<div role="alertdialog" aria-labelledby="exp-t" aria-describedby="exp-m">
<h2 id="exp-t">Session expired</h2>
<p id="exp-m">Your work is saved. Log in again to continue.</p>
<button>Log in</button>
</div>
<!-- script moves focus in on open, and back out on close -->Fails
<div class="modal">
<p>Your session has expired.</p>
<button>Log in</button>
</div>
<!-- shown with CSS, focus never moves -->How this gets tested
The W3C publishes test rules that define what a checker looks for here.
- Error message describes invalid form field valueA tool finds candidates, you decide
Other ways to satisfy this rule
13 guides on this site are filed under 3.3.1 Error Identification. W3C lists this one as sufficient for that rule on its own. Implement it correctly, in a way your readers' software actually supports, and the rule is met.
- ARIA19sufficientAnnounce form errors with role=alert
- ARIA21sufficientFlag invalid fields with aria-invalid
- G83sufficientTell users which required fields they missed
- G84sufficientExplain when input is not an allowed value
- G85sufficientExplain format errors and show the fix
- PDF5sufficientMark required fields in PDF forms
This guide is our interpretation of W3C technique ARIA18: Using aria-alertdialog to Identify Errors. W3C publishes its techniques as guidance rather than as the standard, and says so on every one of them. The success criterion is what conformance is measured against, and a technique is one documented way to meet it.