How to write alt text: start from the image's job on the page
Alt text replaces an image for people who can't see it, so write what the image contributes to the page, not an inventory of what's in it. The same photo can need different alt text in different places, and a purely decorative image needs an empty alt="" so screen readers skip it.
Who reads alt text
Screen readers announce alt text in place of the image. Browsers show it when an image fails to load or when someone has images turned off on a slow connection. Search engines and AI assistants use it to understand what an image is about. In every case, the reader gets the text instead of the picture, at the point where the picture sits in the page. That's the test to keep in mind: if the image vanished and the alt text appeared in its place, would the page still make sense and lose nothing important?
Decide the image's job first
Learning how to write alt text is mostly learning to classify images. The W3C's alt decision tree walks through the questions; in practice nearly every image on a small site falls into one of five jobs.
| Job | What to write | Example |
|---|---|---|
| Informative: shows something the text doesn't say | The information it carries, in a sentence | "A skin fade with a sharp line-up, finished with a beard trim" |
| Functional: it's a link or a button | Where it goes or what it does | A logo linking home: "Market Row Bakery, home" |
| Decorative: adds mood but no information | Nothing: alt="" | A texture, a divider, a background flourish |
| Text in an image | The same words as the image | A poster reading "Open late Fridays" |
| Complex: a chart, map or diagram | A short summary, with the detail in nearby text | "Bookings by month, rising from 40 in January to 120 in June; table below" |
Context changes the answer
Take one photo: a baker pulling a tray of sourdough loaves from a wood-fired oven. On different pages it needs different alt text.
- On the About page, next to a paragraph about the founder: "Rosa Bell taking the morning's sourdough out of the oven". The person matters here.
- On a product card for the country sourdough: "Country sourdough loaves, dark crust, fresh from the oven". The product matters.
- As a hero background behind a headline that already says "Bread out of the oven at 7": possibly
alt="", because the headline carries the message and the photo adds atmosphere. - Linked to the bread menu: "See the bread menu", because the job is navigation.
Writing the words
- Lead with what matters. Screen reader users can stop listening at any point. Put the important part first.
- Be specific. "A dog" says little; "A black Labrador after a bath, wrapped in a towel" is what a dog-grooming site actually needs.
- Skip "image of" and "photo of". Screen readers already announce that it's an image. Say "painting" or "screenshot" only when the medium matters.
- Keep it short, but don't truncate meaning. A sentence is usually enough. There's no formal character limit, but long descriptions are tiring; put extended detail in the page text instead.
- Don't repeat the caption. If a visible caption already says it, the alt text can add what the caption doesn't, or be empty if there's nothing to add.
- Don't stuff keywords. Alt text written for search engines rather than people helps neither.
When empty alt is correct
An empty alt attribute, alt="", tells assistive technology to skip the image. It's correct for decoration and for images whose content is already in adjacent text, such as an icon next to the word it illustrates. It isn't the same as leaving alt out: with no attribute at all, many screen readers fall back to reading the file name, which is how listeners end up hearing "IMG underscore 4471 dot JPEG". Every image needs the attribute; only some need words in it.
Be honest about which images are decorative. A product photo on a shop page is never decoration, even if it's pretty. Photos of the team, the premises and the work almost always carry information.
Common mistakes
- Alt text such as "hero image", "banner" or "photo1" that describes the layout slot, not the picture.
- The same generic alt text on every product image.
- Describing a linked image instead of its destination.
- Leaving out text that appears inside an image, such as opening hours on a poster or a price on a menu photo.
- Writing alt text once and never updating it when the photo changes.
What Anticode checks, and what it can't
In Anticode, Sentinel fails a page if an image has no text alternative, and the design gate requires an alt attribute before a page can be published. One difference to know: the design gate accepts an empty alt="" for a decorative image, but Sentinel treats an empty alt as missing, so on Anticode pages give even decorative images a short description. Photos from the curated Unsplash library used by design-engine pages come with written alt text. Photos you upload are used by app builds, where the model sees them; read whatever alt text ends up on the page against the photo itself, and do the same for any image you show through a CMS image field.
What no check can confirm is whether the words are right: whether they describe the actual person or product, fit the image's job on that page, or would let someone who can't see the photo understand what they're missing. That part is still yours, and it's worth reading each one aloud in context. The accessibility guide has a short screen reader test.
Questions people ask
How long should alt text be?
Usually one sentence. There's no hard limit, but long descriptions are tiring to listen to. Put extended detail in the page text.
What alt text should a logo have?
The organisation's name. If the logo links to the home page, add that, such as "Market Row Bakery, home".
Is it OK to leave alt text empty?
Yes, as alt="", for purely decorative images or ones whose content is already in nearby text. Never leave the attribute out entirely.
Does alt text help SEO?
It helps search engines understand images, but write it for people first. Accurate, specific descriptions serve both.