The aria-dialog-name rule flags an element with role="dialog" or role="alertdialog" that has no accessible name. When the dialog opens, a screen reader announces "dialog" and nothing about what it is for. The fix is almost always one attribute: aria-labelledby pointing to the dialog's visible heading.
What the rule means
A dialog is a window on top of the page: a cookie banner, a login form, a "remove item?" confirmation, a cart drawer. Its name is what assistive technology reads when focus moves into it. axe accepts three ways to give one:
aria-labelledbypointing to an element with text, usually the heading;aria-labelwith the name as text, where there is no visible heading;- a non-empty
titleattribute – valid, but the weakest of the three.
The rule only tests elements with an explicit role="dialog" or role="alertdialog", and only while they are displayed. A native <dialog> element without a role attribute is not checked by it at all, though it needs a name just as much.
This is a best practice, not a WCAG failure in itself. It relates to two criteria: 4.1.2 Name, Role, Value, because a dialog is a user interface component whose name should be available to assistive technology, and 2.4.6 Headings and Labels, because a name only helps if it describes the dialog's purpose.
Who is affected
Mainly blind and partially sighted people using a screen reader. When focus jumps into an unnamed dialog, they hear "dialog" followed by whatever element got focus – often just "Close, button" – and must explore the dialog to find out whether it is asking for consent, a password or confirmation to delete something. Screen magnifier users, who see only part of the screen, benefit from a clear name as well.
Why the check fails
- Modal libraries and UI kits that set
role="dialog"on the container but leave naming to the developer, who never passes a title. - Cookie consent banners built as dialogs with a heading that is not linked to the container.
- A visible heading without an id, so
aria-labelledbyhas nothing to point to. aria-labelledbyto an id that does not exist, after the heading was renamed or removed.- Confirmation dialogs (
role="alertdialog") with only a message and two buttons. - Chat and newsletter pop-ups injected by third-party scripts.
How to fix it
- Give the dialog's visible heading an
idand pointaria-labelledbyto it. Visible and spoken name are then the same. - With no heading, use
aria-labelwith a short, specific name – "Cookie settings", not "Dialog". - For an
alertdialog, also link the message witharia-describedby, so it is read out together with the name. - Fix it once in the modal component; every dialog built from it inherits the name.
<!-- Before: the dialog has a heading, but nothing links it to the dialog -->
<div class="cookie-modal" role="dialog" aria-modal="true">
<h2 class="cookie-modal__title">Cookie settings</h2>
<p>We only use cookies that keep the shop working.</p>
<button class="btn btn--primary">Accept necessary cookies</button>
</div><!-- After: aria-labelledby names the dialog after its visible heading -->
<div class="cookie-modal" role="dialog" aria-modal="true" aria-labelledby="cookie-title">
<h2 class="cookie-modal__title" id="cookie-title">Cookie settings</h2>
<p>We only use cookies that keep the shop working.</p>
<button class="btn btn--primary">Accept necessary cookies</button>
</div>A native <dialog> needs the same name, even though this rule does not look at it:
<!-- Native dialog: name it the same way -->
<dialog class="confirm" aria-labelledby="confirm-title" aria-describedby="confirm-text">
<h2 id="confirm-title">Remove item?</h2>
<p id="confirm-text">The walking boots will be removed from your basket.</p>
<button>Remove</button> <button>Cancel</button>
</dialog>How to test it manually
- Open every dialog on the page – cookie banner, login, cart, confirmations – because the rule only sees dialogs that are displayed while the page is scanned.
- In the browser's developer tools, select the dialog container and check its name in the Accessibility pane.
- With a screen reader such as NVDA (free) or VoiceOver, open the dialog and listen: you should hear its name and "dialog" as focus moves in.
- Check that the name says what the dialog is for. "Modal" or "Popup" passes the rule and helps nobody.
Related WCAG criterion
None directly – aria-dialog-name is a best practice. It relates to 4.1.2 Name, Role, Value and 2.4.6 Headings and Labels. A dialog that traps or loses keyboard focus is a separate matter for 2.1.2 No Keyboard Trap.
How Reviseberg reports it
Reviseberg runs aria-dialog-name on every crawled page. The issue list shows the rule as a best practice with its severity, the number of elements and pages, and the points a fix gets you back; it never counts against a WCAG criterion and never appears in a compliance report or accessibility statement. The detail view shows the selector and HTML snippet of each dialog and every affected page. The rule only sees dialogs that are displayed when the page is scanned: a cookie banner shown on arrival is tested, a dialog that stays hidden until somebody clicks is not – check those by hand. Findings can be marked "ignore", "can't fix" or "false positive" with a reason, for example for a third-party widget you cannot change; every decision is logged.