A11yDen

Home / Guides

How to write alt text

Alt text is the text alternative a screen reader speaks when it reaches an image, and the text a browser shows when the image cannot load. WCAG's rule for it — Success Criterion 1.1.1, Non-text Content, Level A — is one sentence long: all non-text content presented to the user has a text alternative that serves the equivalent purpose, with a short list of exceptions. Writing good alt text means answering one question honestly: what would a sighted reader lose if this image disappeared?

Start with the decision, not the description

Before writing anything, decide which of these the image is:

Context decides the words

The same image legitimately takes different alt text in different places. A photograph of a red double-decker bus on a tourism page might be "A red double-decker bus crossing Westminster Bridge"; the identical photograph on a page about a bus-service timetable change might be decorative, because the timetable text carries the news. Alt text serves the purpose of the image on this page, which is why no generator that sees only the picture can finish the job for you.

Worked examples

SituationWeak altBetter alt
Product photoimage123.jpg"Trail running shoe, side view, orange with black sole"
Logo linking home"logo""A11yDen — home"
Chart"chart""Bar chart: monthly sales rose from 40 units in January to 65 in June. Full data in the table below."
Decorative flourish"abstract blue swirls decoration"alt="" — silence is the correct reading

The mistakes that actually fail people

What a checker can and cannot tell you

An automated checker can settle the mechanical questions completely: which images have no alt attribute, which have file names as alt, which repeat trigger words, and which decorative-looking images were given long text anyway. It cannot judge whether your alt serves the equivalent purpose — that is a human decision, and it is the decision SC 1.1.1 actually tests. Run the checker first, then read every remaining alt aloud in context and ask whether the page still makes sense with your eyes closed.

Put it into practice

Sources and checking

WCAG facts in this guide follow the official W3C WCAG 2.2 Recommendation and its Understanding documents; any other fact is attributed to its source in the text. Facts checked November 16, 2026. Direct links to the sources are in the references below.

References

More guides