The difference between aria-label and aria-labelledby
The aria-label and aria-labelledby attributes do the same thing but in different ways. Sometimes the two attributes are confused and this has unintended results. This post describes the differences between
aria-labelledby and how to choose the right one.
aria-labelledby attributes are both used to give an element it's accessible name. An element's accessible name is a piece of text that differentiates one instance of that element in a document from the rest; the text of a link or text description for an image for example.
The difference between
aria-labelledby is where they get that piece of text, and the clue is in the name. If you think of the accessible name for an element as its label it becomes more understandable. The
aria-label attribute gives an element its label; an element with the
aria-labelledby attribute is labelled by something else.
The aria-label attribute
aria-label attribute takes a piece of text as its value. This text becomes the element's label or accessible name. For example, the accessible name of the button in the following example is "Search":
- Code language
<button id="search" aria-label="Search"></button>
The aria-labelledby attribute
aria-labelledby attribute points to another element in the document. It takes the value of the id attribute on that other element as its value, creating a relationship between the two elements. The text contained in the other element becomes the label or accessible name for the element with
aria-labelledby applied to it. For example, the accessible name for the button in the following example is also "Search":
- Code language
<label for="search">Enter search term
<input type="search" id="search">
Choosing between aria-label and aria-labelledby
When it comes to deciding which attribute to use, consider these things:
- Do you need to use ARIA?
- If yes, does the text already exist elsewhere in the document?
- If yes, use
aria-labelledby; if no, use
The first question references the First Rule of ARIA:
If you can use a native HTML element or attribute with the semantics and behaviour you require already built-in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so.
There are ways an element can be given an accessible name without using
aria-labelledby. For example, put text inside a link or button, use the
alt attribute to give an image a text description, or match the
for attribute on a
label element with the
id attribute of the form field it relates to.
If you think ARIA is the right solution, then the second question is whether the piece of text already exists in the document. Generally speaking it's better to reuse than duplicate, so using
aria-labelledby to associate the piece of text with the element makes sense if the text already exists. If it does not exist elsewhere, then use
aria-labelledby attributes do not work consistently with all HTML elements.
aria-labelledby attributes will override any other accessible name assigned to the element. ARIA always takes precedence over native HTML semantics. The accessible name in the following example is "This", despite the content of the button:
- Code language