What are they?
aria-label and aria-labelledby are ARIA attributes that allow authors to provide an accessible name to elements.
aria-labelsupplies the name as a text string directly in the attribute.aria-labelledbyreferences another element whose content is used as the accessible name.
Which elements can they be applied to?
aria-labelandaria-labelledbyare intended for elements whose roles support author-provided accessible names.- Those roles can be either implicit (native to the HTML element) or explicit (assigned via ARIA).
This is a lot to unpack, so let's break it down into smaller parts.
What are roles?
Roles communicate the purpose and expected behaviour of elements to assistive technologies such as screen readers.
For example, a role can identify an element as a:
- button
- heading
- navigation
- checkbox
- dialog
What are implicit and explicit roles?
Implicit roles are roles that HTML elements already have by default.
For example:
<button>has an implicit role ofbutton<nav>has an implicit role ofnavigation<main>has an implicit role ofmain
These roles are automatically exposed by browsers without needing extra markup.
Explicit roles are roles added manually by authors using the role attribute.
In the example below, the <div> element is explicitly assigned the role of button.
<div role="button">Save</div>This example is used only to demonstrate an explicit role. Where possible, use native <button> elements.
What are accessible names?
Accessible names identify elements for assistive technologies such as screen readers. For example:
- A button might have the accessible name “Save”
- A search field might have the accessible name “Search”
- A dialog might have the accessible name “Settings”
Accessible names can come from different sources, including:
- visible text
<label>elementsaltattributesaria-labelaria-labelledby
Where possible, visible text labels are preferred over ARIA-only labels.
What are author-provided accessible names?
Author-provided accessible names are names supplied directly by the author using aria-label or aria-labelledby, rather than being produced from element content or other native HTML methods.
For example, a button role can have the name “Save” from the button’s content.
<button>Save</button>But it could also be given an author-provided accessible name, in this case to provide additional context.
<button aria-label="Dismiss alert">Dismiss</button>Which roles can have author-provided names?
Many interactive, structural, and landmark roles support author-provided accessible names. Examples include:
buttonlinkcheckboxradiotextboxheadingimgdialog
Some roles are intended only for presentation or generic structure, so they do not allow author-provided accessible names. In ARIA 1.2, roles that cannot be named are:
captioncodedeletionemphasisgenericinsertionparagraphpresentationstrongsubscriptsuperscript
In fact, most roles in this list are also the implicit roles of common HTML elements. This means applying aria-label or aria-labelledby to those elements is equally unsupported.
In this example, the <div> is explicitly assigned the role of presentation.
<div role="presentation"></div>In this example, <p> has an implicit role of paragraph.
<p>Hello world</p>In both cases, these roles do not support author-provided accessible names, even though some browsers may still expose names in practice.
Summary
aria-labelandaria-labelledbyare used to apply author-provided accessible names to elements.- They are intended for elements whose roles support author-provided accessible names.
- Those roles can be either implicit (native to the HTML element) or explicit (assigned via ARIA).
Further reading
The rules above describe the ARIA specification requirements. In practice, browsers are often more tolerant than the spec requires. They sometimes expose accessible names even when they shouldn’t.
For a detailed look at how browsers actually behave, see aria-label and static elements, including test results across browsers and platforms.