Using the aria-labelledby attribute - Accessibility 编辑

Description

The aria-labelledby attribute establishes relationships between objects and their label(s), and its value should be one or more element IDs, which refer to elements that have the text needed for labeling. List multiple element IDs in a space delimited fashion.

This idea is similar to how the "for" attribute is used to link a LABEL to an INPUT.

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 description 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="myBillingId">Billing</div>

<div>
    <div id="myNameId">Name</div>
    <input type="text" aria-labelledby="myBillingId myNameId"/>
</div>
<div>
    <div id="myAddressId">Address</div>
    <input type="text" aria-labelledby="myBillingId myAddressId"/>
</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">anathema</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>

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