October 29, 2026

How to write alt text: the W3C decision tree, case by case

Alt text is the text alternative that stands in for an image for people who cannot see it: it can be read aloud by synthesized speech, displayed as text or converted to braille. For an HTML image, you write it in the alt attribute of the img element. The hard part is not where to put it but what to put in it: a description, the purpose of a link, the text shown in the image, or nothing at all (an empty alt). To answer that, the W3C offers a decision tree of five questions, asked in order. This guide walks you through it step by step, adds examples from the W3C's Understanding 1.1.1 page, and covers the mistakes the W3C lists as failures of WCAG success criterion 1.1.1 Non-text Content in its supporting documentation.

What WCAG requires from alt text

Success criterion 1.1.1 Non-text Content is a Level A requirement. It states that all non-text content presented to the user has a text alternative that serves the equivalent purpose, except in a few specific situations. The W3C sums up its goal simply: non-text information is available to more people.

Why text? Because it can be rendered through any sensory modality: visual, auditory or tactile. Someone who cannot see a photo can have its text alternative read aloud with synthesized speech; someone who is deaf-blind can read that text in braille. The W3C adds that text alternatives may also help some people who have difficulty understanding the meaning of photographs, drawings, graphs or animations, and that they make non-text content searchable and reusable.

The criterion sets out special cases you may meet on a website:

Controls and input (for example an image used as a submit button): they need a name that describes their purpose.
Time-based media, tests or exercises that would be invalid in text, and content primarily intended to create a specific sensory experience: the text alternative at least provides a descriptive identification.
CAPTCHA: the text alternative identifies and describes its purpose, and alternative forms of CAPTCHA using different senses are provided to accommodate different disabilities.
Pure decoration, visual formatting only, or content not presented to users: it must be implemented so that assistive technology can ignore it.

How to write alt text with the W3C decision tree

The W3C decision tree describes how to use the alt attribute of the img element in various situations. Work through the questions in order: for the first four, a "yes" gives you your instruction; a "no" sends you to the next question.

1. Does the image contain text? If the same text is also present as real text nearby, or is only shown for visual effect: empty alt (decorative image). If the text has a specific function, such as an icon: use alt to convey that function (functional image). If the text in the image is not present anywhere else: put that text in the alt (image of text).
2. Is the image used in a link or a button, and would it be hard or impossible to understand what the link or button does without it? If yes: use alt to convey the link's destination or the action taken (functional image).
3. Does the image contribute meaning to the page or context? If it is a simple graphic or photograph: a brief description that conveys that meaning (informative image). If it is a graph or complex piece of information: include that information elsewhere on the page (complex image). If it shows content redundant with real text nearby: empty alt.
4. Is the image purely decorative, or not intended for users? If yes: empty alt (decorative image).
5. Is your case not listed, or are you unsure what alt text to write? The tree does not cover every case: refer to the full W3C Images Tutorial.

Informative, functional and complex images: alt text examples

The examples on the Understanding 1.1.1 page show that good alt text depends on context, not only on what the image depicts.

Same image, two alternatives. An image of the world links to the International Travel section of a travel site, so its text alternative is "International Travel". The same image, used as a link on a university website, has the alternative "International Campuses". When the image is what makes a link understandable, the destination is what matters. Likewise, a thumbnail of a newspaper's front page that links to the Smallville Times home page simply has the alternative "Smallville Times".

Same photo, two levels of detail. In a news story about an international summit, a photo of two leaders shaking hands has the alternative "President X of Country X shakes hands with Prime Minister Y of country Y." On a site about intricate diplomatic relationships, the same photo gets a more precise first alternative that adds the date ("… on January 2, 2009"), plus an additional description of the room, the leaders' facial expressions and the other people present. That description might sit on the same page or in a separate file associated with the image through a link or another standard programmatic mechanism.

A data chart. For a bar chart comparing widget sales in June, July and August, the short label says "Figure one - Sales in June, July and August." A longer description identifies the type of chart and gives a high-level summary of the data, trends and implications comparable to those available from the chart; where possible and practical, the actual data is provided in a table.

An interactive image. For a clickable building floor plan that leads to a page about each room, the short text alternative describes the image and its interactive purpose: "Building floor plan. Select a room for more information."

Decorative images: when to use an empty alt

Some non-text content is not meant to be seen or understood by the user. The W3C gives as examples transparent images used to move text over on a page, an invisible image used to track usage statistics, and a decorative swirl in a corner that conveys no information. These images should not be described, but they should not be left unmarked either.

Putting alternative text on such items just distracts screen reader users from the content. Not marking them at all, though, leaves those users guessing what they may have missed, even though they missed nothing. The criterion therefore requires implementing them so that assistive technology can ignore them; techniques the W3C lists for this case include an empty alt and no title attribute on the img element, or including the decorative image through CSS. Be careful: information must never be conveyed exclusively through a CSS background image; that is a documented failure of the criterion (F3).

Alt text mistakes documented as failures

On its Understanding 1.1.1 page, the W3C lists failures of the criterion. These are the bad examples to look for when you audit your images:

Omitting the alt attribute or text alternative on img elements, area elements and input elements of type image (F65).
Using text alternatives that are not alternatives, such as filenames or placeholder text (F30).
Giving a non-null alt, such as alt="spacer" or alt="image", to an image that should be ignored (F39).
Not marking up decorative images in HTML in a way that lets assistive technology ignore them (F38).
Conveying information exclusively through CSS background images (F3).
Leaving out of the text alternative information conveyed by color differences in the image (F13).
Not updating the text alternative when the non-text content changes (F20).
Using ASCII art, or text look-alikes to represent text, without a text alternative (F72, F71).
Providing a long description that does not serve the same purpose, or does not present the same information, as the image (F67).

How to check the alt text on your pages

For each image on a page, apply the decision tree, then compare the result with the failures above. In practice: find images with no alt attribute, those whose alt is a filename, and decorative images that have been described; then review images inside links and buttons and ask whether the alternative states the destination or the action. For charts, check that a long description exists, either on the page or in another location reached through a link right next to the image, and, where possible, a table of the data.

The W3C also notes that text alternatives should match the human language of the original content, normally the default language of the page. You can start with a free test of your site on Conformly, then turn on continuous monitoring to catch new images published without a text alternative.

Frequently asked questions

How do you write good alt text for an image?

Follow the order of the W3C decision tree. If the image contains text that is not present elsewhere, use that text. If it sits in a link or button and nobody could tell what the link or button does without it, describe the destination or action. If it contributes meaning and is a simple graphic or photo, give a brief description that conveys that meaning in context; if it is a graph or complex information, provide that information elsewhere on the page; if it only repeats nearby real text, leave the alt empty. If it is purely decorative, leave the alt empty too.

When should alt text be empty?

According to the W3C decision tree: when the text in the image is also present as real text nearby, when that text is only shown for visual effect, when the image is redundant with nearby real text, and when the image is purely decorative or not intended for users.

Can I remove the alt attribute from a decorative image?

No. Omitting the alt attribute on an img element is a documented failure of success criterion 1.1.1 (F65). A decorative image must be marked so assistive technology ignores it, for example with an empty alt and no title attribute, or be included through CSS.

What alt text should a chart or complex image have?

A short alternative that identifies the chart, plus a long description that identifies the type of chart and summarizes the data, trends and implications in a way comparable to the chart, placed elsewhere on the page or in another location linked right next to the image. Where possible, provide the data in a table.

Can the file name be used as alt text?

No. Using a filename or placeholder text as the alternative is a documented failure of success criterion 1.1.1 (F30), as is an alt such as "image" or "spacer" on an image that should be ignored (F39).

Sources

This article relies on the official sources listed at the end of the page.