Writing Good Alt Text

Alt text, the alt attribute on an <img> element , is the text equivalent of an image. Screen readers announce it instead of (or alongside) an image file name. Search engines index it. It appears in place of a broken image. It's small, easy to write, and one of the highest-impact things you can do for accessibility.

WCAG SC 1.1.1 (Non-text Content, Level A) requires a text alternative for every non-text element. The right alt text depends entirely on why the image is there.

Informative Images

An informative image conveys content, information a reader would miss if the image weren't there. The alt text should convey the same information the image does.

The goal isn't to describe every pixel. It's to answer: what would I say if I were describing this image over the phone?

<!-- A photo of a storm rolling over a city at sunset -->
<img src="storm.jpg"
     alt="Dark storm clouds approaching a city skyline at sunset,
          with orange light catching the edges of the clouds">

You don't need to begin with "Image of...", screen readers already announce that it's an image. Start with the content itself.

Functional Images

A functional image performs an action, it's a link, a button, or a form control. For these, the alt text describes the function, not the visual appearance.

<!-- A magnifying glass icon that submits a search form -->
<input type="image" src="search-icon.svg" alt="Search">

<!-- A logo that links back to the home page -->
<a href="/">
  <img src="logo.png" alt="A11yGuides.com: home page">
</a>

For the logo example: if the logo links home, describe the destination ("home page"), not the visual logo. The alt text describes what happens when you activate it.

Decorative Images

Decorative images add visual interest but carry no information. A background texture, a purely ornamental divider, or an illustration that simply repeats text already on the page, these should be hidden from screen readers entirely.

Use an empty alt attribute, not a space, not a description, but truly empty:

<!-- Decorative flourish between sections -->
<img src="divider.png" alt="">

An empty alt="" tells assistive technologies to skip the image. Omitting the alt attribute entirely is a failure, screen readers will often announce the file name instead, which is useless and disruptive.

CSS background images used decoratively require no alt text because they are not part of the HTML document. If a background image conveys meaning, however, that meaning must also be available as text in the page.

Complex Images

Charts, diagrams, infographics, and maps often contain more information than a short alt attribute can carry. WCAG SC 1.1.1 calls these "complex images" and recommends:

A short alt attribute identifying the image (its type and subject)
A longer text description elsewhere on the page, or linked to from the page

<figure>
  <img src="chart.png"
       alt="Bar chart showing accessibility audit results;
            see table below for data">
  <figcaption>
    Audit results for the five most common WCAG failures.
    <a href="#audit-data-table">View the data as a table</a>.
  </figcaption>
</figure>

The key: don't try to cram all the data into the alt attribute. Link to or include an equivalent text representation.

Common Mistakes

File names as alt text: alt="IMG_4872.jpg" tells no one anything. This happens when the alt attribute is omitted and a CMS fills in the file name automatically.
Placeholder alt text: alt="image", alt="photo", alt="graphic" , these describe the medium, not the content. A failure under SC 1.1.1 (F30).
Redundant alt text: If caption text already describes the image fully, the alt text needn't repeat it. alt="" is often correct when a <figcaption> is present and provides the same information.
Keyword stuffing: Alt text is not for SEO. Filling it with keywords makes the image harder to understand for screen reader users, and search engines no longer reward it.
Forgetting functional alt text: An image button with alt="" becomes an unlabeled control. Screen readers may announce it as "button" with no indication of what it does. This is a failure under SC 4.1.2 (Name, Role, Value).