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 to provide descriptions of images

Revision as of 20:04, 28 July 2013 by Dmacdona (Talk | contribs)

Jump to: navigation, search


Using ARIA Describedby to provide descriptions of objects

User Agent Notes [To be published separately]

Updated by David MacDonald July 16, 2013

  • Jaws V.11 and greater has complete support. IE10 JAWS 14. Speaks alt and then "press JAWS key + alt +r to hear descriptive text"
  • ChromeVox V.1 and greater has complete support?
  • VoiceOver V.3 and greater supports but replaces ALT text if both are present
  • NVDA 2 reads ALT text if both are present but not Describedby unless it is alone
  • Window Eyes as of V.7 ???.


As of this writing this technique applies to HTML technologies.

This technique relates to:


The purpose of this technique is to provide descriptions of objects that can be read by assistive technology. When screen reader users encounter images, there is no way for them to know the contents of the image or its purpose without there being a text alternative. The aria-describedby attribute provides a way to associate text that is on the page, with an object, such as an image. When a screen reader encounters the image, the associated text can be read so that the user will know its contents and purpose.

A feature of WAI-ARIA is the ability to associate descriptive text with a section, drawing, form element, picture, and so on using the aria-describedby property. This is unlike longdesc which typically required the author to create a separate file to describe a picture when it was preferred to have the descriptive text in prose as well so that it was readily available to all users. Yet, like longdesc, descriptive text is treated separately from the short name you would typically provide using the title or alt attributes in HTML. This is the preferred vehicle for providing long descriptions for elements in your document because the alternative is available to all, including sighted people who do not have assistive technology.

Like aria-labelledby, aria-describedby 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. If an object or widget lacks aria-describedby the user agent or AT may try to extract information from the label or th elements, if present. The label and th elements have limited use in that they can only be applied to forms or tables, respectively.


Example 1

The following example shows how aria-describedby can be applied to an image to provide a long description, where that text description is on the same page as the image.

<img src="ladymacbeth.jpg" alt="Lady MacBeth" aria-describedby="123">
<p id="123">This painting dates back to 1730 and is oil on canvas. It was created by 
Jean-Guy Millome, and represents ...</p>

Example 2

Sample form field using aria-describedby to associate instructions with form fields while there is a form label.

<label for="123">First name</label>  
<input name="" type="text" id="123" aria-describedby="234"> </form>
<p id="234">A  bit of instructions for this field linked with aria-describedby. </p>

See example

Example 3

Sample close button using aria-describedby to associate a visible instructions further below.

<button aria-label="Close window" aria-describedby="descriptionClose"
<p>other content</p>
<div id="descriptionClose">Closing this window will discard any information entered
and return you back to the main page</div>

Example 4

The following code snippet from the iCITA site shows how to use aria-describedby and the onfocus="tooltipShow() function to display the tooltip when focus is placed on an element.

<html lang="en-us"">  
   <title>inline: Tooltip Example 1</title>      
   <link rel="stylesheet" href="css/tooltip1_inline.css"  type="text/css">    
   <script type="text/javascript" src="js/tooltip1_inline.js"></script>    
   <script type="text/javascript" src="../js/widgets_inline.js"></script>
   <script type="text/javascript" src="../js/globals.js"></script>          
   <link rel="icon" href="" type="image/x-icon">    
   <link rel="shortcut icon" href="" type="image/x-icon"> 

   <body onload="initApp()">

   <div id="container">

   <h1>Tooltip Example 1</h1>
     <h2>Create Account</h2>
   <div class="text">
   <label for="first">First Name:</label> 

   <input type="text"  id="first" name="first" size="20" 
          onmouseover="tooltipShow(event, this, 'tp1');"     
          onfocus="tooltipShow(event, this,  'tp1');" 

   <div id="tp1" role="tooltip" aria-hidden="true">Your first name is optional. </div>    


WAI ARIA 1.0 Authoring Practices

Related Techniques



  1. Examine each element where a aria-describedby attribute is present.
  2. Examine whether the aria-describedby attribute programatically associates an element with its text description, via the id attribute on the element where the text alternative is found.
  3. Examine whether the text description accurately describes or serves the equivalent purpose to the object.

Expected Results

Tests #1, #2 and #3 are true.