How to write alt text: the W3C decision tree, with examples
There is no single right length for alt text, because the right alt text depends on what the image does on the page. The W3C's decision tree provides a starting point for common image uses.
In short
Ask what the image does. Decorative: use an empty alt (alt=""). A link or button: describe the action or destination. Text in an image: repeat the text. Informative: a brief description that conveys the meaning. A chart or diagram: put the information in the page as well.
Alt text is the text alternative for an image: what a screen reader announces, and what shows if the image fails to load. The W3C's alt decision tree starts from one question: what is this image for?
The five cases
| The image | Alt text | Example |
|---|---|---|
| Decorative: adds nothing a reader would miss | Empty: alt="" | A background swirl next to a heading |
| Functional: a link or button | The destination or action, not the picture | A magnifying-glass icon button: alt="Search" |
| Image of text | The text in the image | A logo with words: the words |
| Informative: conveys a simple idea | A brief description that conveys that meaning | A photo showing a product in use: what it shows that matters here |
| Complex: a chart, graph or diagram | A short alt, with the full information elsewhere on the page | A sales chart: a summary in the alt, the data in a table or text nearby |
These cases are a starting point; the W3C explicitly says the decision tree does not cover every image. For an unclear use, consult its full Images Tutorial. The W3C adds another case: if an image repeats information already in nearby text, it is treated like a decorative image and given an empty alt.
Writing it
- Say what matters in context, not everything visible. The same photo might need different alt text on a product page and in a news story.
- Don't start with "image of" or "picture of": screen readers already announce it is an image.
- Keep it short. If it needs more than a sentence or two, it is probably a complex image and needs a longer description on the page.
- Never leave the attribute out. A missing alt can lead some screen readers to read the file name; an empty alt tells them to skip a decorative image.
Worked examples
The same principles, applied to images a typical site actually uses:
| Image on the page | Good alt text | Why |
|---|---|---|
| Company logo linking to the home page | "Ideal UI home" | It is a link, so name the destination |
| Headshot next to the author's name in a byline | alt="" | The name beside it already says who it is |
| Screenshot showing where the Export button sits | "The Export button at the top right of the report toolbar" | The location is the information the reader needs |
| A bar chart of monthly sign-ups | "Sign-ups rose each month from January to June; full figures in the table below" | Summarise the point; put the data in text |
| Social media icons in the footer | "Instagram", "LinkedIn" | Each is a link; name where it goes |
| A photo of a team at a whiteboard, beside a paragraph about workshops | "Five people sorting sticky notes into groups on a whiteboard" | Short, and it matches why the photo is there |
Alt text in design files
Alt text is easiest to get right when it is written with the content, not added by a developer at the end. Add an alt text field next to every image in your design or content specification, and mark decorative images as decorative explicitly so nobody fills them in by guesswork. Review alt text the way you review headings and button labels: as interface copy.
Alt text and captions
A caption is visible text shown with the image; alt text is its text alternative. They can serve different purposes. A caption might name a photographer or explain the scene, while the alt conveys the information needed in this page's context. Repeating the full caption in the alt can make a screen-reader visit unnecessarily repetitive.
AI-written alt text
Tools can now draft alt text automatically, and they are good at describing what is in a picture. What they cannot know is why the image is on the page, which is the question the decision tree turns on. Treat AI drafts as a starting point, and decide the purpose yourself.
Common questions
Should decorative images have alt text?
They should have an empty alt attribute (alt=""), so screen readers skip them.
How long should alt text be?
As short as conveys the image's purpose, usually a phrase or a sentence. Complex images need a fuller description elsewhere on the page.
Should a logo have alt text?
Yes. If it links to the home page, the alt text should name the destination, such as the site name followed by home; if it is not a link, the company name is enough.
Sources
Read next
- Colour contrast checker (WCAG 2.2)Check any two colours against WCAG 2.2: the ratio, and whether it passes for body text, large text and interface parts such as icons and input borders.
- Nielsen's 10 usability heuristics, with what each looks like on a screenTen rules of thumb, first published in 1990 and refined in 1994, that still catch most of what goes wrong on a screen.
- Design systems: components, patterns and a shared languageA design system lets a team stop redrawing the same button. It is the components, the rules for using them, and the shared names for both.