Standards for Adding Long Descriptions to Your Content

Status of the longdesc attribute

As of March 2013, longdesc attribute (@longdesc) has been reinstated in HTML5 as an extension specification, and is now available as the HTML5 Image Description Extension  (W3C working draft). Work continues on this extension specification, with an expected completion date in the fall of 2013.  @longdesc is once again “legal” for authors to use in the sense that it is part of HTML and is no longer a deprecated attribute. @longdesc is supported by some major browsers, by JAWS and NVDA screen readers, and ChromeVox (both Mac and Windows).

How it works

The longdesc attribute uses a URL to point to an off-page image description (a code example would be <img src=”foodchain.jpg alt=”A depiction of the food chain.”  longdesc=”foodchain_description.html” />).  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 and then announce “Has long description” or “Press ‘enter’ to hear long description.” The user can then choose to hear the description or not.  Browsers do not currently make it visually obvious that @longdesc is available on images, so its discovery is currently limited to assistive technology. However, there are plans by at least one major browser vendor to provide a visual notification of the presence of @longdesc.  This feature may be available sometime during 2013.

Another way to link images: aria-describedby

There are other ways to link images to long descriptions; among them is using the aria-describedby property, which will associate an image with a description but only on the same page.  It is possible to deliver off-page descriptions to the user using aria-describedby, too, by associating the image with an off-page description that is contained within a hidden element, such as a <div> or an <iframe>. See James Craig’s examples  of hidden descriptions delivered using aria-describedby  to learn more about this technique.

How to decide which method to use

Both 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 now recommends that EPUB authors use aria-describedby to provide image descriptions until a new attribute, aria-describedat (unofficial W3C draft), becomes available in ARIA 1.1 sometime in 2014. 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 or EPUB documents, if the image and description appear on the same page, use aria-describedby to associate one with the other. See example code in the EPUB 3 Accessibility Guidelines
  • In HTML documents, if it is not practical to put the description on the same page as the image, use @longdesc to associate the image with an off-page description.  Take a look at a demonstration of the longdesc attribute to see how it works.  Alternatively, you can also use the hidden aria-describedby technique to link an image with an off-page description.
  • In EPUB documents, if it is not practical to put the description on the same page as the image, use aria-describedby to provide hidden descriptions until aria-describedat becomes available in ARIA 1.1.  Note that aria-describedby will continue to be supported by browsers and assistive-technology vendors, so you will not be required to replace previous instances of aria-describedby with aria-describedat.