Accessible Publishing Knowledge Base



Include an extended description for complex images, tables.



There are many reasons why describing content adds to its accessibility for all users. Although often considered only useful for non-visual users, descriptions facilitate comprehension and provide context for users with a wide range of needs. They can also assist users whose first language may not be that of the text being read.


The aria-describedby attribute can be used to add a description to any HTML5 element, not just img, and is the currently recommended mechanism for referencing descriptions in EPUB 3.

The attribute references the ID of the element on the page containing the description. For example:

<table aria-describedby="table-desc">

<aside id="desc">
   <p>The table is composed of three smaller tables
        each of which … </p>

Note that the ID reference does not include a hash (#) at the start. If the description is spread across multiple elements, the ID of each can be listed in the attribute.

It is not required that the element containing the description be visible content. The aria-describedby attribute can point to hidden elements:

<img … aria-describedby="img-desc"/>

<aside id="desc" hidden="hidden">

Before using hidden content too extensively, be aware that the ability to navigate the description is removed when content is not visible. Hidden descriptions are read as one long text string that the user has to listen to in its entirety.

One of the primary limitations of aria-describedby is that the element containing the description must be present in the same page as the content that is being described, so it is not possible to reference out-of-band descriptions directly. The workaround to this limitation is to reference the external description through an iframe element:

<img src="bunny.jpg" aria-describedby="bunny-desc"/>

<iframe id="desc" src="bunny-description.xhtml" hidden="hidden"></iframe>

Although using an iframe in this fashion mimics the out-of-band functionality of the longdesc attribute, there are a number of drawbacks:

  • There is no way to reference into the content in the iframe from an aria-describedby attribute; all content in the iframe will be read.
  • The iframe will be announced as a separate document.
  • Using many iframe elements slows down the loading of documents, since each description must be loaded, unlike proper out-of-band linking mechanisms, which allow the content to only be loaded as requested by the user.

Related Links

Frequently Asked Questions

Why link to visible descriptions?

Even though a description is a visible part of the current page, linking to it provides a programmatic means for users of assistive technologies to rapidly access the description without having to hunt through the page content.

Why not longdesc?

The longdesc attribute is an HTML5 extension not currently supported by EPUB. It is also limited to being attached to img elements.

Why not aria-details?

The aria-details attribute is currently under development and not supported by assistive technologies. It will allow an association to be made with a description in a details element. Although similar to aria-describedby, the aria-details attribute will not result in stringified content (i.e., the user will be able to navigate the description as structured HTML).