modal-lacks-an-accessible-name
Web validation
<dialog> element or with role="dialog" or role="alertdialog", should have an accessible name.A modal 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. This applies to native <dialog> elements in the same way as to custom dialogs: the <dialog> element does not take its name from its heading or its content automatically. Providing this name ensures dialogs are announced clearly and understood in context.
Note: This validation covers both native <dialog> elements and elements with role="dialog" or role="alertdialog". The related aria-dialog-name validation covers only the ARIA roles.
Pass Patterns
Native <dialog> using aria-labelledby
This native dialog takes its accessible name from its visible heading through aria-labelledby.
<dialog id="subscribe-dialog" aria-labelledby="dialog-title">
<h2 id="dialog-title">Subscribe to newsletter</h2>
<p>Enter your email address to subscribe.</p>
</dialog>
<script>
document.getElementById("subscribe-dialog").showModal();
</script>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
Native <dialog> with no name
This native dialog has a visible heading, but nothing connects it to the dialog, so the dialog has no accessible name.
<dialog id="subscribe-dialog">
<h2>Subscribe to newsletter</h2>
<p>Enter your email address to subscribe.</p>
</dialog>
<script>
document.getElementById("subscribe-dialog").showModal();
</script>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 modal 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 modal dialog.
- Select the
<dialog>element, or the element with the dialog role.
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 modal dialogs 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 modal 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.
How is this different from aria-dialog-name?
The two validations check the same requirement. This one also covers native <dialog> elements, while aria-dialog-name covers only elements with role="dialog" or role="alertdialog".