Writing useful alt text

Alt text is the text alternative for an image. Screen readers read it aloud, browsers show it when an image fails to load, and search engines use it to understand the image. Good alt text conveys the same information or function as the image, in the context where it appears.

This lesson covers the accessibility side of the alt attribute. The HTML Complete Course covers the img element itself.

The rule: 1.1.1 Non-text Content

Success criterion 1.1.1 Non-text Content (level A) says that all non-text content presented to the user has a text alternative that serves the equivalent purpose. Decorative images are the exception: they must be implemented so that assistive technology can ignore them.

Every img therefore needs an alt attribute. What goes in it depends on the image's purpose.

<!-- Informative: describe the information -->
<img src="queue.jpg" alt="A queue of about thirty people outside the clinic before it opens">

<!-- Decorative: empty alt, so screen readers skip it -->
<img src="divider-swirl.svg" alt="">

<!-- Missing alt: a screen reader may read the file name instead -->
<img src="IMG_20260312_0931.jpg">

Ask what the image is for

Do not ask "what does this image show?". Ask "what would I lose if this image were gone?". The answer is your alt text.

The same photo can need different alt text in different places:

Informative images

Informative images convey information that is not in the surrounding text.

• Be concise. One sentence is usually enough. There is no strict character limit, but long descriptions are tiring to listen to.
• Do not start with "Image of" or "Picture of". Screen readers already announce "image" or "graphic".
• Include text that appears in the image. If a poster says "Closed Monday", the alt text must say so.
• Front-load the important part. Users can stop listening once they have what they need.
• Use correct punctuation. Screen readers pause at full stops and commas, which makes alt text easier to follow.

<img src="chart-sales.png"
     alt="Bar chart: online sales grew every quarter in 2025, from 120 orders in Q1 to 410 in Q4.">

The alt text gives the conclusion, not every bar. If people need the exact figures, provide them as text or in a table next to the chart, which helps everyone.

Decorative images

An image is decorative when it adds only visual styling, or when its content is already in nearby text.

<!-- The icon repeats the visible text, so it is decorative -->
<a href="/basket">
  <img src="basket-icon.svg" alt="">
  Basket
</a>

If the image could be a CSS background without anyone losing information, it is decorative. Purely presentational images often belong in CSS in the first place.

Functional images

When an image is the only content of a link or button, its alt text names the action or destination, not the picture.

<!-- A linked logo: describe where it goes -->
<a href="/">
  <img src="logo.svg" alt="Northfield Library home">
</a>

<!-- An image as the only content of a button -->
<button type="submit">
  <img src="magnifier.svg" alt="Search">
</button>

A screen reader user hears "Northfield Library home, link" and "Search, button". Without alt text they would hear the file name or nothing useful. Lesson 8 covers naming icon buttons in more depth.

Images of text

Avoid putting text in images. It cannot be resized cleanly, translated, restyled or searched. Success criterion 1.4.5 Images of Text (level AA) asks you to use real text instead, except for logos and cases where a particular presentation is essential. When you must use an image of text, the alt text repeats the text exactly.

Complex images

Charts, diagrams and maps hold more information than a short alt can carry. Give a short alt that identifies the image and its main point, then put the full description in the page so everyone can use it.

<figure>
  <img src="org-chart.png"
       alt="Organisation chart for the support team. Full description follows.">
  <figcaption>
    <p>The support team is led by the Head of Support. Three team leads report to them:
       Phone, Email and Chat. Each team lead manages four advisers.</p>
  </figcaption>
</figure>

Visible descriptions also help people with cognitive disabilities and anyone who finds charts hard to read. Lesson 22 returns to accessible charts.

Avoid these common mistakes

• Using the file name, or words like "photo" or "graphic", as alt text.
• Repeating the caption or the adjacent link text word for word, so screen reader users hear it twice.
• Stuffing alt text with keywords for search engines.
• Describing every visual detail when only one matters in context.
• Giving decorative images descriptive alt text, which adds noise.
• Using the title attribute instead of alt. It is not a reliable text alternative.

A quick decision guide

1. Does the image contain text? Put the same text in the alt, unless it is already next to the image.
2. Is it the only content of a link or button? Describe the destination or action.
3. Does it add information not in the surrounding text? Describe that information briefly.
4. Is it purely decorative or already described nearby? Use alt="".
5. Is it complex, such as a chart or diagram? Give a short alt plus a full description in the page.

The W3C alt decision tree, linked in the resources, covers more edge cases.

Summary

• Every img needs an alt attribute; 1.1.1 Non-text Content is a level A requirement.
• Write alt text for the purpose of the image in its context, not a literal description.
• Use alt="" for decorative images; never leave alt out.
• Functional images describe the action or destination.
• Prefer real text to images of text.
• Give complex images a short alt and a full description in the page.