a11y/dialog-name

Why

When a dialog opens, a screen reader announces its name and role first. Without a name the user hears only "dialog" and must explore it to learn whether it is a confirmation, an error or a form.

Fix

Give the dialog a visible heading with an id and set aria-labelledby to it; use aria-label only when there is no visible title. For an alert dialog, also point aria-describedby at the message.

Examples

<!-- bad -->
<dialog><h2>Delete project?</h2>…</dialog>
<!-- good -->
<dialog aria-labelledby="del-title"><h2 id="del-title">Delete project?</h2>…</dialog>

Sources

• WAI-ARIA Authoring Practices, Dialog (Modal) pattern
• W3C, WAI-ARIA 1.2, dialog role (name required)

Read it in the terminal

npx github:dawidolko/frontend-skills explain a11y/dialog-name