ARIA dialogs must have an accessible name.

Elements with role="dialog" or role="alertdialog", as well as native <dialog> elements, must have an accessible name. When a dialog opens, screen readers announce its role (e.g., "dialog") along with its accessible name. Without a name, users who rely on assistive technology hear only "dialog" with no context about what the dialog contains or why it appeared. This forces them to explore the dialog's contents to understand its purpose, which is disorienting and slows them down.

This rule applies to WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value), Level A. That criterion requires all user interface components to have a name that can be programmatically determined. Dialogs are interactive components that take over part of the user experience, so they need a name just like form controls and links do.

How to fix it

There are two common ways to give a dialog an accessible name:

1. Use aria-labelledby to point to the dialog's visible heading. This is the preferred approach because it keeps the visible heading and the accessible name in sync. Set the heading's id and reference it from the dialog's aria-labelledby attribute.

2. Use aria-label to provide a name directly when the dialog has no visible heading. The value of aria-label becomes the accessible name.

These techniques work for elements with role="dialog", role="alertdialog", and the native <dialog> element.

Choose a name that describes the dialog's purpose. A confirmation dialog might be named "Confirm deletion", while a login dialog might be named "Sign in". Avoid generic names like "Dialog" or "Pop-up" — they don't help users understand what the dialog is for.

Examples

Missing accessible name

This dialog has no aria-label or aria-labelledby, so screen readers announce it without a name.

<div role="dialog">
  <h2>Delete this file?</h2>
  <p>This action cannot be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

Fixed with aria-labelledby

The aria-labelledby attribute references the heading's id, giving the dialog a descriptive accessible name.

<div role="dialog" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Delete this file?</h2>
  <p>This action cannot be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

Fixed with aria-label

When a dialog has no visible heading, aria-label provides the accessible name directly.

<div role="dialog" aria-label="Confirm file deletion">
  <p>This action cannot be undone. Are you sure?</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

Native <dialog> element with aria-labelledby

The native <dialog> element needs an accessible name too. The same techniques apply.

<dialog aria-labelledby="native-dialog-title">
  <h2 id="native-dialog-title">Sign in</h2>
  <form method="dialog">
    <label for="email">Email</label>
    <input id="email" type="email">
    <label for="password">Password</label>
    <input id="password" type="password">
    <button type="submit">Sign in</button>
  </form>
</dialog>

Alert dialog with aria-labelledby

Alert dialogs (role="alertdialog") follow the same rules. They are typically used for urgent messages that require immediate user action.

<div role="alertdialog" aria-labelledby="alert-title">
  <h2 id="alert-title">Unsaved changes</h2>
  <p>You have unsaved changes. Do you want to leave without saving?</p>
  <button>Stay</button>
  <button>Leave</button>
</div>

Learn more:

W3C Reference

Understanding Name, Role, Value

→

MDN Reference

ARIA: dialog role

→

W3C Reference

WAI-ARIA Authoring Practices: Dialog (Modal)

→