How to Write Good Alt Text (With Before-and-After Examples)

How common is the problem

The WebAIM Million audits the home pages of the top one million websites every year. In 2026, missing alt text sat near the top of the list of the most commonly detected WCAG failures. And that figure only counts images with no alt attribute at all. It does not count the images that have alt text which is empty when it should not be, copied from the filename, or written for a search engine rather than a person.

We covered the full set in the 6 most common accessibility failures. This post zooms in on the one that touches almost every site: the humble alt attribute.

Alt text has two audiences

Alt text is a short written description of an image, carried in the alt attribute. It serves two groups at once, which is exactly why it is worth getting right.

The good news: writing for the first audience almost always serves the second. We dug into that overlap in why accessible websites rank higher on Google.

Start by deciding the image's role

There is no single rule for alt text, because not every image does the same job. The first question is never "what is in this image" but "why is this image here". The W3C alt decision tree is the canonical reference. Here is the short version.

Informative images: describe the purpose, not the pixels

Most content images are informative: a product photo, a team headshot, a screenshot. Good alt text for these describes what the image communicates in the context of the page, in a sentence or so. A few rules cover almost every case:

• ✓ Describe the purpose, not just the appearance.
• ✓ Keep it concise. WCAG sets no character limit, but around 125 characters is a widely used rule of thumb, since some screen readers pause around there.
• ✗ Avoid opening with "image of" or "photo of". The screen reader already announces that it is an image.
• ✗ Do not repeat a visible caption word for word.

The length and phrasing points are widely recommended conventions rather than formal requirements. WCAG 1.1.1 asks for a text alternative that serves the same purpose as the image; exactly how you word it is left to you.

Before — unhelpful

alt="DSC_4821.jpg"

Screen reader:"DSC underscore 4821 dot jpg, image"

After — good alt

alt="Latte with a heart in the foam, in a white cup"

Screen reader:"Latte with a heart in the foam, in a white cup, image"

<!-- Filename as alt text describes nothing useful -->
<img src="DSC_4821.jpg" alt="DSC_4821.jpg" />

<!-- Describes what the image conveys in this context -->
<img
  src="DSC_4821.jpg"
  alt="Latte with a heart in the foam, in a white cup"
/>

Decorative images: empty alt, never missing alt

Dividers, background textures, and purely visual flourishes add nothing to the meaning of the page. For these, the right answer is an explicit empty alt="". That tells assistive technology to skip the image entirely. Leaving the attribute off is not the same thing: with no alt at all, some screen readers fall back to reading the file name out loud.

Before — unhelpful

no alt attribute

Screen reader:"section dash divider dot s v g, image"

After — good alt

alt=""

Screen reader:(skipped, nothing announced)

<!-- Decorative divider with no alt: many screen readers
     announce the filename instead of skipping it -->
<img src="section-divider.svg" />

<!-- Empty alt marks it decorative so assistive tech skips it -->
<img src="section-divider.svg" alt="" />

/* Purely visual flourish? A CSS background has no alt at all,
   which is the cleanest option for decoration. */
.section::before {
  background-image: url("section-divider.svg");
}

Decorative and heavy? Think about performance too

Marking an image decorative does not make the file any smaller, so do not reach for alt="" as a performance fix. What decorative images give you is freedom to defer them. A purely visual flourish that sits below the fold rarely needs to load up front. Lazy-load it with loading="lazy", and for backgrounds and textures a CSS background-image keeps the markup clean and carries no alt at all. It still downloads, and how soon depends on your CSS and its priority, so it is not a free pass. Whatever the role, compress the file and set width and height so it does not shift the layout while it loads.

<!-- Decorative, below the fold, and heavy? Keep the empty alt, then
     defer the download so it never blocks the initial render -->
<img
  src="hero-texture.webp"
  alt=""
  loading="lazy"
  decoding="async"
  width="1200"
  height="400"
/>

Functional images: describe the action, not the artwork

When an image is the clickable part of a link or button, the alt text should describe where it goes or what it does. A logo that links home should not read "company logo". It should read "Acme home", because for the person using it, that is its job. This is closely related to the empty-link and empty-button failures in the 6 most common failures: the link exists, but it has no accessible name.

<!-- Linked logo described as a picture, not a destination -->
<a href="/">
  <img src="logo.svg" alt="Company logo" />
</a>

<!-- Alt describes where the link goes, not what it looks like -->
<a href="/">
  <img src="logo.svg" alt="Acme home" />
</a>

Complex images: short alt plus a real description

Charts, graphs, maps, and infographics carry more information than a single sentence can hold. The pattern recommended by the W3C complex images tutorial is a short alt that names the image, paired with a full text description nearby, often in a <figcaption> or adjacent paragraph. The text version also gives search engines the actual data, which an image alone never can.

<!-- Short alt names the chart; the detail lives in real text nearby -->
<figure>
  <img
    src="revenue-2026.png"
    alt="Bar chart of quarterly revenue in 2026, described in the caption"
  />
  <figcaption>
    Revenue rose each quarter in 2026: 1.2M in Q1, 1.6M in Q2,
    2.1M in Q3, and 2.8M in Q4.
  </figcaption>
</figure>

Images of text: avoid them, or repeat the words

Text baked into an image is invisible to screen readers, hard to translate, blurry when zoomed, and ignored by search engines. WCAG 1.4.5 Images of Text asks you to use real text wherever possible. When an image of text is genuinely unavoidable, such as a logo or a promotional banner, the alt text must repeat the words exactly.

<!-- Text baked into an image with empty alt: the offer is
     invisible to screen readers and to search engines -->
<img src="summer-sale-banner.png" alt="" />

<!-- If text must live in an image, the alt repeats it word for word -->
<img
  src="summer-sale-banner.png"
  alt="Summer sale: 25% off all plans until 31 July"
/>

Alt text and SEO: helpful, not stuffed

Google's own Google Images documentation asks for alt text that is descriptive and specific, and warns against stuffing it with keywords. The advice that produces good accessibility produces good image SEO too: describe the image naturally, give the file a meaningful name, and surround it with relevant text. Keyword stuffing fails on both counts. It reads as spam to Google, and it is painful to hear read aloud.

One describes the image. The other describes nobody's idea of a good time. Write the first kind.

Where alt text lives in your stack

The principle is the same everywhere, but the field you fill in differs:

• WordPress: set the "Alternative Text" field in the media library, not the "Title" field. The Title is not exposed to assistive technology and does not act as alt text.
• React and JSX: every <img> needs an alt prop. The jsx-a11y ESLint plugin catches missing ones before they ship.

// React requires an alt prop on every <img>.
// eslint-plugin-jsx-a11y flags a missing one at build time.
<img src={chart} alt="Bar chart of quarterly revenue in 2026" />

// Decorative image: pass an explicit empty string, never omit it.
<img src={divider} alt="" />

Finding missing alt text across a whole site

Knowing the rules is one thing. Finding every image that breaks them, across hundreds of pages, is another. Automated tooling reliably catches the part that is machine-checkable: images with no alt attribute at all. It cannot judge whether existing alt text is meaningful, so think of it as the map, not the destination.

Our free alt text checker scans up to 150 pages from any URL and lists every image missing an alt attribute, with the page it sits on. No sign-up needed. If you are also chasing dead links while you are in there, the broken link checker runs the same way.