How to write alt text: a guide with examples

Alt text (alternative text) is one of the simplest and most effective things you can do for an accessible website — and it’s constantly done wrong. Good alt text makes an image usable for people who can’t see it, and helps search engines along the way. This guide covers the rules, the crucial difference between image types, and lots of concrete examples. It’s the hands-on companion to our pillar guide, how to make your website accessible.

What is alt text — and why does it matter?

Alt text is a text description you give an image in its alt attribute. Sighted users normally don’t see it — it’s for everyone who can’t perceive the image:

• Screen readers read the alt text aloud, so blind and low-vision people know what the image shows.
• When an image fails to load (slow connection, error), the browser shows the alt text.
• Search engines use it to understand the image — good alt text improves image SEO.

Alt text is also a core part of the WCAG: the “non-text content” criterion requires text alternatives for all informative images. Missing them is one of the most common — and most easily avoided — barriers.

The basic rule: describe function and meaning in context

Good alt text doesn’t describe every detail — it describes the purpose of the image in this place. The same file may need different alt text depending on context. A photo of a running shoe on a product page describes the model; the same photo in an article about injury prevention might describe the cushioning. So always ask: why is this image here, and what would someone miss if they couldn’t see it?

Two phrases you can drop: “image of …” and “graphic showing …”. Screen readers already announce that it’s an image. Get straight to the content.

The four image types — and how to handle them

Before you write, sort the image into one of these types:

1. Informative images carry content (product photos, charts, explanatory illustrations). → Describe the meaning briefly and concretely.
2. Decorative images are there only for looks (dividers, mood backgrounds, ornamental icons). → Empty alt attribute: alt="". That way screen readers skip them. Important: leaving the attribute out entirely is not the same — then screen readers often read the file name.
3. Functional images trigger an action or are linked (a linked logo, a magnifier icon as a search button). → Describe the function, not the appearance: “Home”, “Open search”.
4. Complex images contain a lot of data (charts, infographics, maps). → A short alt text plus a detailed description nearby (body text, a table, or a linked long description).

Good vs bad: concrete examples

Product photo

• ❌ alt="image" / alt="IMG_2043.jpg"
• ✅ alt="Red running shoe seen from the side, with a white sole"

Decorative background image

• ❌ alt="abstract green waves background decorative"
• ✅ alt="" (empty — the image carries no information)

Linked logo

• ❌ alt="logo"
• ✅ alt="Welcoma — home"

Icon button (magnifier)

• ❌ alt="magnifier"
• ✅ alt="Search"

Chart

• ❌ alt="chart"
• ✅ alt="Bar chart: revenue per quarter 2025, Q4 highest at €1.2m" (plus a data table below)

Text in an image (e.g. a banner with promo text)

• ❌ alt="banner"
• ✅ The alt text contains the text from the image: alt="20% off all shoes until Sunday"

Practical writing tips

• Keep it short. One or two sentences usually do; many screen readers and guidelines work to around 125 characters. Anything that needs more explanation belongs in a separate description.
• Write for people, not search engines. No keyword stuffing. A natural, accurate description ranks better and helps real users.
• No “image of”, no file names. Straight to the content.
• Don’t repeat the caption. If a caption right next to the image already states the same thing, the image can be decorative (alt="") — otherwise screen readers hear it twice.
• Punctuation helps. A full stop at the end creates a natural pause when read aloud.

Special cases that are often missed

• Image as the only content of a link: if an image sits inside a link with no other link text, the alt text must describe the link target — otherwise the screen reader only announces “link”. A linked thumbnail gets the title of its target as alt text.
• CAPTCHAs: image-only CAPTCHAs are a barrier in themselves. Offer an alternative (audio or logic-based) and describe the purpose in the alt text, not the solution.
• Emojis and icon fonts: emojis carry a built-in text meaning that gets read aloud — use sparingly. Hide decorative icon fonts with aria-hidden="true"; give functional ones a text label.
• CSS background images: images set via CSS have no alt attribute. If they carry information, that information belongs in the HTML as real text — otherwise it’s lost to screen readers.

Alt text, title, caption — what’s what?

These fields are often confused:

• Alt text (alt): the text alternative for assistive technologies — this is the important one.
• Title (title): appears as a tooltip on hover, but is unreliable for keyboard and touch users. Not a substitute for alt text.
• Caption (figcaption): visible to everyone and useful for sources or context — but it doesn’t replace alt text.

When in doubt: the alt text is required, the rest is optional.

Alt text in WordPress

In WordPress you enter the alt text directly in the media library: select the image, fill in the “Alt text” field — ideally right when you upload, so it doesn’t get forgotten. In the block editor you can also set alt text per image block. Watch out with page builders and sliders: they sometimes manage alt text in their own fields, so check there specifically. How to approach WordPress accessibility overall is covered on the accessibility plugin for WordPress page.

Common mistakes

• Forgetting alt text entirely (the screen reader then often reads the file name).
• Stuffing decorative images with unnecessary descriptions.
• Setting the title instead of the alt.
• Not carrying text that’s inside an image into the alt text.
• Stubbornly prefixing every image with “image of …”.
• Cramming the same keyword into every alt text.

Quick checklist

• Image type identified: informative, decorative, functional or complex?
• Informative images: meaning described briefly and in context
• Decorative images: alt="" (empty, not omitted)
• Functional images: function described, not appearance
• Complex images: short alt + detailed description
• Text inside an image included in the alt text
• No “image of …” phrases, no file names
• Kept short, written for people

How Welcoma helps

Alt text is a content task — it’s created as you maintain your site, and no tool does the writing for you. What tools can do: spot missing alt text. The Welcoma scanner (coming soon) will do exactly that and show you the affected images so you can add them in a targeted way. The honest part stays: the actual writing — accurate and in context — is up to you, and that’s what this guide is about.