This article needs an editorial review. How you can help.
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
Compatibility
TBD: Add support information for common UA and AT product combinations