Building useful websites
How to write alt text: six examples and a quick check
Start with what the reader needs from the image on this page. Then decide whether to describe information, name an action, or leave a deliberate empty alt.
Choose the job before the words
Alt text is the text alternative attached to an HTML image. It helps a reader using a screen reader get information or a function that would otherwise depend on seeing the picture. The same picture can need different text in different places.
For each image, finish this sentence: “On this page, the reader needs this image to…” If your answer is “understand a detail”, describe that detail. If it is “follow a link”, name the destination. If the image adds no information or function, it may be decorative.
The examples below are invented editorial situations, not audits of real websites. They apply to ordinary HTML images; inline SVG, canvas, PDF and social-platform interfaces need their own implementation checks.
1. A photo that helps someone find an entrance
Context: a workshop page explains how to arrive. The photograph shows a blue side door beside a bicycle rack; that identifying detail is not in the surrounding text.
Weak: “Building photo”. Better: “Workshop entrance: the blue side door beside the bicycle rack.” The useful information is how to recognize the entrance, not every object in the frame.
If the page is instead reviewing the building’s architecture, the doorway’s shape or materials may be the relevant detail. Reconsider the alternative whenever you reuse the image.
2. A banner that adds atmosphere
Context: a newsletter signup page has a stock photo of a notebook. It adds visual atmosphere, contains no unique information and is not a link.
Use an explicitly empty attribute: alt="". Empty and missing are different: omitting alt can leave some screen readers announcing the filename. Do not enter the words “decorative image” as the alternative.
A CMS field that looks blank does not prove that the output is correct. Inspect the published image element and check that alt="" is actually present. If the CMS has a decorative-image setting, verify what it produces.
3. A cover image that is the whole link
Context: a report cover is the only content inside a link to a PDF. There is no other accessible name for that link.
Weak: “Green report cover”. Better: “Read the community workshop report (PDF)”. The reader needs to know where activating the link leads.
If the cover and visible text “Community workshop report (PDF)” are inside the same link, and the cover adds nothing else, use alt="" for the cover. Text merely placed nearby, outside the link, does not automatically name an image-only link. Check the link as a whole.
4. A screenshot with a selected setting
Context: instructions show a settings screen with “Weekly summary” selected instead of “Every message”. The choice is the relevant information.
Weak: “Screenshot of settings”. Better: “Notification frequency set to Weekly summary.” Also write the instruction in ordinary page text so people can follow it without interpreting the screenshot.
Describe only the needed visible detail. Do not invent hidden settings or crop away a warning that changes the instruction. If all relevant information is already provided in adjacent text and the screenshot adds nothing, reconsider whether an empty alternative is appropriate.
5. A chart that needs more than one sentence
Context: an invented chart compares workshop bookings: Monday 12, Tuesday 18 and Wednesday 15. Its purpose is to compare daily totals.
A useful short alternative is “Workshop bookings by day; values and comparison below.” Then actually provide the promised text or table beside the chart: Monday 12; Tuesday 18; Wednesday 15. Tuesday has the most bookings, six more than Monday.
For a real chart, preserve units, dates, important relationships and any uncertainty needed to interpret it. A title such as “Bookings” alone loses the result. A long string of every number inside alt is difficult to navigate; keep the detailed equivalent available in the page.
6. A poster with essential text
Context: an image is the only place that says “Repair café — Saturday 14 November, 10:00–13:00 — West Hall”. The event details are invented.
The text alternative must carry those essential details. Better still, publish the event information as ordinary text beside the poster, where readers can select and enlarge it. Reassess the poster’s alternative after that change: an illustration with no remaining unique information may be decorative.
Do not describe only the poster’s colors while losing the date or venue. If the illustration itself matters to the article, its contribution still needs a description.
Use this review card before publishing
Copy one card per image. An unresolved answer is a useful finding; do not fill it with a guessed description.
- Page and image: where is it used, and what is its job here?
- Information already in text: what can a reader learn without the image?
- Chosen treatment: short description / link action or destination / empty alt / short alt plus detailed equivalent.
- Exact wording: write the proposed alternative, or explicitly record alt="".
- Rendered check: inspect the actual image and, for linked images, the accessible name of the whole link.
- Reading check: read the surrounding text and alternative in sequence. Is anything essential missing or unnecessarily repeated?
- Follow-up: ask a reader using their usual assistive technology to try the task when possible; record the issue and correction, not just a pass mark.
What a quick check can and cannot tell you
An automated check can flag a missing alt attribute; it cannot decide whether your description conveys the right information in this context. Inspecting the output and reading the alternatives is a useful first pass, not proof of accessibility.
Keep the alternative focused on the image’s job. A good revision makes the intended information or action clear. Adding unrelated keywords does not help someone use the page.
Try one: which alternative fits?
A map icon is the only content of a link to directions for the workshop. The best option below is “Directions to the workshop”: it names the link destination. “Map icon” describes appearance; an empty alternative would leave this particular link unnamed.
Answers and explanations
- Map icon: That describes the picture, but does not tell the reader where this link goes.
- Directions to the workshop: Yes. The image is doing a link’s job, so name its destination.
- Empty alt: Here there is no other link text or accessible name. Empty alt would lose the destination.