How to write good alt text: decorative, informative, functional and complex images

Alt text is the text a screen reader reads in place of an image. It also appears when an image fails to load, and search engines use it to understand what an image shows. WCAG requires a text alternative for every image that carries meaning, and a way for assistive technology to ignore the ones that don’t (1.1.1 Non-text Content, level A).

It is also one of the most common failures on the web. In WebAIM’s 2026 test of the top one million home pages, 53.1% had images without alternative text (WebAIM Million 2026). Missing alt text is easy to detect automatically. Bad alt text isn’t: a tool can’t tell whether “photo” or “team” helps anyone. This guide is about writing alt text that does.

Start with one question

Ask: what is this image doing on this page? The answer, not the picture itself, decides the alt text. The W3C’s alt decision tree boils it down to a few cases:

• Decorative: it adds nothing a reader would miss. Use an empty alt.
• Informative: it shows something the text doesn’t say. Describe what it means here.
• Functional: it is a link or a button, or the only content of one. Say where it goes or what it does.
• Text: it is a picture of words. The alt text is those words.
• Complex: a chart, map or diagram with more information than a sentence can carry. Give a short alt and a full description nearby.

Decorative images: alt=""

Background textures, dividers, flourishes, a stock photo of smiling people next to a heading that already says “Our team”: if removing the image wouldn’t lose any information, it is decorative. Give it an empty alt attribute.

<img src="wave-divider.svg" alt="">

Empty is not the same as missing. With alt="", screen readers skip the image. With no alt attribute at all, many read the file name instead: “I M G underscore 4471 dot J P G”. Never leave it out.

• Better still, put purely visual decoration in CSS (background-image), where assistive technology won’t see it.
• An icon next to a text label is decorative too: the text already says it. Hide inline SVG icons with aria-hidden="true".
• Don’t mark an image decorative just because it is hard to describe. If it carries information, it needs a text alternative.

Informative images: describe the meaning, not the pixels

Write what a sighted reader gets from the image in this context, in as few words as that takes. Usually that is a phrase or a short sentence.

Context changes the answer

The same photo of a bike can need three different alt texts. On a product page: “City bike in matt green with a front basket and dynamo lights”. In a blog post about a cycling holiday: “Our rented bike leaning on a fence above the Moselle valley”. As a background behind a heading that says “Bike repairs in Utrecht”: empty. That is why alt text set once in a media library is often wrong; most CMSs let you change it each time you insert the image.

Writing rules

• Don’t start with “image of” or “picture of”. Screen readers already announce it as an image. Do say “photo”, “painting” or “screenshot” when the type of image matters.
• Lead with what matters. People can stop listening once they have what they need.
• Don’t repeat nearby text. If the caption or the sentence next to the image says it, the alt can be shorter or empty.
• Include text that appears in the image, such as a sign or a label that matters.
• Write it as a sentence or phrase, with normal punctuation, in the page’s language.
• Don’t stuff keywords. Alt text written for search engines reads badly to people, and search engines want it to describe the image too.
• Keep it short. There is no fixed character limit in WCAG, but alt text can’t be paused or navigated in parts the way page text can. If you need more than a sentence or two, the image is probably complex (see below).

Functional images: say what happens

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

<!-- Bad: the screen reader says "link, magnifying glass" -->
<a href="/search"><img src="magnifier.svg" alt="magnifying glass"></a>

<!-- Good: "link, Search" -->
<a href="/search"><img src="magnifier.svg" alt="Search"></a>

<!-- A logo that links home -->
<a href="/"><img src="logo.svg" alt="Acme Bikes home"></a>

<!-- Social link -->
<a href="https://www.instagram.com/acmebikes"><img src="instagram.svg" alt="Acme Bikes on Instagram"></a>

An empty alt is wrong here: the link or button is left with no name at all, and screen readers announce something like “link” or read the URL. This is one of the failures the alt text checker flags. Criteria: 2.4.4 Link Purpose (In Context) and 4.1.2 Name, Role, Value.

When the link also has text

If a link contains both an image and text that says the same thing, such as a product card with a photo and the product name, give the image an empty alt so the name isn’t read twice:

<a href="/boots/ankle-red">
  <img src="ankle-red.jpg" alt="">
  Red leather ankle boot
</a>

Inline SVG icons

SVG icons inside buttons don’t have an alt attribute. Hide the icon and name the button instead:

<button type="button" aria-label="Close">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

If a button has visible text and an icon, the text is the name and the icon stays hidden. When there is visible text, the accessible name should contain it, so voice control users can say what they see (2.5.3 Label in Name).

Images of text

If an image shows words, such as a banner with “Summer sale: 20% off everything” or a scanned opening-hours sign, the alt text is the words:

<img src="summer-sale.png" alt="Summer sale: 20% off everything until August 31">

Better: don’t use images of text at all. Real text can be resized, recolored, translated and read by everyone. WCAG asks for real text wherever the presentation can be achieved with it; logos are the exception (1.4.5 Images of Text).

Complex images: short alt plus a long description

Charts, graphs, diagrams, maps and infographics hold more information than an alt attribute should. Use two parts (W3C complex images tutorial):

1. A short alt that says what the image is and, ideally, its main point.
2. A full description in the page, where everyone can read it: a paragraph, a list or a data table.

<figure>
  <img src="orders-2026.png"
       alt="Bar chart: online orders by month in 2026, rising from 410 in January to 980 in June."
       aria-describedby="orders-desc">
  <figcaption>Online orders per month, January to June 2026</figcaption>
</figure>
<div id="orders-desc">
  <table>
    <caption>Online orders per month, 2026</caption>
    <tr><th scope="col">Month</th><th scope="col">Orders</th></tr>
    <tr><td>January</td><td>410</td></tr>
    <tr><td>February</td><td>455</td></tr>
    …
  </table>
</div>

A data table under the chart is the most useful long description for charts: it works for screen reader users, for people who want exact numbers, and for anyone who can’t tell two similar colors apart. Make sure the chart doesn’t rely on color alone (1.4.1 Use of Color), and that the table uses real header cells (1.3.1 Info and Relationships).

For a map showing where your shop is, the long description is the address and directions in text. For an organization chart, it is a nested list.

Other cases you will meet

• Image galleries: each image needs its own alt. If several photos show the same thing from different angles, say what differs: “Back view”, “Detail of the stitching”.
• Images in carousels: the alt describes the slide’s content; the controls (“Next slide”, “Pause”) are buttons with their own names.
• CAPTCHAs: the alt should say what the image is for (“Security check: type the characters you see”), and there must be another way through, such as an audio version. See also 3.3.8 Accessible Authentication.
• Emoji and icons in text: screen readers read the emoji’s name, so “Opening soon 🔥🔥🔥” is read as “Opening soon fire fire fire”. Use them sparingly.
• Images in PDFs, emails and social posts: the same rules apply. Most email editors and social platforms have an alt text field; use it.

What about AI-generated alt text?

Image recognition can describe what is in a picture, and it is a useful first draft when you have thousands of product photos with nothing at all. It can’t know why an image is on your page: it doesn’t know that the photo is of your terrace, that the screenshot is about the Export button, or that the image is decorative. Treat generated alt text as a draft that a person reviews, never as the finished result. The same applies to accessibility overlays that add alt text automatically (see why overlays don’t make a site accessible).

How to check your alt text

1. Find the missing ones. Paste a page’s HTML into the alt text checker. It lists every image with its alt, and flags missing alt, empty alt in links and buttons, file names, placeholder words and “image of”.
2. Read them in context. For each image, read the alt text out loud in place of the image, with the surrounding sentence. Does the paragraph still make sense? Did you lose anything?
3. Listen once. Turn on VoiceOver (Cmd+F5 on a Mac) or NVDA on Windows and read a key page. Redundant and unhelpful alt text becomes obvious quickly.
4. Fix the source. Correct alt text in the CMS, and add an “alt text” step to your publishing checklist so new images arrive right.

Automated checks, including Perceivly’s, find images with no alt text and links or buttons with no name. They can’t judge whether an alt text is accurate or useful, which is the part that needs a person who can see the image. For the rest of the basics, see our website accessibility checklist.

Sources

• Images tutorial and An alt decision tree (W3C Web Accessibility Initiative)
• Complex images (W3C Web Accessibility Initiative)
• Understanding Success Criterion 1.1.1: Non-text Content (W3C)
• Requirements for providing text to act as an alternative for images (HTML Living Standard, WHATWG)
• The WebAIM Million, 2026 report (WebAIM)