Ensure every ARIA dialog and alertdialog node has an accessible name

The aria-dialog-name rule checks whether every role="dialog" or role="alertdialog" element has an accessible name. An accessible name allows screen readers and assistive technologies to announce the purpose of the dialog to users, which is critical for understanding and navigation.

What is being tested?

The rule verifies that each dialog or alertdialog element has an accessible name. This name can come from:

• the aria-label attribute,
• the aria-labelledby attribute pointing to a visible heading or text, or
• the native text content of the dialog (depending on the implementation).

Common causes of failure

• Dialogs missing an aria-label or aria-labelledby.
• Using aria-labelledby that points to an element with no text content.
• Displaying a dialog with only icons or images without a text label.

How to fix it?

• Add an aria-label that describes the purpose of the dialog, e.g., <div role="dialog" aria-label="Settings">.
• Use aria-labelledby to reference a heading inside the dialog, e.g., aria-labelledby="dialog-title" and <h2 id="dialog-title">Settings</h2>.
• Ensure any referenced label or heading contains meaningful text.