Standards for Adding Long Descriptions to Your Content

Status of the longdesc attribute

On February 26, 2015, the W3C announced the approval of the  HTML5 Image Description Extension  as a final recommendation. This recommendation reinstates the longdesc attribute in HTML5 more than four years after it was removed due to disagreement about its effectiveness and usefulness. Its (re)approval by the W3C means that authors can once again use it to provide long image descriptions in a standards-compliant manner. The presence of longdesc-delivered descriptions is announced by JAWS, NVDA, Window-Eyes and ChromeVox screen readers. VoiceOver, however, does not currently recognize the longdesc attribute. Longdesc is supported by Firefox, IE and Chrome browsers.  Other assistive technologies may provide support for longdesc as well.

How it works

The longdesc attribute uses a URL to point to an off-page image description. Here is a code example:

<img src=”finches.jpg” alt=”A diagram comparing beaks and food of various finches.” longdesc=”finches_longdesc.html” />

You can also see a working example of the longdesc attribute in use.

Assistive technology that recognizes the longdesc attribute will notify the user that the description is available. For example, a screen reader will read the image’s alt text and then announce “Has long description” or “Press ‘enter’ to hear long description.” The user can then choose to hear the description or not.  Most browsers do not currently make it visually obvious that @longdesc is available on images, so its discovery is currently limited to assistive technology. However, current versions of Firefox on both Mac and Windows will display long descriptions when users right-click on an image and choose “View Description” from the context menu.

Another way to link images: aria-describedby

There are other ways to link images to long descriptions; among them is the aria-describedby property, which will associate an image with descriptive text that is on the same page.  It is possible to deliver hidden descriptions to the user using aria-describedby, too, by associating the image with text that is positioned off-screen in a <div> or an <iframe>. See James Craig’s examples of hidden descriptions delivered using aria-describedby to learn more about this technique. Other methods include the use of aria-describedat (still under development); the <details> element or hidden iframeDiagrammar; or integrating descriptive text into the body of the document itself.

How to decide which method to use

Aria-describedby and @longdesc are legitimate methods to convey long image descriptions, so how to decide which is the best one to use? The good news is that you can use either or both. In addition, the DIAGRAM Standards Working Group recommends that EPUB authors use aria-describedby to provide image descriptions until aria-describedat becomes available in ARIA 1.1 sometime in 2015. Aria-describedat is similar to @longdesc in that it uses URLs to point to off-page image descriptions.  Unlike @longdesc, however, this new property will be able to be applied to any element, not just images. (@longdesc can only be applied to images.)


If you are producing HTML5 or EPUB3 documents, here are DIAGRAM’s recommendations to help you decide what to do:

  • In HTML documents, use @longdesc to provide a long description. Take a look at a demonstration of the longdesc attribute to see how it works.  Alternatively, use aria-describedby to associate an image with a description that is located on the same page or is hidden off-screen.
  • In EPUB documents, use aria-describedby to associate images with long descriptions. See example code in the EPUB 3 Accessibility Guidelines.  Now that the longdesc attribute is once again part of the HTML5 recommendation, it may eventually also be supported by the EPUB recommendation.  Should that occur, authors may soon be able to use longdesc in EPUB documents as well as in HTML.