ARIA dialog and alertdialog nodes should have an accessible name

When a dialog appears on screen, assistive technologies announce it to the user along with its accessible name. This name gives essential context — it tells the user what the dialog is about, such as “Confirm deletion” or “Sign in to your account.” Without an accessible name, screen reader users hear that a dialog has opened but have no way to understand its purpose, which can be disorienting and make the interface difficult to use.

This issue primarily affects users who are blind or have low vision and rely on screen readers, as well as users with mobility impairments who navigate with assistive technology. It is flagged as a serious issue by the axe accessibility engine and aligns with Deque’s accessibility best practices.

How to Fix It

Ensure every element with role="dialog" or role="alertdialog" has an accessible name using one of these methods:

1. aria-label — Provide a concise, descriptive name directly on the dialog element.
2. aria-labelledby — Reference the id of a visible element (typically a heading) inside the dialog that serves as its title.
3. title — Use the HTML title attribute as a fallback, though aria-label or aria-labelledby are preferred.

Whichever method you choose, make sure the name clearly describes the dialog’s purpose. Avoid empty strings or references to elements that don’t exist or have no text content.

Examples

Incorrect: Dialog with No Accessible Name

The dialog has no aria-label, aria-labelledby, or title, so screen readers cannot announce its purpose.

<div role="dialog">
  <h2>Unsaved Changes</h2>
  <p>You have unsaved changes. Do you want to save before leaving?</p>
  <button>Save</button>
  <button>Discard</button>
</div>

Incorrect: Empty aria-label

An empty aria-label provides no useful information to assistive technologies.

<div role="alertdialog" aria-label="">
  <p>An error occurred while saving your file.</p>
  <button>OK</button>
</div>

Incorrect: aria-labelledby Pointing to a Nonexistent or Empty Element

If the referenced element doesn’t exist or contains no text, the dialog still has no accessible name.

<div role="dialog" aria-labelledby="dialog-title">
  <p>Please confirm your selection.</p>
  <button>Confirm</button>
</div>
<!-- No element with id="dialog-title" exists -->

<div role="dialog" aria-labelledby="dialog-title">
  <span id="dialog-title"></span>
  <p>Please confirm your selection.</p>
  <button>Confirm</button>
</div>

Correct: Using aria-labelledby to Reference a Heading

The aria-labelledby attribute points to the dialog’s visible heading, giving it a clear accessible name.

<div role="dialog" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Unsaved Changes</h2>
  <p>You have unsaved changes. Do you want to save before leaving?</p>
  <button>Save</button>
  <button>Discard</button>
</div>

Correct: Using aria-label

The aria-label attribute provides a concise name directly on the dialog.

<div role="alertdialog" aria-label="File save error">
  <p>An error occurred while saving your file. Please try again.</p>
  <button>Retry</button>
  <button>Cancel</button>
</div>

Correct: Using the title Attribute

The title attribute works as a fallback naming mechanism, though aria-label or aria-labelledby are generally preferred because title has inconsistent support across assistive technologies.

<div role="dialog" title="Export Settings">
  <p>Choose a format for your export.</p>
  <select>
    <option>PDF</option>
    <option>CSV</option>
  </select>
  <button>Export</button>
  <button>Cancel</button>
</div>

Learn more:

Deque Reference

Deque University - How To Fix

→