ARIA dialog and alertdialog elements must have an accessible name
Content available in English only.
Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).
These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.
Every dialog must have a name; announcing 'dialog' alone is not enough.
Why this matters and how to fix it
Why this matters
Screen readers announce dialogs immediately when they appear. Without an accessible name, users only hear 'dialog' with no context, making it unclear what the dialog is for or what action is needed.
How to fix this issue
Provide a programmatically associated name for all dialogs (`role="dialog"` or `role="alertdialog"`). Use a visible heading inside the dialog and reference it with `aria-labelledby`, or use `aria-label` if no heading exists.
Developer guidance
For custom modal components, enforce a title prop mapped to `aria-labelledby` or `aria-label`. Test with screen readers to ensure the dialog role and name are announced. Remember to also implement focus trapping and background inertness separately.
Code examples
Incorrect Implementation
<div role="dialog">Are you sure you want to delete?</div>Correct Implementation
<div role="dialog" aria-labelledby="dialogTitle"><h2 id="dialogTitle">Confirm deletion</h2><p>Are you sure you want to delete this item?</p></div>Real-World Examples
Before
<div role="dialog">Update available</div> <!-- Screen reader announces only 'dialog' -->After
<div role="dialog" aria-labelledby="updateTitle"><h2 id="updateTitle">Software Update</h2><p>A new update is ready to install.</p></div> <!-- Screen reader announces 'Software Update, dialog' -->Manual testing
- 1. Identify all elements with `role="dialog"` or `role="alertdialog"`.
- 2. Verify each has an accessible name via visible heading (`aria-labelledby`) or `aria-label`.
- 3. Open dialogs with keyboard only and ensure the name is announced by the screen reader.
- 4. Confirm that focus is trapped inside the dialog and background content is inert.
- 5. Automate tests for dialog naming in your CI pipeline.
Trusted by organizations across Europe working toward WCAG and EAA conformance