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 name regions and landmarks
- Surveyed by TF 03 Oct 2013
- Added to XML by AWK 2014/1/2
User Agent Notes [To be published separately]
This technique applies to HTML5 technologies.
This technique relates to:
The purpose of this technique is to provide names for regions of a page that can be read by assistive technology. The
aria-labelledby attribute provides a way to associate an section of the page marked up as a region or landmarks with text that is on the page that labels it.
Landmark roles (or "landmarks") programmatically identify sections of a page. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page.
aria-labelledby can accept multiple ids to point to other regions of the page using a space separated list. It is also limited to ids for defining these sets.
Below is an example of
aria-labelledby used on a complementary Landmark. The region of the document to which the heading pertains could be marked with the
aria-labelledby property containing the value of the
id for the header.
<p role="complementary" aria-labelledby="hdr1"> <h1 id="hdr1"> Top News Stories </h1> </p>
The following code snippet for application landmarks with static prose. If you have a regional landmark of type application and static descriptive text is available, then on the application landmark, include an aria-describedby reference to associate the application and the static text as shown here:
<div role="application" aria-labelledby="p123" aria-describedby="info"> <h1 id="p123">Calendar<h1> <p id="info"> This calendar shows the game schedule for the Boston Red Sox. </p> <div role="grid"> .... </div>
- 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 to provide a name for user interface controls
- Using aria-labelledby for link purpose
- G92: Providing long description for non-text content that serves the same purpose and presents the same information
- H45: Using longdesc
- Examine each element with attribute
role=regionor with a landmark role, where an
aria-labelledbyattribute is also present.
- Check that the value of the
aria-labelledbyattribute is the
idof an element on the page.
- Check that the text of the element with that
idaccurately labels the section of the page.
Checks #2 and #3 are true.