• June 1, 2025

Accessible Naming for ARIA Dialogs

Rule ID: aria-dialog-name
Ruleset: axe-core 4.10
User Impact: Serious
Guidelines: Deque Best Practice

How to Fix the Problem

To comply with this rule, ensure that every element using role="dialog" or role="alertdialog" includes a meaningful, accessible name. This name must be understandable by screen reader users. You can fix the issue by implementing one of the following markup strategies:

✅ Correct Examples

1. Using aria-labelledby:

   html

   KopierenBearbeiten

   <div role="dialog" id="alb" aria-labelledby="labeldiv"></div>
<div id="labeldiv">Dialog Title</div>


   This approach points to another element that contains readable text.

2. Using aria-label:

   html

   KopierenBearbeiten

   <div role="alertdialog" id="combo" aria-label="Aria Name">Name</div>


   The aria-label attribute directly provides the name.

3. Using title:

   html

   KopierenBearbeiten

   <div role="dialog" id="title" title="Title"></div>


   The title attribute can be used as a fallback, though it’s not as robust as ARIA attributes.

❌ Incorrect Examples

Avoid the following patterns, which fail the accessibility check:

• No label or title at all:

  html

  KopierenBearbeiten

  <div role="dialog" id="empty"></div>


• Empty aria-label:

  html

  KopierenBearbeiten

  <div role="alertdialog" id="alempty" aria-label=""></div>


• aria-labelledby references a non-existent element:

  html

  KopierenBearbeiten

  <div role="dialog" id="albmissing" aria-labelledby="nonexistent"></div>


• aria-labelledby references an empty element:

  html

  KopierenBearbeiten

  <div role="dialog" id="albempty" aria-labelledby="emptydiv"></div>
<div id="emptydiv"></div>


Why it Matters

Screen reader users rely on accessible names to understand the purpose and context of a dialog. Without a name, these users may be confused or unaware of the dialog’s purpose. This is especially problematic for modals and alerts that demand user interaction, as they can appear with no context.

A missing or empty name causes screen readers to skip over the dialog or announce unhelpful default phrases like “dialog”, providing no clarity on the dialog’s function or importance. Providing an accessible name ensures all users can understand and interact with modal content.

Rule Description

All elements using role="dialog" or role="alertdialog" must have a discernible text label. This label provides essential information about the dialog’s purpose and helps screen reader users navigate and understand the page structure effectively.

The Algorithm (in simple terms)

The rule checks:

1. If any element has role="dialog" or role="alertdialog".

2. Then, it verifies whether the element has:

   • A non-empty aria-label, or

   • A valid aria-labelledby pointing to visible and meaningful text content.

If neither condition is met, the rule fails.