dialog-name-present
Dialogs have an accessible name
Checks that dialogs (elements with role="dialog" or role="alertdialog", and native <dialog> elements) expose a non-empty accessible name.
Applies to. Applies to elements included in the accessibility tree whose role is dialog or alertdialog: an element whose role attribute resolves to one of those roles (the first token that names a concrete ARIA role wins, so role="alertdialog dialog" is an alertdialog), and a native <dialog> whose role attribute is absent or names no concrete role (its implicit role is dialog). A closed <dialog> is hidden and so not in scope. A custom element whose ElementInternals give it one of those roles (this.attachInternals().role), with no role attribute naming another, counts as a native element with that role does.
Expectation. The element has a non-empty accessible name from aria-label, from an aria-labelledby that resolves to non-empty text, or from title. Both roles are name-from-author-only, so the heading or body text inside the dialog is not accepted as its name unless aria-labelledby points at it. A missing name is reported at CANTTELL, not FAIL. WAI-ARIA requires it ("Authors MUST provide an accessible name for a dialog"), but a dialog is not itself a user interface component in WCAG's sense, "a single control for a distinct function": its controls are, and each is named by its own rule. So the missing name proves the WAI-ARIA violation, not a failure of SC 4.1.2. It can still be a WCAG failure where the dialog shows a visible title that is not tied to it (that relationship is then not programmatically determinable, SC 1.3.1); a person settles that.
Examples
<div role="dialog" aria-label="Confirm deletion"><p>Are you sure?</p></div>
aria-label names the dialog.
<div role="dialog"><p>Body text only.</p></div>
No accessible name, which WAI-ARIA requires; visible body text doesn't count toward a dialog's name. A dialog is not a single control, so whether a WCAG criterion fails depends on whether it shows a title that is not tied to it.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
name_internals
- Inspect the dialog the report names, a custom element, and note its role.
- Open the Accessibility pane in the browser's developer tools and read the element's accessible name.
- With a screen reader, move to the element and listen to the name announced.
Pass. The accessibility tree shows a name for the dialog, set through its internals or otherwise, and the screen reader announces it.
Fail. The dialog has no name in the accessibility tree and the screen reader announces only its role. That breaks WAI-ARIA; it fails WCAG only where the dialog shows a title that is not tied to it (WCAG 1.3.1).
name_missing
- Inspect the dialog the report names and note its role (dialog or alertdialog).
- Look for a visible title or heading at the top of the dialog.
- If there is one, check whether the dialog points at it with aria-labelledby.
Pass. The dialog shows no title, so nothing visible is missing from the accessibility tree. Still give it a name: WAI-ARIA requires one.
Fail. The dialog shows a title that is not tied to it, so the relationship between the dialog and its title is not programmatically determinable (WCAG 1.3.1).