aria-dialog-name
Web validation
role="dialog" or role="alertdialog" should have an accessible name.A dialog communicates important information or requires user interaction. Without an accessible name, assistive technology users may not know the purpose of the dialog. This creates confusion and makes it harder to interact with the content inside the dialog.
An accessible name can come from the attributes aria-label or aria-labelledby. Providing this name ensures dialogs are announced clearly and understood in context.
Pass Patterns
Using aria-label
This dialog has an accessible name with aria-label.
<div role="dialog" aria-modal="true" aria-label="Subscribe to newsletter">
<p>Enter your email address to subscribe.</p>
</div>Using aria-labelledby
This dialog takes its accessible name from its visible heading through aria-labelledby.
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
<h2 id="dialog-title">Subscribe to newsletter</h2>
<p>Enter your email address to subscribe.</p>
</div>Fail Patterns
Missing name
This dialog has no accessible name.
<div role="dialog" aria-modal="true">
<!-- A login form -->
</div>Non-existent aria-labelledby references
This dialog references a missing element for its name.
<div role="dialog" aria-modal="true" aria-labelledby="missingTitle">
<!-- A login form -->
</div>Try It Yourself
Using a screen reader
New to screen reader testing, or need a refresher?
Review this article first: Practical guides for using screen readers
- Load the page, open a screen reader.
- Trigger the dialog.
- Listen to the announcement when focus moves into the dialog.
Expected result: The dialog is announced with its accessible name and role.
Actual result: The dialog is announced only as “dialog” or “alert dialog” without a clear purpose.
Inspecting the browser dev-tools
- Open the Accessibility Tree panel.
- Trigger the dialog.
- Select the dialog element.
Expected result: The Name field shows the text you provided.
Actual result: If unnamed, Name is empty.
FAQ
Why is this validation considered a best practice?
Although not directly tied to a specific WCAG success criterion, providing accessible names for dialog elements is significantly important for assistive technology users to understand the context and purpose of the dialog.
Why is this issue marked as Serious?
When a dialog lacks an accessible name, assistive technology users cannot understand its purpose. This creates a significant barrier when completing tasks that require dialogs, such as forms, confirmations, or warnings.