ARIA dialog accessible name required

ARIA dialogs and alertdialogs must not be missing an accessible name

Each element with role="dialog" or role="alertdialog" must expose a clear accessible name. This applies to modals, popups implemented as dialogs, and alert prompts. Without a name, assistive technology cannot present purpose or context when the dialog opens.

Why It Matters

Screen reader users depend on the dialog’s name to understand what just appeared and what task it supports. A nameless dialog is announced generically, which is disorienting and slows navigation.

Speech input users often use visible titles as verbal targets; if no programmatic name exists, voice commands may fail. Clear naming also reduces cognitive load for users who benefit from immediate context.

Common Causes

• role="dialog" or role="alertdialog" added without aria-label or aria-labelledby
• aria-labelledby points to an ID that doesn’t exist, is not unique, or is created after open
• The referenced heading is empty, offscreen, or hidden with aria-hidden/display:none
• An empty aria-label (e.g., aria-label="") is set by mistake
• Relying only on the title attribute (inconsistent and not visible to sighted users)
• Copy/paste of modal templates that reuse the same ID across pages

How to Fix

1. Prefer a visible heading and aria-labelledby
   • Place a heading (e.g., h2) inside the dialog that states its purpose.
   • On the dialog container, set aria-labelledby to the heading’s ID.
   • Ensure the referenced element exists when the dialog opens, is unique, and not hidden.
2. Use aria-label when there is no visible title
   • Provide a short, specific name on the dialog container with aria-label.
   • Keep it concise (2–6 words) and avoid filler like “Dialog” or brand names.
3. Alert dialogs
   • role="alertdialog" should have a brief, direct label that summarizes the alert (e.g., “Delete this file?”, “Payment failed”).
   • Use aria-describedby to point to supporting text if needed.
4. Library components
   • Use the library’s title/label props that map to aria-labelledby or aria-label.
   • Confirm emitted markup sets a name on the element with role="dialog"/"alertdialog".
5. Additional recommendations
   • If the dialog is modal, set aria-modal="true" and move focus to the dialog on open (best practice). This does not replace the name.
   • Avoid using the title attribute for naming; while some AT may read it, it’s not reliable for users.

How to Test

Keyboard

• Open the dialog using only the keyboard.
• Verify focus moves into the dialog (best practice) and that the dialog container has a computed accessible name.

Screen reader

• With NVDA or JAWS (Windows) or VoiceOver (macOS), open the dialog.
• Expect an announcement like “dialog” or “alert dialog” followed by the dialog’s name.
• Use the browser’s Accessibility panel or screen reader element list to confirm the dialog node has the expected name.

Mobile/touch

• With TalkBack (Android) or VoiceOver (iOS), open the dialog.
• Confirm the dialog type and its title are announced immediately.

Quick checklist

• The dialog/alertdialog node exposes a non-empty accessible name
• aria-labelledby references a visible, non-hidden element with text
• Referenced IDs exist, are unique, and are present at open time
• aria-label (if used) is short and descriptive
• Alert dialogs state the condition or required decision, not just button names

Good Example

<div role="dialog" aria-modal="true" aria-labelledby="settings-title" aria-describedby="settings-help">
  <h2 id="settings-title">Profile settings</h2>
  <p id="settings-help">Update your contact details and notification preferences.</p>
  <form>
    <!-- form fields -->
  </form>
  <button type="button" aria-label="Close settings">Close</button>
</div>

<!-- Alert dialog variant using aria-label -->
<div role="alertdialog" aria-modal="true" aria-label="Remove item?" aria-describedby="remove-desc">
  <p id="remove-desc">This action will delete the selected item. You can’t undo this.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

Bad Example

<!-- Missing name entirely -->
<div role="dialog">
  <h2>Untitled</h2>
</div>

<!-- aria-labelledby points to a missing element -->
<div role="alertdialog" aria-labelledby="missing-title">
  <p>Are you sure?</p>
</div>

<!-- Empty aria-label and hidden referenced title -->
<div role="dialog" aria-label="" aria-labelledby="hidden-title">
  <h2 id="hidden-title" aria-hidden="true">Payment</h2>
</div>

Quick Checklist

• role is dialog or alertdialog, and the element has a non-empty accessible name
• Prefer aria-labelledby referencing a visible heading inside the dialog
• If no visible title, use a concise aria-label on the dialog container
• Confirm referenced IDs exist, are unique, and not hidden
• Alert dialogs summarize the condition or decision in the name
• Verify with a screen reader that the name is announced on open
• Avoid using only the title attribute for naming
• Keep names short, specific, and free of redundant words like “dialog”