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
This attribute can be used with any typical HTML form element; it is not limited to elements that have an ARIA
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
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
<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
<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
<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
<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>
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
TBD: Add support information for common UA and AT product combinations