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-describedby for link purpose

Jump to: navigation, search


User Agent Notes [To be published separately]

  • Windows 7, Firefox 18.02, NVDA 2012.3, reads the link text and then the text content of the elements identified with the aria-describedby attribute
  • Windows 7, IE 9, NVDA 2012.3, reads the link text and then the text content of the elements identified with the aria-describedby attribute
  • Windows 7, Firefox 18.02, JAWS 13, user is alerted to additional information and JAWS+ALT+R is used to read the descriptive information
  • Windows 7, IE 9, JAWS 13, reads the link text and then the text content of the elements identified with the aria-describedby attribute
  • OS X 10.8.2, Safari 6.0.2, Voice Over, Automaticallyr reads descriptive text if you stay on a link long enough


As of this writing this technique applies to HTML technologies.

This technique relates to:

Success Criterion 1.3.1 (Info and Relationships)
Success Criterion 2.4.4 (Link Purpose (In Context))


The context of a link will help people understand the purpose of a link, especially if link text content is the same or similar to other link text on the page. For assistive technologies to be able to provide similar contextual information the relationship between the link and the other content is established through markup. One way to provide this relationship is to place an aria-describedby attribute on the link and provide an ID or list of space separated IDs to the other elements with text content on the page that provide contextual information.

Assistive technologies will present the link text of the link to the user and typically alert the user that there is additional information about this link available. Some assistive technologies will automatically present the additional information, and some will provide the user a way to request the additional information.

The following examples are derived versions of current WCAG techniques that use the aria-describedby attribute to provide programmatic contextual information to the links.

Example 1: Link context with a LI element

The following example is derived from H77: Identifying the purpose of a link using link text combined with its enclosing list item technique

  <li id="li1"> 
    Check out the video report for last year's 
    <a href="festival.htm" aria-describedby="li1">National Folk Festival</a>. 
  <li id="li2"> 
    <a href="listen.htm">Listen to the instruments</a> 
  <li id="li3"> 
    Guitar Man: George Golden talks about 
    <a href="mkguitars.htm" aria-describedby="li3">making guitars</a>. 

Example 2: Link context from other content in the li element

The following example is derived from H77: Identifying the purpose of a link using link text combined with its enclosing list item technique

    <a href="tomb_raider.htm" id="a1">Tomb Raider: Legend</a> 
    <a href="tomb_raider_images.htm" aria-describedby="a1">See Images</a> 
    <a href="tomb_raider.mpeg" aria-describedby="a1">(Download Demo)</a> 
    <a href="fear_extraction.htm" id="a2">F.E.A.R. Extraction Point</a> 
    <a href="fear_extraction_images.htm" aria-describedby="a2">See Images</a> 
    <a href="fear_extraction.mpeg" aria-describedby="a2">(Download Demo)</a>
    <a href="call_of_duty.htm" id="a3">Call of Duty 2</a> 
    <a href="call_of_duty_images.htm" aria-describedby="a3">See Images</a> 
    <a href="call_of_duty.mpeg" aria-describedby="a3">(Download Demo)</a>
    <a href="Warhammer_40K.htm" id="a4">Warhammer 40K</a>  
    <a href="warhammer_40k_images.htm"  aria-describedby="a4">See Images</a>  
    <a href="Warhammer_40k.mpeg"  aria-describedby="a4">(Download Demo)</a> 

Example 3: Link context from th elements of a table

The following example is derived from H79: Identifying the purpose of a link using link text combined with its enclosing table cell and associated table headings

<table class="links" border="1" style="border-collapse:collapse;"> 
<caption>Comparison of Rental Car Rates</caption> 
  <th id="c1">Alamo</th> 
  <th id="c2">Budget</th> 
  <th id="c3">National</th> 
  <th id="c4">Avis</th> 
  <th id="c5">Hertz</th> 
  <th id="r1">Economy cars</th> 
  <td><a href="econ_ala.htm" aria-describedby="c1 r1">$67/day</a></td> 
  <td><a href="econ_bud.htm" aria-describedby="c2 r1">$68/day</a></td> 
  <td><a href="econ_nat.htm" aria-describedby="c3 r1">$72/day</a></td> 
  <td><a href="econ_av.htm" aria-describedby="c4 r1">$74/day</a></td> 
  <td><a href="econ_hz.htm" aria-describedby="c5 r1">$74/day</a></td> 
  <th id="r2">Compact cars</th> 
  <td><a href="comp_ala.htm" aria-describedby="c1 r2">$68/day</a></td> 
  <td><a href="comp_bud.htm" aria-describedby="c2 r2">$69/day</a></td> 
  <td><a href="comp_nat.htm" aria-describedby="c3 r2">$74/day</a></td> 
  <td><a href="comp_av.htm" aria-describedby="c4 r2">$76/day</a></td> 
  <td><a href="comp_hz.htm" aria-describedby="c5 r2">$76/day</a></td> 
  <th id="r3">Mid-sized cars</th> 
  <td><a href="mid_ala.htm" aria-describedby="c1 r3">$79/day</a></td> 
  <td><a href="mid_bud.htm" aria-describedby="c2 r3">$80/day</a></td> 
  <td><a href="mid_nat.htm" aria-describedby="c3 r3">$83/day</a></td> 
  <td><a href="mid_av.htm" aria-describedby="c4 r3">$85/day</a></td> 
  <td><a href="mid_hz.htm" aria-describedby="c5 r3">$85/day</a></td> 
  <th id="r4">Full-sized cars</th> 
  <td><a href="full_ala.htm" aria-describedby="c1 r4">$82/day</a></td> 
  <td><a href="full_bud.htm" aria-describedby="c2 r4">$83/day</a></td> 
  <td><a href="full_nat.htm" aria-describedby="c3 r4">$89/day</a></td> 
  <td><a href="full_av.htm" aria-describedby="c4 r4">$91/day</a></td> 
  <td><a href="full_hz.htm" aria-describedby="c5 r4">$91/day</a></td> 

Example 4: Link context from preceding h1-h6 heading elements

The following example is derived from H80: Identifying the purpose of a link using link text combined with the preceding heading element

<h2 id="head1"><a href="royal_palm_hotel.html">Royal Palm Hotel</a></h2> 
  <ul class="horizontal"> 
    <li><a href="royal_palm_hotel_map.html" aria-describedby="head1">Map</a></li> 
    <li><a href="royal_palm_hotel_photos.html" aria-describedby="head1">Photos</a></li> 
    <li><a href="hroyal_palm_hotel_directions.html" aria-describedby="head1">Directions</a></li> 
    <li><a href="royal_palm_hotel_reviews.html" aria-describedby="head1">Guest reviews</a></li> 
    <li><a href="royal_palm_hotel_book.html" aria-describedby="head1">Book now</a></li> 

<h2 id="head2"><a href="hotel_three_rivers.html">Hotel Three Rivers</a></h2> 
  <ul class="horizontal"> 
    <li><a href="hotel_three_rivers_map.html" aria-describedby="head2">Map</a></li> 
    <li><a href="hotel_three_rivers_photos.html" aria-describedby="head2">Photos</a></li> 
    <li><a href="hotel_three_rivers_directions.html"  aria-describedby="head2">Directions</a></li> 
    <li><a href="hotel_three_rivers_reviews.html"  aria-describedby="head2">Guest reviews</a></li> 
    <li><a href="hotel_three_rivers_book.html"  aria-describedby="head2">Book now</a></li> 

Example 5: Link context from nested list content

The following example is derived from H81: Identifying the purpose of a link in a nested list using link text combined with the parent list item under which the list is nested

<li><span id="li4">Annual Report 2005-2006 </span>
  <li><a href="annrep0506.html" aria-describedby="li4">(HTML)</a></li> 
  <li><a href="annrep0506.pdf"  aria-describedby="li4">(PDF)</a></li> 
  <li><a href="annrep0506.rtf"   aria-describedby="li4">(RTF)</a></li> 
<li><span id="li5">Annual Report 2006-2007</span>
  <li><a href="annrep0607.html" aria-describedby="li5">(HTML)</a></li> 
  <li><a href="annrep0607.pdf" aria-describedby="li5">(PDF)</a></li> 
  <li><a href="annrep0607.rtf" aria-describedby="li5">(RTF)</a></li> 



For link elements that use aria-describedby

  1. Check that the id or ids referenced by aria-describedby exist in the page
  2. Check that the value of the element referenced by the aria-described attribute properly describes the context of the link element.

Expected Results

  • #1 and #2 are true