HTML longdesc Attribute

Introduction

The longdesc attribute was designed to point from an <img> element to a URL containing a longer description of the image—useful for complex charts or diagrams where alt alone is too short. It is now obsolete in HTML5. Browsers never implemented it consistently, and modern accessibility guidelines recommend on-page descriptions with aria-describedby, <figure>/<figcaption>, or visible “Long description” links instead.

What You’ll Learn

Purpose of longdesc

The original purpose of longdesc was to improve accessibility for complex images by linking to a separate document with a full textual description—for example, a detailed explanation of a scientific chart or map that would not fit in the alt attribute.

Because the URL was hidden with no standard UI in most browsers, users often never discovered the long description. HTML5 removed longdesc from the specification. You should understand it when maintaining legacy pages, but not add it to new work.

📝 Syntax

Legacy syntax (recognition only):

<img src="chart.png" alt="Sales chart 2024" longdesc="chart-description.html">

Modern replacement:

<figure>
  <img src="chart.png" alt="Sales chart 2024"
       aria-describedby="chart-desc">
  <figcaption>Sales by quarter</figcaption>
</figure>
<p id="chart-desc">Detailed description of the chart…</p>

Syntax Rules

• Historically on <img> (and rarely <frame> in old HTML).
• Value was a URL string pointing to an HTML page with the extended description.
• Always required a meaningful alt as well—longdesc was supplemental, not a replacement.
• Obsolete in HTML5—validators flag it; do not use on new images.
• Use same-document ids with aria-describedby for screen reader associations.
• Legacy DOM property: longDesc (camelCase) on HTMLImageElement.

💎 Values

The longdesc attribute accepted a URL referencing a document with the long description:

• longdesc="chart-description.html" — Relative URL on the same site.
• longdesc="https://example.com/descriptions/photo.html" — Absolute URL.
• longdesc="#details" — Fragment URL to an on-page section (rarely supported reliably).

Modern equivalent uses an element id, not a separate attribute on img:

// Legacy (avoid):
img.longDesc = "old-page.html";

// Modern:
img.setAttribute("aria-describedby", "photo-desc");

Applicable Elements

longdesc vs alt vs aria-describedby

Examples Gallery

Legacy longdesc markup, a modern accessible figure pattern, and toggling a visible long description.

👀 Live Preview

Modern pattern with visible long-description link:

Q1 sales were 12 units, Q2 18, Q3 24, and Q4 30—a steady upward trend across the year.

Example — Legacy longdesc (Do Not Use)

index.html

Copy

<img src="example.jpg" alt="Example Image" longdesc="longdesc.html">

View Output Try It Yourself

📤 Output:

Browsers render the image but provide no reliable way to discover longdesc.html. Screen reader support was inconsistent. Replace with on-page description text.

How It Works

The attribute pointed to a separate document. Because discovery failed for most users, the feature was removed from HTML5.

Example — Modern Accessible Pattern

accessible-image.html

Copy

<figure>
  <img src="chart.png" alt="Quarterly sales bar chart"
       aria-describedby="chart-long-desc">
  <figcaption>
    Sales 2024
    <a href="#chart-long-desc">Long description</a>
  </figcaption>
</figure>
<div id="chart-long-desc">
  Q1 through Q4 show steady growth from 12 to 30 units…
</div>

View Output Try It Yourself

📤 Output:

Sighted users follow the visible link. Screen readers hear the alt and can read the associated description via aria-describedby.

How It Works

The description stays on the same page where everyone can find it. aria-describedby links the image to the detailed text programmatically.

Example — Expandable Long Description

toggle-desc.html

Copy

<img id="diagram" src="diagram.png" alt="Network diagram"
     aria-describedby="diagram-desc">
<button type="button" aria-expanded="false" aria-controls="diagram-desc">
  Show long description
</button>
<div id="diagram-desc" hidden>…</div>

View Output Try It Yourself

📤 Output:

Clicking the button reveals the description for all users while aria-describedby keeps it available to assistive tech when expanded.

How It Works

An expandable panel replaces the hidden external URL pattern of longdesc with discoverable, keyboard-accessible UI.

♿ Accessibility

• Always provide alt — Even with a long description, images need concise alternative text.
• Do not use longdesc on new sites — It is obsolete and poorly supported.
• Put long text on the same page — Link with aria-describedby or a visible anchor.
• Make descriptions discoverable — Unlike longdesc, visible links help sighted users too.
• Use aria-expanded on toggles — Announce show/hide state for description panels.
• Consider a data table — For charts, an accessible table of the same data benefits everyone.

💡 Best Practices