The HTML aria-labelledby attribute
Text already on the page names an element through aria-labelledby, which references the labeling elements by id. List several ids, as in aria-labelledby="del file", and their text joins in that order. The result overrides aria-label, a <label> and the element's own content.
Overview
The aria-labelledby attribute identifies the element or elements that label the current element. Its value is a space-separated list of ids. The double l is deliberate, because accessibility APIs had already settled on that spelling. Chrome also accepts aria-labeledby, but Firefox ignores it.
The list order is the order of the name. Each id's text is computed, then joined with a space, and an element may list its own id. A Delete button with aria-labelledby="del file" can be named Delete Budget.xlsx, which sets it apart from the other Delete buttons in a file list.
Checked first in the name computation, it beats aria-label, <label>, alt and the element's content. Browsers should ignore an id that matches nothing. When no listed element yields text, the AccName 1.2 Working Draft moves on to those sources, as Chrome and Firefox do.
Referenced text can be hidden from view. Point straight at an element with hidden, display: none, visibility: hidden or aria-hidden, and all the text inside it still counts. Point at a visible element with a hidden child, and that child is left out.
A referenced element's own aria-labelledby isn't followed. An id doesn't resolve across a shadow root boundary, but the ariaLabelledByElements property can point out of a shadow tree, and Chrome 135, Firefox 136 and Safari 16.4 have it.
Syntax
<section aria-labelledby="billing">
<h2 id="billing">Billing</h2>
<p>Your next invoice is due on June 1.</p>
</section>Values
| Value |
|---|
| A space-separated list of element id values. |
Example
<p>Rename the file and watch the joined text change.</p>
<label for="rename">File name</label>
<input id="rename" type="text" value="Budget.xlsx" maxlength="40">
<p style="overflow-wrap: anywhere"><span id="file">Budget.xlsx</span>
<button id="del" type="button" aria-labelledby="del file">Delete</button></p>
<p role="status" id="out" style="overflow-wrap: anywhere"></p>
<script>
const button = document.getElementById('del');
const out = document.getElementById('out');
function show() {
const parts = button.getAttribute('aria-labelledby').split(' ').map(function (id) {
return document.getElementById(id).textContent.trim();
}).filter(Boolean);
out.textContent = 'Text from the id list: ' + parts.join(' ');
}
document.getElementById('rename').addEventListener('input', function (event) {
document.getElementById('file').textContent = event.target.value;
show();
});
show();
</script>Best practices
- Point
aria-labelledbyat text people can see, and keeparia-labelfor interfaces with no visible label. Assistive technology users should get the same content as everyone else. - Name a <section> from its heading. A named section gets the region role, and a region with a visible label should reference it this way.
- Make every referenced id unique. With a repeated id, a browser should use the first element found, the same as
getElementById, so a duplicate can name the element from the wrong text. - Test the computed name with real assistive technology, since the calculation can be complex and can reference hidden content.
