HTML5 Image Description Extension (longdesc)

W3C Candidate Recommendation 12 August 2014

This version:
Latest published version:
Latest editor's draft:
Previous version:
Charles (McCathie) Nevile, ЯндексYandex
Mark Sadecki, W3C through July 2014


This specification defines a longdesc attribute (based on the longdesc attribute of HTML 4) to link descriptions to images in HTML5 content.

By allowing a hyperlink inside another one, this document explicitly redefines the HTML concept of hyperlink in a limited set of circumstances.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was developed through the HTML Accessibility Task Force, and is published by the HTML Working Group with approval by the Protocols and Formats Working Group as a W3C Candidate Recommendation. If you wish to make comments regarding this document, please send them to public-html-a11y@w3.org (subscribe, archives). All feedback is welcome. Bugs can also be filed directly into the W3C Bug tracker for this specification. This Candidate Recommendation is expected to end no sooner than 26 August 2014.

The disposition of comments from the Last Call Working Draft is available.

Significant changes between successive public drafts are tracked in the Change History section.

This document is intended to become a W3C Recommendation.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents


Text alternatives are used to make visual information accessible by describing the information or function represented in an image. The alt attribute is designed to provide a concise description or functional equivalent for an image. For some images and contexts, more detail is required to convey all the information contained in the image. The longdesc attribute is designed as a means to provide this level of detail.

HTML 4 provided a longdesc attribute for the img element that enabled a machine-discoverable description of an image to be linked to the image. This extension specification defines a longdesc attribute to provide that functionality for HTML5.

Example: (Informative)

<!-- The description is somewhere on the same page as the image -->
<img src="http://example.com/graph1" alt="Drinks are getting sweeter"

<!-- The description is a page on its own -->
<img src="figure1" alt="figure 1" longdesc="http://example.com/desc1">

<!-- The description is one of several within an external page -->
<img src="ExampleImage" alt="example" longdesc="http://example.com/descs#item3">

<!-- The description is included in a data: URI -->
<img src="logo" alt="W3C" longdesc="data:text/html;charset=utf-8;,%3C!DOCTYPE%20html%3E

1. Conformance

All authoring guidelines, diagrams, examples, notes, and sections marked "informative" in this specification are informational. Everything else in this specification is "normative" as described in [QAFRAME].

The key words "must", "should", "should not" and "may" in this specification are to be interpreted as described in [RFC2119].

1.1 Dependencies and Definitions

The Interface Definition Language (IDL) fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

The terms "valid non-empty URL potentially surrounded by spaces", "hyperlink", and "reflect", used in this specification are defined in [HTML5], although this specification modifies the semantics of the term "hyperlink" in allowing hyperlinks to be nested in certain specific circumstances.

This document uses the terms accessible and accessibility in the sense of ensuring people with disabilities can use the Web. Further information is available, e.g. Introduction to Web Accessibility.

2. Use Cases and Requirements

The longdesc attribute gives authors a mechanism for referencing a long text description for images which cannot be adequately described using shorter description mechanisms, such as in the following use cases.

Use Cases

Identifying a well-known image
Identifying an image is often important context for a discussion. There are many well-known images which are widely reproduced and well known. In some cases, such as "Mona Lisa", "Guernica", "A Starry Night", or "The Scream", the most effective way to identify an image is to use its title, creator, and similar information that would be found in a catalog. But different people know images by different titles, and some titles are not well known. When the image itself cannot be seen, a description can often be used to offer easier recognition than the cataloging information, for example "Washington crossing a river, standing heroically in a boat, while soldiers do all the paddling", or "the Da Vinci picture of the man in a square and a circle".
Requires: Discoverability
Helped by: Inline, Optional Consumption, Reuse, Simple Return
Describing a complex diagram
In many environments diagrams are used to explain a concept or transmit information efficiently. For a user with a reduced ability to see the image (poor contrast vision and other conditions are as relevant here as a complete lack of vision), a description can enable that user to understand the information being presented.
Requires: Structured Markup
Helped by: Inline, Reuse, Simple Return
Teaching accessible development
In many environments producing content that is accessible to users regardless of disability is a legal and/or market requirement.
Requires: Backwards Compatibility, Maintenance
A self-describing artistic work
The visual design of many pages is an important part of the message the author intends to convey to a fully-sighted user. Many authors would like to convey as much of that design as possible to a user with low or no vision.
Requires: Discoverability, No Visual Encumbrance, Structured Markup
Helped by: Reuse, Simple Return
Referring to an existing description
Many well-known images are already described by other sources. The copyright on those sources may not be compatible with re-publishing the description, but there is little value in making a new one.
Requires: Discoverability, Optional Consumption, Reuse, Simple Return
Helped by: No Visual Encumbrance
Linking to a description included within a page
If an image already has a description included within a page, making the linkage explicit can provide further clarity for a user who is not able to interpret the default layout. For example this happens when users force a re-layout of the page elements because they have magnified the content, or because they do not see the default visual relationship between the element and its description.
This practice also enables description to be provided for all users.
By keeping the association clear the content maintainer can more easily check that the description and link are actually correct.
Requires: Discoverability, Inline, Optional Consumption, Simple Return, Structured Markup
Localizing descriptions
When content is translated to multiple languages, it is important that metadata intended for humans, such as image descriptions, can be readily localized.
Helped by: Structured Markup, Reuse, Maintenance.
Image search
Many search engines provide an option to search for images and present the results out of context. The ability to discover and process identified descriptions allows search engines to improve the source material they use to support text-based queries for images.
Requires: Discoverability
Helped by: Structured Markup
Describing images
Image search tools identify multiple copies of the same image. Where a search tool can identify a description of an image, this can be provided to the user as a description for any copies of that image.
Requires: Discoverability
Helped by: Reuse

Requirements for an Image Description Functionality

Backwards Compatibility
It should be possible to use existing tools and techniques to associate an image with its description.
It must be simple for a user agent to automatically discover a description provided for a given image.
A user should be able to determine that there is a description available for a given image.
It must be possible to associate a description in the body of a page with an image in that page.
It must be simple to maintain a library of images and descriptions for dynamic assembly, or dis-assembly and re-assembly, of content.
No Visual Encumbrance
It must be possible to provide a description for an image without forcing the description to be rendered on the page.
Optional Consumption
A user must be able to choose not to read the long description of a given image.
It must be possible to re-use a single description for multiple occurrences of an image.
Simple Return
A user must be able to return from the description to the image.
Structured Markup
It must be possible to include rich markup (e.g. HTML5) in the description of the image.

3. The longdesc Attribute

This extension changes the definition of a hyperlink in HTML, by allowing a longdesc attribute to occur inside a hyperlink.

3.0 Implementation

3.0.1 Authors and Conformance Checkers

Zero or one longdesc attributes may be added to any img element.

The longdesc attribute must contain a valid non-empty URL potentially surrounded by spaces. The URL is a hyperlink to a description of the image that the parent img element represents.

The linked description should be in a broadly accessible format.

This section is informative

Best practices for checking descriptions of images are beyond the scope of this document, but there are many resources available. For further guidance authoring tool developers can consult e.g. Appendix A-3: Long text descriptions of [ATAG].

High quality implementation in authoring and content management tools is likely to include checking for common errors, such as including a description instead of a URL in the attribute, or pointing to a resource that is an image or plain text, which are often poor choices for a high-quality description. Additional examples of error checking and repair options can be found in Appendix B: Levels of Checking Automation and Appendix C: Levels of Repair Automation of [ATAG]

3.0.2 Authors

When a description is only part of the target document, authors should link to a container element in the target document that contains the entire description.

Example: (Informative)

<!-- Image with description that is only part of target document -->
<img src="foo.png" alt="Example image" longdesc="example.html#desc2">

<!-- Target document -->
<section id="desc2">
  <h2>Image foo.png</h2>
  <p>Description of the image...</p>

This section is informative

Best practices for full descriptions of images are beyond the scope of this document, but there are many resources available.

Authors should not rely solely on longdesc where standards exist to provide direct, structured access.

This section is informative

For example a MathML version of mathematical content, or an SVG image that uses the accessibility features of SVG, can provide direct accessibility to users with appropriate technology. In such cases, it is appropriate to use those techniques in combination with longdesc.

3.0.3 User Agents

If the longdesc value is valid, User agents must make the link available to all users through the regular user interface(s). 

If the longdesc value is valid, User agents must expose the link to relevant APIs, especially accessibility-oriented APIs.

User agents should enable users to discover when images in a page contain a long description.

This section is informative

longdesc can be present on an image within a hyperlink. This does not change the requirements on user agents, which must still enable the hyperlink to be followed.

Complete documentation of best practices for implementation is beyond the scope of this document. These notes are offered to help minimize the impact of common mistakes.

A common mistake in the past has been to use a description, instead of a URL that links to a description. Converting such values to data: URLs is a repair strategy for user agents that can help users to recover in cases where authors have made this mistake.

It is usually helpful when the behavior for finding, reading, and returning from a long description to the image described is a consistent experience.

Further information on making user agents accessible can be found in [UAAG].

3.1 Extension to the HTMLImageElement Interface

partial interface HTMLImageElement {
             attribute DOMString longdesc;

3.1.1 Attribute

longdesc of type DOMString

The longdesc IDL attribute must be a valid non-empty URL potentially surrounded by spaces. It defines a hyperlink to a detailed description of the image its parent HTMLImageElement represents.

The longdesc IDL attribute must reflect the HTML content attribute longdesc.

This section is informative

image.longdesc [ = value ]

Returns a DOMString that represents the attribute's contents.

Can be set, to replace the contents of the attribute with the given string.

Example: (Informative)

/*Make the first internal longdesc reference absolute*/

var baseURL = document.location.origin + document.location.pathname
var someImage = document.querySelector('img[longdesc^=#]');

someImage.longdesc = baseURL + someImage.longdesc;
Example: (Informative)

/*Open new windows for each longdesc found*/

var describedImages = document.querySelectorAll('img[longdesc]');

for (i in describedImages) {
  if (i.longdesc)
Example: (Informative)

/*Tries to repair errors where the longdesc isn't a URI*/

var describedImages = document.querySelectorAll('img[longdesc]');

for (i in describedImages) {
  if (i.longdesc && !(validURL(i.longdesc)) { //assumes some URL validating function
    var theData = encodeURIComponent(i.longdesc);
    i.longdesc = "data:text/plain;charset=";
    i.longdesc += document.charset;
    i.longdesc += theData;

A. Acknowledgements

This section is informative

Thanks to the HTML Working Group of the late 1990s for the original specification of longdesc, to those who have implemented it in various kinds of software, and to many many people involved with the development of HTML5 (including but not limited to those who discussed "ISSUE-30" in the HTML Working Group, the Protocols and Formats Working Group, the W3C Advisory Board, and around countless dinner tables, coffee breaks, and elsewhere) for the ideas, discussions and contributions that led to the initial draft of this specification. With the exception of Laura Carlson, who did far more very valuable work than it took me to produce this specification, I haven't named them: the list might be larger than the content of the specification.

For specific comments and suggestions that led to improvements over successive drafts of this specification, thanks to the W3C's HTML Accessibility Task Force, the W3C Internationalization Working Group, and to Jonathan Avila, Robin Berjon, James Craig, Paul Cotton, Steve Faulkner, John Foliot, Geoff Freed, Peter Gruzca, Richard Ishida, Anne van Kesteren, David MacDonald, Michelle McManus, Chris Mills, Jay Munro, Devarshi Pant, Marta Pawlowska, Silvia Pfeiffer, Wendy Seltzer, Leif Halvard Silli, Mathew Turvey, Klaas 'Z4us' V, and Boris Zbarsky. The code examples are rendered with Lea Verou's prism tools. Any errors are despite, not as a result of, their efforts.

B. References

B.1 Normative References

Robin Berjon et. al., eds. HTML5. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/

B.2 Informative References

Karl Dubost et. al., eds. QA Framework: Specification Guidelines., August 2005. W3C Recommendation. URL: http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/
Jutta Treviranus et. al., eds. Implementing ATAG 2.0, October 2011. W3C Working Draft. URL: http://www.w3.org/TR/2013/WD-IMPLEMENTING-ATAG20-20131107/
Ian Jacobs et. al., eds. User Agent Accessibility Guidelines 1.0, December 2002. W3C Recommendation. URL: http://www.w3.org/TR/2002/REC-UAAG10-20021217/. A draft for a version 2.0 is available at http://www.w3.org/TR/UAAG20/

C. Change History

This section is informative

Between the current draft and the Last Call Working Draft

Editorial changes include:

  • Improved markup used for informative sections for better screen reader support
  • Moved introductory text from "Use Cases" to "Introduction" and modified it to more clearly define the longdesc attribute.
  • Added more precise references to relevant sections of ATAG in the "Implementation" section.
  • Added text to clarify the use of longdesc in conjunction with other techniques.
  • Added the "Image Search" and "Describing images" use case.
  • Improved examples in the "Identifying a well known image" use case
  • Clarified the scope of normative text in the "Conformance" section.
  • Hyperlinked "Use Case" references to their definitions and rearranged definitions in alphabetical order.
  • Removed "title" attribute from example.
  • Added Mark Sadecki as an editor.
  • Various changes to improve readability and consistency.

Between the Last Call Working Draft and the Second Public Working Draft

Editorial changes include:

  • Explicitly stating that longdesc makes a limited change to the semantics of the term "hyperlink" in HTML
  • Editing of the informative guidance in various places.
  • Explicitly adding a reference to the software license to allow people to re-use the code samples and IDL more easily with fewer restrictions.

Between the Second Public Working Draft and the First Public Working Draft

Substantive changes include:

  • Added a requirement that the destination of a longdesc should be "accessible".
  • The requirement to present content through the standard User Interface was changed from should to must.
  • The requirement to present content through the standard User Interface was narrowed to apply only to valid values of longdesc.
  • The requirement to present content through the Accessibility APIs was changed from should to must.
  • The requirement to present content through the Accessibility APIs was narrowed to apply only to valid values of longdesc.
  • The IDL attribute longdesc was changed to reflect the HTML content attribute longdesc.

Editorial changes include:

  • Clarifying that the document does not define "accessible", except that it is used in the sense that it is used in [WCAG].
  • Sectioning requirements according to whom they apply.
  • Removed the statement that User Agents may present descriptions which are erroneously included in the content instead of a link.
  • Added more examples