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.
From WCAG WG
Using ARIA Describedby
User Agent Notes
- Jaws V.11 and greater has complete support.
- ChromeVox V.1 and greater has complete support
- VoiceOver V.3 and greater supports ???
- NVDA 2 supports Aria Describedby ???
- 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. This is called a "programmatic association" in WCAG 2. When a screen reader encounters the image, the associated text is 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.
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
th elements, if present. The
th elements have limited use in that they can only be applied to forms or tables, respectively.
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>
Sample form field using
aria-describedby to associate instructions with form fields while there is a form label.
<form> <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> </form>
Sample close button using
aria-describedby to associate a visible instructions further below.
<button aria-label="Close window" aria-describedby="descriptionClose" onclick="myDialog.close()">X</button> <p>other content</p> <div id="descriptionClose">Closing this window will discard any information entered and return you back to the main page</div>
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.
Below is an example of using
aria-describedby to associate the application and the static text alternative:
<div role="application" aria-labelledby="calendar" aria-describedby="info"> <h1 id="calendar">Calendar<h1> <p id="info"> This calendar shows the game schedule for the Boston Red Sox. </p> <div role="grid"> .... </div>
- ARIA-XX: Using aria-labelledby to provide labels for objects.
- ARIA-XX: Using aria-label to provide labels for objects.
- G92: Providing long description for non-text content that serves the same purpose and presents the same information
- H45: Using longdesc
- Examine each element where a
aria-describedbyattribute is present.
- Examine whether the
aria-describedbyattribute programatically associates an element with its text description, via the
idattribute on the element where the text alternative is found.
- Examine whether the text description accurately describes or serves the equivalent purpose to the object.
Tests #1, #2 and #3 are true.