aria-role-name-present
ARIA roles that require an accessible name have one
Checks that the ARIA roles WAI-ARIA requires an accessible name for expose a non-empty one.
Applies to. Applies to elements whose role attribute resolves to one of grid, meter, progressbar, radiogroup or tree (its first token naming a known role, matched in any case: role="foo tree" and role="TREE" count, role="link tree" does not), and that are included in the accessibility tree. Membership is decided by WAI-ARIA's own "Accessible Name Required: True" characteristic, not by whether a role merely permits a name: tablist, toolbar, menu, menubar and scrollbar are name-from-author roles the spec does not require a name for, and are out of scope. meter and progressbar are also covered by meter-name-present and progressbar-name-present, which map to SC 1.1.1; this rule is what gives those two roles their 4.1.2 coverage. A custom element whose ElementInternals give it one of those roles (this.attachInternals().role), with no role attribute naming another, is in scope too: that is its default role, and no other rule checks it. A variant with the setting roles: 'all' also checks application, marquee, table, tabpanel and treegrid, the other name-from-author roles WAI-ARIA requires a name for: a standard for WAI-ARIA asks it, and a WCAG scan does not, as an unnamed table is common and usually no WCAG failure.
Expectation. The element has a non-empty aria-label, an aria-labelledby that resolves to non-empty text, or a non-empty title. Every role in the set is name-from-author-only, so descendant text is not accepted: a labelled child inside a composite widget would otherwise pass the container that has no name of its own. The name the HTML host element gives itself counts too, since the browser still computes it under the role: the first child <legend> of a <fieldset>, the first child <caption> of a <table>, and an associated <label> on a labelable element such as <progress> or <meter>. A missing name is reported at CANTTELL, not FAIL. The requirement is WAI-ARIA's ("Accessible Name Required: True"), and none of these roles is by itself a user interface component in WCAG's sense, "a single control for a distinct function": a grid, tree or radiogroup is a container of controls (its cells, items or radios, each named by its own rule), and a meter or progressbar is no control at all. So a missing name proves the WAI-ARIA violation, not a failure of SC 4.1.2. It can still be one, or a failure of another criterion, depending on the page: a visible question above a radiogroup that is not tied to it, a visible title for a grid that is not tied to it. A person settles that. A meter or progressbar with no text alternative fails SC 1.1.1 through meter-name-present and progressbar-name-present.
What a finding reports.
role: the role that needs a name, one ofgrid,meter,progressbar,radiogroupandtree. A stable contract, unlike the rest ofdata.details.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<div role="grid" aria-label="Orders"></div>
role="grid" requires an accessible name, and aria-label provides one.
<div role="grid"></div>
role="grid" requires an accessible name in WAI-ARIA; none is present. A grid is a container of controls, not a single control, so whether a WCAG criterion fails depends on whether the page shows a title for it 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 custom element the report names 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 element, set through its internals or otherwise, and the screen reader announces it.
Fail. The element 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 page shows a title or question for the element that is not tied to it (WCAG 1.3.1).
name_missing
- Inspect the element the report names and note its role (grid, tree, radiogroup, meter or progressbar).
- Look at what the page shows for it: a visible title, heading, caption or question that tells people what it is.
- If it shows one, check whether it is tied to the element, with aria-labelledby or the element's own HTML label (a legend or caption).
Pass. Nothing visible names the element or asks a question about it, so no information shown on the page is missing from the accessibility tree. Still give it a name: WAI-ARIA requires one.
Fail. The page shows a title or question for the element that is not tied to it, so that relationship is not programmatically determinable (WCAG 1.3.1).