Using the aria-labelledby attribute

Description

The aria-labelledby attribute is used to indicate the IDs of the elements that are the labels for the object. It is used to establish a relationship between widgets or groups and their labels. Users of assistive technologies such as screen readers typically navigate a page by tabbing between areas of the screen. If a label is not associated with an input element, widget or group, it will not be read by a screen reader.

aria-labelledby is very similar to aria-describedby: a label describes the essence of an object, while a description provides more information that the user might need.

The aria-labelledby attribute is not used only for form elements; it is also used to associate static text with widgets, groups of elements, panes, regions that have a heading, definitions, and more. The Examples section below provides more information about how to use the attribute in these cases.

aria-labelledby can be used in conjunction with the <label> element (using the for attribute) to improve compatibility with user agents that do not yet support ARIA.

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 both aria-labelledby and aria-label are used, user agents give precedence to aria-labelledby when computing the accessible name property.

Note: Opinons may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

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="name billing"/>
</div>
<div>
    <div id="address">Address</div>
    <input type="text" aria-labelledby="address billing"/>
</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:

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

Compatibility

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

Additional resources

Document Tags and Contributors

Last updated by: smarvin,