This Wiki page is edited by participants of the WCAG Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.
Using aria-labelledby to provide a name for user interface controls
- Surveyed by TF 25 June 2012
- Discussed by TF 25 June 2012
- 1 Nov 2012: Ready for Review
- Surveyed by WG 10 Jan 2013, returned to TF
- Split naming of controls from naming of regions/landmarks from naming of image-like non-text content
- Surveyed by TF 03 Oct 2013
- Added to XML by AWK 2014/1/2
User Agent Notes [To be published separately]
- Jaws V.11 and greater has complete support.
- ChromeVox V.1 and greater has complete support
- VoiceOver V.3 and greater supports ???
- NVDA 2 supports Aria Describedby ???
- Window Eyes as of V.7 ???.
This technique applies to HTML technologies using WAI-ARIA.
This technique relates to:
The purpose of this technique is to provide names for user interface controls that can be read by assistive technology. WAI-ARIA provides a way to associate text with a section, drawing, form element, picture, and so on, using the
aria-labelledby property. This techniques uses the
aria-labelledby attribute to associate a user interface control, such as a form field, with text on the page that labels it.
aria-labelledby can accept multiple ids to point to other elements of the page using a space separated list. This capability makes
aria-labelledby especially useful in situations where sighted users use information from the surrounding context to identify a control. Using aria-labelledby to concatenate a label from several text nodes contains more examples of situations where names are created from several other text elements on the page.
While the function of aria-labelledby appears similar to the native HTML label element, there are some differences:
aria-labelledbycan reference more than one text element;
labelcan only reference one.
aria-labelledbycan be used for a variety of elements while the
labelelement can only be used on form elements.
- Clicking on a
labelfocuses the associated form field. This does not occur with
aria-labelledby. If this behaviour is required then use
labelor implement this functionality using scripting.
Note that as of December 2013,
label has better support than
aria-labelledby, especially in older browsers and assistive technologies.
The following is an example of
aria-labelledby used on a simple text field to provide a label in a situation where there is no text available for a dedicated label but there is other text on the page that can be used to accurately label the control.
<input name="searchtxt" type="text" aria-labelledby="searchbtn"> <input name="searchbtn" id="searchbtn" type="submit" value="Search">
Below is an example of
aria-labelledby used to provide a label for a slider control. In this case the label text is selected from within a longer adjacent text string. Please note that this example is simplified to show only the labeling relationship; authors implementing custom controls also need to ensure that controls meet other success criteria.
<p>Please select the <span id="mysldr-lbl">number of days for your trip</span></p> <div id="mysldr" role="slider" aria-labelledby="mysldr-lbl"></div>
The following example of
aria-labelledby with multiple references uses the
label element. For additional detail on concatenating multiple sources of information into a label with aria-labelledby, please view the technique Using ARIA labelledby to concatenate a label from several text nodes.
<label id="l1" for="f3">Notify me</label> <select name="amt" id="f3" aria-labelledby="l1 f3 l2"> <option value="1">1</option> <option value="2">2</option> </select> <span id="l2" tabindex="-1">days in advance</span>
Note: The use of the
label element is included for a number of reasons. If the user clicks on the text of the
label element, the corresponding form field will receive focus, which makes the clicking target larger for people with dexterity problems. Also the
label element will always be exposed via the accessibility API. A
span could have been used (but if so, it should receive a
tabindex="-1" so that it will be exposed via the accessibility API in all versions of Internet Explorer). However, a
span would lose the advantage of the larger clickable region.
- WAI ARIA 1.0 Authoring Practices
- HTML to Platform Accessibility APIs Implementation Guide: Accessible Name and Description Calculation
- Using aria-labelledby to provide a text alternative for non-text content
- Using aria-label to provide labels for objects
- Using aria-labelledby to concatenate a label from several text nodes
- Using aria-labelledby for link purpose
- Using aria-labelledby to name regions and landmarks
- G92: Providing long description for non-text content that serves the same purpose and presents the same information
- H45: Using longdesc
For each user interface control element where an
aria-labelledby attribute is present:
- Check that the value of the
aria-labelledbyattribute is the
idof an element or a space separated list of
ids on the web page.
- Check that the text of the referenced element or elements accurately labels the user interface control.
Checks #1 and #2 are true.