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.
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
a space-separated list of element IDs
Possible effects on user agents and assistive technology
aria-label are used, user agents give precedence to
aria-labelledby when computing the accessible name property.
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
<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">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
<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