How to Write Alt Text: A Practical Decision Guide with Real Examples

Missing or unhelpful alternative text is one of the most common accessibility failures, and it is also one of the most misunderstood. Many teams think alt text means describing what is in a picture. It doesn’t. Good alt text conveys the information or function an image provides in its context. The same photo can need completely different alt text on two different pages.

As someone who uses a screen reader regularly, I can tell you what bad alt text sounds like: “image”, “IMG_4032.jpg”, “graphic”, or a 60-word description of a stock photo that adds nothing. This guide gives you a simple decision process and examples for each type of image.

Key takeaways

• Alt text should communicate the purpose of the image in its context, not catalogue everything visible.
• Decorative images get an empty alt attribute (alt="") so screen readers skip them. Never leave alt out entirely.
• Images inside links or buttons need alt text that describes the destination or action.
• Complex images like charts need a short alt plus a longer text alternative nearby.
• Don’t start with “image of” or “picture of”; screen readers already announce that it’s an image.

Why alt text matters

WCAG 1.1.1 Non-text Content (Level A) requires that all non-text content has a text alternative that serves the equivalent purpose. Alt text is used by:

• Screen reader users, who hear it in place of the image.
• People with images turned off or on slow connections, who see it as a placeholder.
• Voice control users, for whom alt text is the name of an image link they need to say.
• Search engines, which use it to understand images.

The decision process

Ask these questions in order:

1. Does the image contain text? If the text is meaningful, the alt should include it (or better, use real text instead of an image of text).
2. Is the image inside a link or button? The alt text should describe where the link goes or what the button does.
3. Does the image add information that isn’t already in the surrounding text? Describe that information, briefly.
4. Is the image complex (a chart, diagram, map or infographic)? Give a short alt and provide the full information elsewhere.
5. Is it purely decorative, or does nearby text already say the same thing? Use alt="".

The W3C’s “alt decision tree” follows a similar logic and is worth bookmarking.

Examples by image type

Informative images

These convey a simple piece of information.

Context: A blog post about remote work, with a photo of a person on a video call with a sign language interpreter visible in a corner window.

• Bad: alt="image"
• Bad: alt="A woman with brown hair wearing a blue shirt sitting at a wooden desk with a laptop, a plant and a coffee mug"
• Good: alt="A woman on a video call, with a sign language interpreter shown in a small window"

The good version focuses on what matters to the article: the interpreter. The plant and the mug don’t help.

Functional images (links and buttons)

When an image is the only content of a link or button, its alt text becomes the accessible name of that control. Describe the action or destination.

• A magnifying glass icon on a search button: alt="Search", not alt="Magnifying glass".
• A company logo linking to the home page: alt="Acme home" or simply alt="Acme". Not alt="Acme logo" repeated on every page.
• A printer icon: alt="Print this page".

If the link also contains visible text, the image is usually redundant and should have alt="" so the name isn’t read twice.

Images of text

Real text is almost always better: it scales, reflows and can be restyled by users. WCAG 1.4.5 Images of Text discourages images of text except for logos and cases where a particular presentation is essential.

If you must use one, the alt text should include the words in the image. A promotional banner reading “50% off all courses until Friday” needs exactly that as its alt text.

Decorative images

Purely decorative images, such as background flourishes, dividers, or a generic stock photo that adds nothing to the content, should be hidden from assistive technology:

<img src="divider.svg" alt="">

Two important points:

• alt="" is not the same as no alt attribute. If you leave alt out entirely, many screen readers will read the file name instead, such as “hero-banner-final-v2.png”.
• CSS background images are already ignored by screen readers, which makes CSS a good choice for purely decorative visuals.

Complex images: charts, diagrams and infographics

A one-line alt can’t carry a bar chart with twelve data points. Use a two-part approach:

1. Short alt text that identifies the image and its main takeaway: alt="Bar chart: mobile traffic grew from 40% to 68% of visits between 2021 and 2025".
2. A full text alternative nearby: a data table, a written summary, or a “Chart details” disclosure section underneath.

This helps everyone, not just screen reader users. Many sighted readers prefer the table.

Photos of people

Describe people in ways that are relevant to the content. If the article is about a speaker at a conference, their name and role matter: alt="Priya Shah presenting on accessible design systems at the conference keynote". Avoid guessing at characteristics such as ethnicity, age or disability unless they are relevant and known.

Screenshots in tutorials

For step-by-step guides, describe what the reader needs to find, not every pixel: alt="WordPress block settings panel with the Alt text field highlighted". If the screenshot shows code or error text the reader needs, put that text in the article as real text too.

How long should alt text be?

There is no strict character limit in WCAG, but concise alt text is easier to listen to. A useful guide is one or two short sentences. If you find yourself writing a paragraph, the image is probably complex and needs a long description elsewhere.

Common mistakes to avoid

• Starting with “Image of”, “Picture of” or “Graphic of”. The screen reader already says “image” or “graphic”.
• Using the file name, or SEO keyword lists, as alt text.
• Repeating the caption word for word in the alt. Screen reader users then hear it twice.
• Leaving important information only in the image, such as prices, dates or instructions.
• Identical alt text on every product image (“product image”).
• Trusting AI-generated alt text without reviewing it. AI tools are improving, but they don’t know why the image is on your page.

Alt text in WordPress and other CMSs

Most content management systems have an alt text field in the media library and in the image block settings. A few tips:

• Alt text set in the media library may be reused on every page where the image appears. Review it in context, because the right alt text can change from page to page.
• Featured images displayed next to a post title are often decorative or redundant, since the title already says what the post is about.
• Make alt text part of your publishing checklist, not an afterthought.

Conclusion

Writing good alt text is a content skill, not a technical one. Ask what the image is doing on the page, then write the shortest text that does the same job. Mark decorative images as decorative, give charts a proper text alternative, and review anything a tool generates for you. Your screen reader users, and your search rankings, will thank you.

Further reading

• Screen Reader Testing for Beginners: NVDA and VoiceOver
• How AI Is Transforming Industries: 7 Applications and What They Mean for Accessibility
• W3C WAI: Images Tutorial
• W3C WAI: An alt Decision Tree