ARIA property
aria-labelledby
Names an element by pointing at visible text already on the page. Preferred over aria-label, because the name then matches what people see.
It builds the name out of text already on screen, in the order you list the ids. Change that text and the name changes with it, without you touching the markup that points at it. That is the reason to prefer it over a hand-written string.
Which roles may carry aria-labelledby
- Value
- ID reference list
- Filed as
- A property, which is how ARIA files it and not a rule about how often it changes.
- Roles that may carry it
- Any role. This one is global, which is why no individual role lists it.
Those 12 roles have no name of their own, and ARIA does not merely say that naming them is pointless. It says authors must not do it, which makes it an authoring error rather than harmless extra markup. The one that catches people is generic, because a bare div or span maps to it.
Global means no role has to grant permission for it. There is one more place to check, because ARIA in HTML sets rules per element as well as per role, and it allows no aria-* attributes at all on a datalist or on the html element. Past that, the way a global attribute goes wrong is rarely where it sits. It is whether it is still true, which is the next section.
Every role above comes from the specification's own list for this attribute, checked name for name. The normative definition stays with the W3C, in the aria-labelledby section of the ARIA specification.
Keeping aria-labelledby true
The maintenance is in the ids rather than in the words. An id that stops resolving is dropped without a warning, and if none of them resolve the element is left with no name from this attribute at all. So the ids have to survive every rename, every component split and every move into a portal, and a test that only checks the element has some name will not catch it. The spelling catches people too. Two Ls, because the spec keeps labelledby even while noting that the expected US English spelling is labeledby, since the accessibility APIs underneath established that form. The same twelve roles are off limits here as for aria-label, and how accessible names are computed sets out where this sits in the order.
How aria-labelledby gets checked
There are test rules that check an ARIA attribute is one that exists, is allowed on the role underneath it, and carries a value of the right type. What they map to is ARIA's own author requirements rather than any WCAG criterion, so a misplaced attribute breaks ARIA without being a WCAG failure by itself. It becomes one under 4.1.2 Name, Role, Value the moment the missing or wrong value means the control's state cannot be worked out programmatically, which is what usually happens next.
The value testing skips id references on purpose. Pointing at an element that does not exist and having no pointer at all come to the same end, so a broken reference fails no rule directly. It fails later, wherever the missing name or description was needed.
Nothing automated catches the failure this page is about. A stale value is a valid value, on a permitted role, with the right type. It is only wrong about the world.
Attributes you will meet alongside aria-labelledby
- aria-atomic Whether an update should be read whole, or only the part that changed.
- aria-busy Says a region is still being updated, so wait before announcing it.
- aria-controls Points at what this control operates. A combobox has to say what it opens.
- aria-current Marks the one item in a set that represents the here and now, such as the current page in a nav.
- aria-describedby Points at further description, read after the name. Hints and error text usually go here.
- aria-details Points at richer explanation elsewhere in the page, which people can navigate to rather than have read out.
- aria-flowto Overrides reading order by pointing at what should be read next. Rarely the right answer.
- aria-hidden Removes an element from the accessibility tree while leaving it on screen.
Every ARIA state and property · Every ARIA role · ARIA explained