ARIA Dialog and Alertdialog Must Have an Accessible Name: How to Fix It
- May 16, 2022
- Accessibility, Dialogs
Any element with role="dialog" or role="alertdialog" needs a name, or a screen reader announces "dialog" and nothing else. Point aria-labelledby at the heading and the modal introduces itself.
This check flags a modal container carrying role="dialog" or role="alertdialog" that has no accessible name. When focus lands inside a nameless dialog, assistive tech says "dialog" with no context, so the user has no idea whether they are in a cookie prompt, a delete confirmation, or a checkout step. Dialogs are also where conversions happen, so a modal a screen reader user cannot parse is a straight path to a bounced session and a lost sign-up.
Why the name matters more in a dialog than almost anywhere else
A dialog is a context switch. The moment it opens, a screen reader user is torn out of the page they were reading and dropped somewhere new, usually with focus moved into the modal. In that instant the accessible name is the only orientation they get. On a normal page you can explore headings and landmarks to figure out where you are, but a modal is meant to be a small, self-contained task, and users expect it to announce itself the way a well-labeled door announces the room behind it. Miss the name and you have effectively teleported someone into an unmarked room and asked them to make a decision. For an alertdialog the stakes climb higher, because these are reserved for urgent, often destructive choices, and the whole point is that the user hears the message before they act. A nameless confirmation dialog is how a keyboard-and-audio user deletes something they never meant to touch.
A real failure, and the fix
A common React or vanilla modal ships the role but forgets the name entirely:
<div role="dialog" aria-modal="true">
<h2>Delete this project?</h2>
<p>This action cannot be undone.</p>
<button>Cancel</button> <button>Delete</button>
</div>The heading already says exactly what this dialog is, so reuse it. Give the <h2> an id and reference it with aria-labelledby:
<div role="dialog" aria-modal="true" aria-labelledby="dlg-title">
<h2 id="dlg-title">Delete this project?</h2>
<p>This action cannot be undone.</p>
<button>Cancel</button> <button>Delete</button>
</div>Now, on open, the screen reader announces "Delete this project?, dialog" and the user knows precisely where they are.
dialog vs alertdialog, and how to name each
| Role | Use it for | Preferred name source | Also needs |
|---|---|---|---|
dialog | Forms, pickers, general modals | aria-labelledby → heading | Focus trap, aria-modal |
alertdialog | Urgent confirmations, errors | aria-labelledby → heading | aria-describedby → body text |
| Either, no visible title | Icon-only or compact prompts | aria-label="…" | Concise, purpose-first text |
How to detect it
- axe DevTools: open the modal first so it is in the DOM, then run the scan; "ARIA dialog and alertdialog nodes should have an accessible name" pinpoints the offending container.
- Lighthouse: run the Accessibility category with the dialog open and read the "ARIA" failures; a nameless dialog surfaces there.
- WAVE: trigger the modal, run WAVE, and inspect the ARIA panel for a dialog node with no associated name.
- Screen reader spot check: open the modal with VoiceOver or NVDA; if it announces "dialog" with no title, the name is missing.
How to fix it
Prefer aria-labelledby pointing at the visible heading, because the name then always matches what sighted users read. Only fall back to aria-label when there is genuinely no on-screen title. For an alertdialog, add aria-describedby targeting the body copy so the warning message is announced along with the name. Make sure the id you reference actually exists and is unique, and that the dialog receives focus on open. Buttons inside the dialog have their own naming requirement, covered in buttons must have discernible text, and the same accessible-name concept extends to widgets like ARIA tooltip must have an accessible name.
A few implementation details save you from re-opening this ticket later. Reference the heading by its id even if you already render that heading visually, because the visible heading and the accessible name are two different systems and only the association guarantees they stay in sync. If your modal is portaled to the end of the <body>, which most modern component libraries do, confirm the referenced id still resolves after the portal moves the DOM node. Keep the name short and specific: "Delete this project?" beats "Confirmation," because it tells the user what they are confirming. And when a single component powers many dialogs, generate the title id dynamically so two open-and-close cycles never leave duplicate ids in the tree, which would quietly break the aria-labelledby lookup.
Frequently asked questions
Can I use the native <dialog> element instead?
Yes, and it is a solid choice, but it still needs a name. A native <dialog> without a title, aria-label, or aria-labelledby announces just as poorly, so name it the same way.
Which is better here, aria-label or aria-labelledby?
Reach for aria-labelledby whenever a visible heading exists, since it keeps the spoken and visible names in sync. Use aria-label only when no visible title is present.
Do I need both a name and aria-modal?
They solve different problems. The accessible name tells users what the dialog is; aria-modal="true" tells assistive tech to treat content behind it as inert. Ship both, plus a real focus trap.
When should I choose alertdialog over dialog?
Use alertdialog for urgent, interruptive messages that need an immediate response, such as a destructive-action confirmation. For everything else, dialog is the right role.
Need a full technical audit?
SEO ProCheck runs deep crawls that catch issues like this across your whole site.
Claude Vincent is a technical SEO consultant focused on crawlability, rendering, and AI-search visibility. He writes the field guides and case studies at SEO ProCheck, with a bias toward the durable, unglamorous work that decides whether search engines and AI answer engines can actually read and cite a site.
About SEO ProCheck
Technical SEO consulting and GEO strategy with 20 years of enterprise experience. Case studies, resources, and tools for search and AI visibility.
Work With Me
Technical SEO audits, GEO strategy, site migrations, and international SEO. Hourly consulting for teams who need hands-on support, not just reports.
Subscribe to our newsletter!
