# ARIA dialogs must have an accessible name.

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/labels-and-names/aria-dialog-name
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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.

```html
<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.

```html
<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.

```html
<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.

```html
<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.

```html
<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>
```