HTML Guides for longdesc

The longdesc attribute was originally designed to point to a URL containing a detailed description of an element’s content, primarily as an accessibility feature for screen reader users. On <iframe> elements, it was intended to describe the framed content for users who couldn’t perceive it directly. However, the attribute was poorly implemented across browsers, rarely used by assistive technologies, and was ultimately removed from the HTML specification for <iframe> elements.

Using obsolete attributes causes W3C validation errors and can create a false sense of accessibility. Since browsers and assistive technologies don’t reliably process longdesc on iframes, users who need the description may never actually reach it. A visible link, on the other hand, is universally accessible — it works for all users regardless of their browser, device, or assistive technology.

The fix is straightforward: remove the longdesc attribute from the <iframe> and place a regular <a> element near the iframe that links to the description page. This approach is more robust because the link is visible, discoverable, and works everywhere.

Examples

❌ Obsolete: Using longdesc on an <iframe>

<iframe src="report.html" title="Annual report" longdesc="report-description.html"></iframe>

This triggers the validation error because longdesc is no longer a valid attribute on <iframe>.

✅ Fixed: Using a visible link instead

<iframe src="report.html" title="Annual report"></iframe>
<p>
  <a href="report-description.html">Read a detailed description of the annual report</a>
</p>

The longdesc attribute is removed, and a descriptive link is placed adjacent to the iframe so all users can access it.

✅ Alternative: Wrapping in a <figure> for better semantics

For a more structured approach, you can use a <figure> element with a <figcaption> to associate the description link with the iframe:

<figure>
  <iframe src="report.html" title="Annual report"></iframe>
  <figcaption>
    Annual report overview.
    <a href="report-description.html">Read the full description</a>.
  </figcaption>
</figure>

This groups the iframe and its caption together semantically, making the relationship between them clear to both sighted users and assistive technologies.

✅ Alternative: Using aria-describedby for additional context

If you want to provide a short inline description that assistive technologies can announce automatically, you can use aria-describedby:

<p id="report-desc">
  This iframe contains the interactive annual report for 2024.
  <a href="report-description.html">Read the full description</a>.
</p>
<iframe src="report.html" title="Annual report" aria-describedby="report-desc"></iframe>

This links the iframe to the descriptive paragraph programmatically. Screen readers will announce the content of the referenced element when the iframe receives focus, while the visible link remains available to all users.

Key Takeaways

• Always include a title attribute on <iframe> elements to describe their purpose — this is an important baseline accessibility practice.
• Replace longdesc with a visible <a> element that links to the long description.
• Place the link near the iframe so users can easily find it.
• Consider using <figure> and <figcaption> or aria-describedby for stronger semantic association between the iframe and its description.

The longdesc attribute dates back to HTML4, where it accepted a URL pointing to a separate page (or section of a page) containing a detailed description of the image. The idea was to supplement the short text in the alt attribute with a more comprehensive explanation, particularly useful for complex images like charts, diagrams, or infographics.

HTML5 made longdesc obsolete for several reasons. Browser support was inconsistent — most browsers never exposed the attribute in a way that was easily discoverable by users. Many developers misused it by placing literal descriptions in the attribute instead of URLs, or left it pointing to broken links. Because the attribute was invisible in the rendered page, there was no visual indication that a longer description existed, making it practically useless for sighted users and unreliable for assistive technology users.

The recommended replacements are more robust and accessible:

• Wrap the image in an a element (or place a link nearby) that points to the description page. This makes the link visible and usable by everyone.
• Use aria-describedby to reference a description that already exists on the same page. This is ideal when the detailed description is displayed alongside the image.
• Use a figure with figcaption to associate a visible caption or description directly with the image.

These approaches are better for accessibility because they work reliably across browsers and assistive technologies, and they make the description discoverable to all users, not just those using specific screen readers that happened to support longdesc.

Examples

❌ Obsolete: using longdesc

<img
  src="cat.jpg"
  alt="Smiling cat sitting on a windowsill"
  longdesc="descriptions/smiling-cat.html">

This triggers the validation error because longdesc is no longer a valid attribute on img in HTML5.

✅ Fix: wrap the image in a link

The simplest replacement is to make the image itself a link to the description:

<a href="descriptions/smiling-cat.html">
  <img src="cat.jpg" alt="Smiling cat sitting on a windowsill">
</a>

✅ Fix: provide a separate link near the image

If you don’t want the image itself to be clickable, place a visible link nearby:

<figure>
  <img src="chart.png" alt="Quarterly revenue chart for 2024">
  <figcaption>
    Quarterly revenue chart.
    <a href="descriptions/revenue-chart.html">View detailed description</a>
  </figcaption>
</figure>

✅ Fix: use aria-describedby for on-page descriptions

When the long description is already on the same page, reference it with aria-describedby:

<figure>
  <img
    src="chart.png"
    alt="Quarterly revenue chart for 2024"
    aria-describedby="chart-description">
  <figcaption id="chart-description">
    Revenue grew from $2.1M in Q1 to $3.8M in Q4, with the largest
    quarter-over-quarter increase occurring between Q2 and Q3.
  </figcaption>
</figure>

This approach keeps the description visible on the page and programmatically associates it with the image for screen readers.

Choosing the right approach

In all cases, make sure the alt attribute still provides a meaningful short description. The long description supplements alt — it doesn’t replace it.