What This Rule Checks
When a dialog appears on a webpage, it must provide a clear and accessible name to help users of assistive technologies, such as screen readers, understand its purpose. Without an accessible name, users may struggle to interact with the dialog properly, resulting in a poor user experience.
Who Is Affected
This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Low Vision users, who may use screen magnification, custom fonts, or high-contrast modes; Mobility users, who navigate using keyboards, switches, voice control, or other assistive input devices.
Why This Matters
When a dialog opens, screen readers announce its name to help users understand the context switch. Unnamed dialogs are announced as “dialog” with no indication of their purpose, leaving users disoriented.
How to Fix
To make ARIA dialogs accessible, follow these steps:
Use aria-labelledby or aria-label: Ensure the dialog element has an accessible name by applying either the aria-labelledby attribute, which references an external element, or the aria-label attribute, which directly provides a label.
Ensure Clear Naming: The dialog name should describe the purpose of the dialog. Make sure that whatever method you use (whether aria-labelledby or aria-label) is clear and meaningful to users.
Code Examples
<!-- Dialog with no accessible name -->
<div role="dialog">
<h2>Settings</h2>
<p>Choose your preferences</p>
</div>
Copy
<!-- Dialog with aria-labelledby -->
<div role="dialog" aria-labelledby="dialog-title">
<h2 id="dialog-title">Settings</h2>
<p>Choose your preferences</p>
</div>
Copy
Common Mistakes to Avoid
- Opening a modal dialog without giving it an accessible name.
- Using aria-label with a different text than the visible dialog heading.
- Forgetting to update the dialog name when its content changes dynamically.
AI Auto-Fix Available
This rule supports ACE™ AI Auto-Fix. When a violation is detected, ACE can automatically generate a code fix for review. The AI analyzes the specific element in context and proposes a targeted remediation that preserves your existing markup and styling. You can preview, modify, and approve the fix before it is applied.
Tip: Remember the first rule of ARIA: don’t use ARIA if a native HTML element can provide the same semantics. Native elements come with built-in keyboard handling and screen reader support that ARIA cannot replicate.