WAI-ARIA: aria-labelledby (Property)

Description

Identifies the element (or elements) that labels the current element. See related aria-describedby.

The purpose of aria-labelledby is the same as that of aria-label. It provides the user with a recognizable name of the object. The most common accessibility API mapping for a label is the accessible name property.

If the interface is such that it is not possible to have a visible label on the screen, authors SHOULD use aria-label and SHOULD NOT use aria-labelledby. As required by the text alternative computation, user agents give precedence to aria-labelledby over aria-label when computing the accessible name property.

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

Note: The expected spelling of this property in U.S. English is “labeledby.” However, the accessibility API features to which this property is mapped have established the “labelledby” spelling. This property is spelled that way to match the convention and minimize the difficulty for developers.

Screen Reader Support

aria-labelledby Example

HTML Example 1

<figure aria-labelledby="operahouse_1" role="group">
  <img src="/operahousesteps.jpg" alt="The Sydney Opera House">
  <figcaption id="operahouse_1">
    We saw the opera <cite>Barber of Seville</cite> here!
  </figcaption>
</figure>

HTML Example 2

<div role="navigation" aria-labelledby="nav-heading">
  <h2 id="nav-heading">Learn About This Product</h2>
  <ul>
    <li>Product Description</li>
    <li>Technical Specifications</li>
    <li>Customer Reviews</li>
  </ul>
</div>

HTML Example 3

<div class="text">
  <label id="tp1-label" for="first">First Name:</label> <input type="text" id="first" name="first" size="20" aria-labelledby="tp1-label" aria-describedby="tp1" aria-required="false">
  <div id="tp1" class="tooltip" role="tooltip" aria-hidden="true">
    Your first name is optional
  </div>
</div>

Associating Headings With Regions Example

In the example below, header elements are associated with the content they head. Note that the region being referenced is the region that contains the header.

<div role="main" aria-labelledby=”foo”>
<h1 id="foo">Wild fires spread across the San Diego Hills</h1>
Strong winds expand fires ignited by high temperatures ...
</div>

Characteristics

Related Concepts

• HTML label

Used in Roles

• All elements of the base markup

Value

• ID reference list
  • A list of one or more ID references.

Semantic HTML

No HTML element equivalent.

Reference

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-labelledby.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for aria-labelledby.
• HTML5 Accessibility Chops: notes on using ARIA by TPGi