How to write alt text that actually helps

Alt text is the written alternative a screen reader reads aloud in place of an image. It is required under WCAG 2.1 success criterion 1.1.1 (opens in a new tab) Non-text Content, and it is one of the most common gaps we find. This guide explains how to decide what an image needs, with examples you can adapt.

Start with purpose, not appearance

The rule in WCAG is that a text alternative should serve the same purpose as the image. That is a different question from "what does this image look like?"

Before writing anything, ask: if this image disappeared, what would a reader lose? The answer is your alt text. Sometimes that is a description of what is shown. Sometimes it is the destination of a link. Sometimes it is nothing at all.

Types of images and what they need

Informative images

Images that add information not found in the text. Describe the information, briefly. A photo of your storefront on a "Find us" page might be: "Brick storefront with a green awning, beside the pharmacy."

Functional images

Images that are links or buttons. Describe the action or destination, not the picture. A magnifying glass icon on a search button is "Search", not "Magnifying glass". A logo that links to the home page is the business name followed by "home", not "Logo".

Images of text

If an image contains words that matter, the alt text should include those words. Better still, use real text instead of an image, which is what 1.4.5 Images of Text asks for at Level AA.

Complex images

Charts, diagrams and maps often carry too much for a short phrase. Give the key point in the alt text, then provide the full detail in the page text or a table nearby.

Decorative images

Images that are purely visual, such as background textures, dividers or a stock photo that repeats what the heading already says, should be hidden from screen readers. In HTML, that means an empty alt attribute: alt="". Leaving the attribute out entirely is not the same thing; many screen readers will then read the file name instead.

Examples: a clinic

• Team photo on the "Our team" page, next to each person's name and role. The text already identifies the person. Alt text that gives the person's name again would repeat the heading. A short description of what the photo adds is enough, or alt="" if the photo adds nothing.
• Photo of the accessible entrance on the "Visiting us" page. This is informative and useful: "Ramp entrance on the east side of the building, with an automatic door."
• Icon of a calendar on the "Book online" button. If the button also shows the words "Book online", hide the icon. If the icon is the only content, the alt text is "Book an appointment".
• Diagram showing stretches after physiotherapy. Describe each step in the page text. The alt text can then summarize: "Illustration of the three stretches described below."

Examples: a restaurant

• Hero photo of a plated dish on the home page. If it sets the mood, a short description helps: "Roasted pickerel with wild rice and seasonal vegetables."
• Menu posted as an image. Alt text cannot carry a whole menu. The fix is to publish the menu as text on the page, then treat any accompanying photo as decorative or informative as appropriate.
• Logo in the header linking to the home page. The restaurant's name followed by "home".
• Photos of the patio in a gallery. Distinguish them briefly so people know what each shows: "Patio at dusk with string lights", "Patio seating for large groups".

Examples: a shop

• Product photo on a product page. Describe what a buyer needs to know that is not in the product text: colour, pattern, notable features. "Wool toque in charcoal grey with a cream stripe and a pompom."
• Several photos of the same product. Each should say what it adds: "Back view showing the zipper pocket", "Shown worn, reaching mid-thigh".
• Banner image with the text "Winter boots on sale this week". The alt text is the text in the banner: "Winter boots on sale this week". If it links somewhere, make sure the destination is clear.
• Payment icons in the footer. Either list them in one piece of real text, such as "We accept debit, credit and e-transfer", and hide the icons, or give each icon a short name.

Common mistakes

File names

Alt text such as "IMG_4021.jpg" or "hero-banner-final-v2" tells the listener nothing.

Starting with "image of" or "picture of"

Screen readers already announce that an element is an image. Adding "image of" repeats that. The exception is when the medium matters, such as "Painting of the Forks in winter" or "Screenshot of the booking page".

Keyword stuffing

Alt text like "best Winnipeg dentist family dentist teeth cleaning Winnipeg" is written for search engines, not people. It makes the page harder to use and offers no real benefit. Write for the person listening.

Repeating nearby text

If a caption or heading already says what the image shows, repeating it in the alt text means the listener hears it twice. Either add something new or mark the image as decorative.

Too long, or too vague

Most alt text fits in a short sentence. "Photo" is too vague; a paragraph is usually too much. If more detail is genuinely needed, put it in the page text.

Missing alt on linked images

An image that is the only content of a link must have alt text, or the link has no name. The screen reader user hears "link" and nothing else, which also fails 2.4.4 Link Purpose.

Why tools cannot do this for you

Automated scanners can tell you an image has no alt attribute. They cannot tell you whether the alt text is right. Generated descriptions describe appearance, not purpose, and cannot know which images are decorative. Our method includes reviewing every image in context, and our article on overlays, available in the Insights library, explains why automated fixes fall short more generally.

Talk to us

If your site has many images and you are unsure where to start, we can review them and write or correct the alt text as part of a repair. Book a consultation to discuss your site, or read about our services.