Using aria-describedby for link purpose - May 2014

From WCAG WG


Status

Applicability

WAI-ARIA, HTML5

This technique applies to:

User agent and assistive technology support notes [To be published separately]

Please see user agent ARIA support: [1]

  • In IE JAWS reads the aria-describedby text twice.
  • VoiceOver can be sluggish in reading the aria-describedby

Description

With 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, span or 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.

Examples

Example 1

This example should extend the "read more" link text with the content of the h2 heading referenced by aria-describedby.

<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

Example 2

This example extends the "learn more" link text with the content of the paragraph p referenced by aria-describedby.

<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

Example 3

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

Resources

Related Techniques

  • 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

Tests

For each link that has an aria-describedby attribute:

  1. Check that each ID in the value of the aria-describedby attribute matches an ID for a text element which is visible and nearby the link text.
  2. Check that the link text and the referenced elements are within the same or adjacent paragraph, div or span element, or under the same heading.
  3. Check that the value of the aria-describedby combined with the link text provides the purpose of the link.

Expected results

Test #1 and #2 are true for each link with aria-describedby.