aria-dialog-name

Description

The aria-dialog-name rule ensures that elements with role="dialog" or role="alertdialog" have an accessible name. When a dialog opens, screen readers announce the dialog and its name before reading its contents. Without a name, users do not know the purpose of the dialog before they begin exploring it, which disrupts orientation and understanding.

This rule meets WCAG requirements by:

1. Programmatic Name Determination (WCAG 4.1.2 Name, Role, Value): It ensures that the name of every dialog can be programmatically determined by assistive technologies, so users understand the dialog’s purpose as soon as focus moves into it.
2. Descriptive Labels (WCAG 2.4.6 Headings and Labels): It ensures that dialogs have a label that accurately describes the topic or purpose of the interaction they present.

To comply with this rule, provide an accessible name for every dialog using aria-label or aria-labelledby referencing a heading or title within the dialog.

Examples

This example shows a dialog element with no accessible name. When focus moves to the dialog, a screen reader announces only “dialog”, giving users no context about its purpose.

Here, aria-labelledby references the heading inside the dialog, so screen readers announce “Confirm deletion, dialog” when focus enters.

How to fix?

To fix violations of the aria-dialog-name rule, follow these steps:

• Add a visible heading (such as <h2>) inside the dialog that describes its purpose, and reference it from the dialog element using aria-labelledby="heading-id".

• If a visible heading is not appropriate for the dialog design, add an aria-label attribute directly on the dialog element with a concise name that describes the dialog’s purpose.

• Ensure that aria-labelledby references an element whose id matches exactly, and that the referenced element contains meaningful, descriptive text.

Reference

• WCAG Success Criterion 4.1.2: Name, Role, Value

• WCAG Success Criterion 2.4.6: Headings and Labels