Using the aria-labelledby attribute

Description

The aria-labelledby attribute contains the element IDs of labels in objects such as input elements, widgets, and groups. The attribute establishes relationships between objects and their labels. Assistive technology, such as screen readers, use this attribute to catalog the objects in a document so that users can navigate between them. Without an element ID, the assistive technology cannot catalog the object.

aria-labelledby is very similar to aria-describedby: A label provides essential information about an object, while a descriptions provides extended information that the user might need.

In addition to form elements, you can use the aria-labelledby attribute to associate static text with widgets, groups of elements, panes, regions that have a heading, definitions, and other types of objects. The Examples section below provides more information on how to use the attribute this way.

To improve compatibility with user agents that do not support ARIA, you can use aria-labelledby with the <label> element (using the for attribute).

This attribute can be used with any typical HTML form element; it is not limited to elements that have an ARIA role assigned.

Value

A space-separated list of element IDs

Possible effects on user agents and assistive technology 

When user agents compute the accessible name property of elements that have both an aria-labelledby attribute and an aria-label attribute, the user agents give precedence to aria-labelledby.

Examples

Example 1: Multiple Labels

In the example below, each input field is labelled by both its own individual label and by the label for the group:

<div id="billing">Billing Address</div>

<div>
    <div id="name">Name</div>
    <input type="text" aria-labelledby="billing name"/>
</div>
<div>
    <div id="address">Address</div>
    <input type="text" aria-labelledby="billing address"/>
</div>

Example 2: Associating Headings With Regions

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>

Example 3: Radio Groups

In the example below, the container of a radiogroup is associated with its label using the aria-labelledby attribute:

<div id="radio_label">My radio label</div>
<ul role="radiogroup" aria-labelledby="radio_label">
    <li role="radio">Item #1</li>
    <li role="radio">Item #2</li>
    <li role="radio">Item #3</li>
</ul>

Example 4: Dialog Label

In the example below, the header element that labels the dialog is referred to by the aria-labelledby attribute:

<div role="dialog" aria-labelledby="dialogheader">
    <h2 id="dialogheader">Choose a File</h2>
    ... Dialog contents
</div>

Example 5: Inline Definition

In the example below, the definition of a term that is described in the natural flow of the narrative is associated with the term itself using the aria-labelledby attribute:

<p>The doctor explained it had been a <dfn id="placebo">placebo</dfn>, or <span role="definition" aria-labelledby="placebo">  
an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
</p>

Example 6: Definition Lists

In the example below, the definitions in a formal definition list are associated with the terms they define using the aria-labelledby attribute:

<dl>
    <dt id="anathema">anthema</dt>
    <dd role="definition" aria-labelledby="anathema">a ban or curse solemnly pronounced by ecclesiastical authority
                                                     and accompanied by excommunication</dd>
    <dd role="definition" aria-labelledby="anathema">a vigorous denunciation : cursor</dd>

    <dt id="homily">homily</dt>
    <dd role="definition" aria-labelledby="homily">a usually short sermon</dd>
    <dd role="definition" aria-labelledby="homily">a lecture or discourse on or of a moral theme</dd>

</dl>

Example 7: Menus

In the example below, a popup menu is associated with its label using the aria-labelledby attribute:

<div role="menubar">
    <div role="menuitem" aria-haspopup="true" id="fileMenu">File</div>
    <div role="menu" aria-labelledby="fileMenu">
        <div role="menuitem">Open</div>
        <div role="menuitem">Save</div>
        <div role="menuitem">Save as ...</div>
        ...
    </div>
    ...
</div>

Working Examples:

• Button example uses aria-labelledby
• Combobox example uses aria-labelledby

Notes 

The most common accessibility API mapping for a label is the accessible name property

Used by ARIA roles

All elements of the base markup

Related ARIA techniques 

• Using the aria-label attribute
• Using the aria-describedby attribute

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources

• WAI-ARIA specification for aria-labelledby