aria-labelledby attribute identifies the element (or elements) that labels the element it is applied to.
aria-labelledby property enables authors to reference other elements on the page to define an accessible name. This is useful when using elements that don't have native support for associating elements to provide an accessible name.
Some elements get their accessible name from their inner content. For example, the accessible name for a
<td> comes from the text between the opening and closing tags. Other elements, such as form
<table> get their accessible name from the content of associated elements; for these elements, the accessible name comes from the
<label> with a
All interactive elements must have an accessible name.
aria-labelledby can be used to reference another element to define its accessible name, when an element's accessible name needs to use content from elsewhere in the DOM.
If there is no content that can be referenced to create an accessible name, the
aria-label attribute should be used instead.
The purpose of
aria-labelledby is the same as that of
aria-label. It provides the user with a recognizable, accessible name for an interactive element. If an element has both attributes set,
aria-labelledby will be used.
aria-labelledby takes precedence over all other methods of providing an accessible name, including
<label>, and the element's inner text.
aria-describedby attributes both reference other elements to calculate text alternatives.
aria-labelledby should reference brief text that provides the element with an accessible name.
aria-describedby is used to reference longer content that provides a description. If there is no element in the DOM that provides a brief label appropriate for an accessible name for an interactive element, use
aria-label to define the accessible name for an interactive element.
Note: While in U.S. English the attribute would be assumed to be spelled "labeledby", the "labelledby" spelling has been established and is the spelling used in accessibility APIs.
The following example uses
aria-labelledby to provide an accessible name for a checkbox input by using the text content of a sibling element:
<span role="checkbox" aria-checked="false" tabindex="0" aria-labelledby="tac"></span> <span id="tac">I agree to the Terms and Conditions.</span>
Note that while using
aria-labelledby is similar in this situation to using an HTML
<label> element with the
for attribute, there are some very important differences. The
aria-labelledby attribute only defines the accessible name. It doesn't provide any of
Fortunately, the HTML
type="checkbox" works with native
<label>. When feasible, use the following:
<label for="tac"> <input id="tac" type="checkbox" name="terms-and-conditions"> I agree to the Terms and Conditions. </label> <p> <a href="tac.html">Read our Terms and Conditions</a>. </p>
aria-labelledbyproperty has the highest precedence when browsers calculate accessible names. Be aware that it overrides other methods of naming the element, including
aria-label, other naming attributes, and even the element's contents.
<button aria-label="Blue" aria-labelledby="color">Red</button> <span id="color">Yellow</span>
In this example, that accessible name is "Yellow".
aria-labelledbyproperty takes as value an id reference list, which means you can combine more than one element into a single accessible name. You can include the
idof the element itself to reference its own content.
<h2 id="attr" class="article-title">13 ARIA attributes you need to know</h2> <p>There are over 50 ARIA states and properties, but 13 of them stand out &helip; <a href="13.html" id="rm13" aria-labelledby="rm13 attr">read more</a> </p>
In this example, the accessible name is "read more 13 ARIA attributes you need to know".
aria-labelledbyproperty value order matters. When more than one element is referenced by
aria-labelledby, the content from each referenced element is combined in the order that they are referenced in the
aria-labelledbyvalue. Had we written
aria-labelledby="attr rm13">, the accessible name would have been "13 ARIA attributes you need to know read more".
aria-labelledbyproperty ignores repeated
ids in its value. If an element is referenced more than one time, only the first reference is processed.
aria-labelledby="attr attr rm13 rm13">is treated as
aria-labelledbyproperty value can include content from elements that aren't even visible. While you should provide assistive technology users with the same content and all other users, you can include content from elements with the HTML
display: none, and CSS
visibility: hiddenin the calculated name string.
aria-labelledbyproperty incorporates the value of input elements. If the value references an
<input>, the current value of the form control is included in the calculated name string, changing if the value is updated.
aria-labelledbyproperty cannot be chained. If an element with
aria-labelledbyreferences another element that also has
aria-labelledbyattribute on the referenced element is ignored.
Warning: Because calculating the name of an element with
aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is very important.
- ID reference list
Space separated list of one or more ID values referencing the elements that label the current element.
Used in almost all roles except roles that can not be provided an accessible name by the author.
|Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'ARIA: aria-labelledby Attribute' in that specification.