Using aria-describedby for link purpose - May 2014
This technique applies to:
User agent and assistive technology support notes [To be published separately]
Please see user agent ARIA support: 
- In IE JAWS reads the aria-describedby text twice.
- VoiceOver can be sluggish in reading the
aria-describedby attribute, authors can use a visible text element on the page as a label for a link. For example, a "read more..." link could be associated with the text of the heading of the preceding section to make the purpose of the link unambiguous (see example 1). When applied on links,
aria-describedby can be used to identify the purpose of a link that may be readily apparent for sighted users, but less obvious for screen reader users.
When associating target text with a focusable element with the help of
aria-describedby, the target text element is given an ID which is referenced in the value of the
aria-describedby attribute of the focusable element.
It is also possible to reference several text elements on the page to provide a more detailed description for a focusable element. Each of the text elements used must be given a unique ID which is referenced as a string of IDs (IDREF) in the value of the
aria-describedby attribute. The description text should then be concatenated following the order of IDs in the value of the
aria-describedby attribute. All of the referenced elements should be visually close to the link, either under the same heading, or in the same or adjacent paragraph,
div. This will ensure they can be easily seen be people with low vision who zoom in on the page, and for people with cognitive disabilities so they can easily find and understand the link context.
From the perspective of a web author,
aria-describedby references target text exactly like
aria-labelledby. However, the
aria-describedby attribute allows the link text AND the supplementary text to be read by assistive technology. On the other hand, the
aria-describedby text will not show up in a screen reader list of links, whereas some screen readers provide the
aria-labelledby referenced text as the link value.
This example should extend the "read more" link text with the content of the
h2 heading referenced by
<h2 id="headline">Elections set for October 1</h2> <p>After a series of non-confidence votes by the opposition, provincial residents will head to the polls later this month. <a href="news.html" aria-describedby="headline">Read more...</a></p>
Working example: https://awkawk.github.io/aria-describedby_link.html
This example extends the "learn more" link text with the content of the paragraph
p referenced by
<p id="p456">Sign up for our accessibility services</p> <p><a href="news.html" aria-describedby="p456">Learn more...</a></p>
Working example: http://davidmacd.com/WCAG/examples/aria-describedby_on_a_link.html
This example adds programmatic context to the "learn more" link by referencing the previous
span within the same paragraph.
<p><span id="p789">Purchase our products online</span><a href="news.html" aria-describedby="p789">Learn more...</a></p>
Working example: http://davidmacd.com/WCAG/examples/aria-describedby_on_a_link1.html
- Accessible Rich Internet Applications (WAI-ARIA) 1.0, Accessible Name and Description Calculation
- HTML5 Accessible Name Calculation
- ARIA1: Using the aria-describedby property to provide a descriptive label for user interface controls
- ARIA7: Using aria-labelledby for link purpose
- ARIA8: Using aria-label for link purpose
- ARIA9: Using aria-labelledby to concatenate a label from several text nodes
- G91: Providing link text that describes the purpose of a link
- H30: Providing link text that describes the purpose of a link for anchor elements
For each link that has an
- Check that each ID in the value of the
aria-describedbyattribute matches an ID for a text element which is visible and nearby the link text.
- Check that the link text and the referenced elements are within the same or adjacent paragraph,
spanelement, or under the same heading.
- Check that the value of the
aria-describedbycombined with the link text provides the purpose of the link.
Test #1 and #2 are true for each link with aria-describedby.