ARIA: aria-labelledby attribute
The aria-labelledby
attribute identifies the element (or elements) that labels the element it is applied to.
Description
The 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 All interactive elements must have an accessible name. If there is no content that can be referenced to create an accessible name, the The purpose of The Note:
While in American English, "labeled" is spelled with one "l", the "labelledby" spelling has been established and is the spelling used in accessibility APIs. The following example uses Note that while using Fortunately, the HTML The In this example, that accessible name is "Yellow". The
There are over 50 ARIA states and properties, but 13 of them stand out…
read more
In this example, the accessible name is "read more 13 ARIA attributes you need to know". The The The The The Warning:
Because calculating the name of an element with Space separated list of one or more ID values referencing the elements that label the current element. The The ,
, or
comes from the text between the opening and closing tags. Other elements, such as form ,
, and
get their accessible name from the content of associated elements; for these elements, the accessible name comes from the
with a
for
attribute, , and
respectively.
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.aria-label
attribute should be used instead.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 aria-label
, , and the element's inner text.
aria-labelledby
and 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.aria-labelledby
to provide an accessible name for a checkbox input by using the text content of a sibling element:
I agree to the Terms and Conditions.
aria-labelledby
is similar in this situation to using an HTML 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 's other functionality, such as making clicking on the labeling element activate the input it is associated with. That has to be added back in with JavaScript.
with
type="checkbox"
works with native . When feasible, use the following:
Benefits (and drawbacks)
aria-labelledby
property 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.
Yellow
aria-labelledby
property takes as value a space-separated id reference list, which means you can combine more than one element into a single accessible name. You can include the id
of the element itself to reference its own content.13 ARIA attributes you need to know
aria-labelledby
property 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-labelledby
value. Had we written aria-labelledby="attr rm13">
, the accessible name would have been "13 ARIA attributes you need to know read more".aria-labelledby
property ignores repeated id
s 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-labelledby="attr rm13">
aria-labelledby
property value can include content from elements that aren't even visible. While you should provide assistive technology users with the same content as all other users, you can include content from elements with the HTML hidden
attribute, CSS display: none
, and CSS visibility: hidden
in the calculated name string.aria-labelledby
property incorporates the value of input elements. If the value references an , the current value of the form control is included in the calculated name string, changing if the value is updated.
aria-labelledby
property cannot be chained. If an element with aria-labelledby
references another element that also has aria-labelledby
, the aria-labelledby
attribute on the referenced element is ignored.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.Values
Associated interfaces
Element.ariaLabelledByElements
ariaLabelledByElements
property is part of each element's interface.
Its value is an array of subclasses of Element
that reflect the id
references in the aria-labelledby
attribute (with some caveats).ElementInternals.ariaLabelledByElements
ariaLabelledByElements
property is part of each custom element's interface.
Its value is an array of subclasses of Element
that reflect the id
references in the aria-labelledby
attribute (with some caveats).Associated roles
Specifications
Specification Accessible Rich Internet Applications (WAI-ARIA)
# aria-labelledbySee also
element
element
elementaria-label
aria-describedby