ARIA Dialog and Alertdialog Must Have an Accessible Name: How to Fix It

What this rule checks

The axe-core rule aria-dialog-name inspects every element that carries role="dialog" or role="alertdialog" and confirms each one exposes a discernible, accessible name. An element passes when it has a non-empty aria-label, an aria-labelledby attribute that references an element containing readable text, or a title attribute that resolves to text. If none of those produce a name, axe-core flags the dialog. This is classified as a best-practice rule that supports the WAI-ARIA Authoring Practices for the dialog pattern.

Why dialogs need names: focus context for screen readers

A dialog is a focus trap. When it opens, keyboard and screen reader focus moves into the container, and the rest of the page is usually inert. At that moment the screen reader announces the role ("dialog" or "alert dialog") together with the accessible name. If there is no name, a sighted user sees the heading and understands the context, but a screen reader user hears only "dialog" with no indication of purpose. They are now trapped inside an unlabeled region with no idea whether it is a sign-up form, a delete confirmation, or a cookie notice.

The accessible name is what orients the user. It answers the first question anyone asks when a window appears in front of them: what is this, and why am I here? Providing that name is the difference between a usable interruption and a disorienting one.

dialog vs alertdialog

Both roles need a name, but they signal different intent. Use role="dialog" for a general interactive window such as a form, a settings panel, or a media lightbox. Use role="alertdialog" when the dialog conveys an urgent message that requires a response, such as confirming a destructive action or warning that unsaved changes will be lost. The alertdialog role carries assertive semantics, so assistive technology treats its appearance as more pressing. With either role, the name comes from the same attributes, and an alertdialog additionally uses aria-describedby to point at the body message that explains the alert.

How to diagnose

Open your browser developer tools and search the DOM for role="dialog" and role="alertdialog". For each match, check whether it has a non-empty aria-label, an aria-labelledby whose target id actually exists and contains text, or a title. The accessibility panel in Chrome or Firefox dev tools shows the computed name for the selected node, which is the fastest way to confirm a name is present. You can also run the axe DevTools browser extension, which reports the exact failing node. Watch out for dialogs that are rendered only after a user action, such as opening a modal, because they will not appear in the DOM until triggered.

How to fix

Option 1: aria-labelledby pointing to the dialog heading (preferred)

If the dialog already shows a visible title, reuse it. Give the heading an id and reference that id from aria-labelledby. This keeps the visible label and the accessible name in sync, so they never drift apart.

<!-- Bad: dialog with a heading but no programmatic name -->
<div role="dialog" aria-modal="true">
  <h2>Edit your profile</h2>
  <!-- form fields -->
</div>

<!-- Good: aria-labelledby ties the name to the visible heading -->
<div role="dialog" aria-modal="true" aria-labelledby="dlg-title">
  <h2 id="dlg-title">Edit your profile</h2>
  <!-- form fields -->
</div>

Option 2: aria-label when there is no visible title

If the dialog has no on-screen heading to point at, supply the name directly with aria-label.

<!-- Bad: alertdialog with no name at all -->
<div role="alertdialog">
  <p>Deleting this item cannot be undone.</p>
  <button>Delete</button> <button>Cancel</button>
</div>

<!-- Good: aria-label names it, aria-describedby carries the message -->
<div role="alertdialog" aria-label="Confirm deletion"
     aria-describedby="del-msg">
  <p id="del-msg">Deleting this item cannot be undone.</p>
  <button>Delete</button> <button>Cancel</button>
</div>

Common mistakes

No name supplied. The most frequent failure is a dialog built from a plain div with the role added but no labelling attribute. The visible heading does not name the dialog automatically; you must connect them with aria-labelledby.

aria-labelledby pointing at the wrong place. A reference to an id that does not exist, or one that points at a hidden or empty element, produces no name. If the heading is removed with display:none or has no text content, the dialog still fails.

Confusing the name with the description. Using aria-describedby alone does not satisfy the rule. The description explains the body content; the name still has to come from aria-label or aria-labelledby.

Empty values. An aria-label="" or an aria-labelledby that resolves to whitespace is treated as no name. Make sure the text is real and meaningful.

FAQ