Every image on a web page needs a text alternative, usually written in the alt attribute of the <img> element. Good alt text does the job the image does, for people who cannot see it. This guide follows the image tutorials from the World Wide Web Consortium’s (W3C) Web Accessibility Initiative (WAI) to help you decide what each image needs and write alt text that works.
Why alt text matters
The WAI Images Tutorial states the rule plainly: images must have text alternatives that describe the information or function they represent. It lists who benefits:
- people using screen readers, who hear the text read aloud or read it as Braille;
- people using speech input software, who can focus a linked image or button with one voice command;
- mobile users who turn images off, for example while data roaming;
- search engines, which can index the images.
The tutorial ties this guidance to success criterion 1.1.1, Non-text Content, a Level A requirement of the Web Content Accessibility Guidelines (WCAG).
Step 1: Decide what the image is for
The right alt text depends on the image’s purpose and its context. WAI’s alt decision tree asks a short series of questions, in this order:
- Does the image contain text? If the same text is also on the page as real text, or the text is only a visual effect, use an empty alt. If it is an icon with a function, describe the function. If the text appears nowhere else, put that text in the alt attribute.
- Is it a link or a button that would be hard to understand without the image? Describe where the link goes or what the button does.
- Does it add meaning to the page? For a simple photo or graphic, write a brief description that conveys that meaning. For a graph or other complex image, give the full information elsewhere on the page.
- Is it purely decorative? Use an empty alt.
WAI’s tips page suggests a quick test: imagine reading the page aloud over the phone to someone who needs to understand it. Would you mention the image? If so, what would you say?
Step 2: Describe what matters in informative images
For an image that carries information, the alt text should give at least a short description of the essential information. Context decides what is essential. The tutorial’s example: the exact type of bird in a photo may need only a brief mention on a website about parks, but more detail on a website about birds. On a shop page, the details a buyer needs come first:
<img src="backpack-red.jpg"
alt="Red canvas backpack with two side pockets and a padded strap">
Step 3: Give decorative images an empty alt
WAI’s page on decorative images covers images that add no information, such as borders and spacers, pictures that repeat nearby text, or images used only for atmosphere. Give these a null alt, so screen readers can skip them:
<img src="leaf-divider.png" alt="">
Do not leave the attribute out. WAI warns that without it, some screen readers announce the image file name instead. Where possible, add purely decorative images as Cascading Style Sheets (CSS) background images rather than with <img>.
Step 4: Describe the action for functional images
When an image is a link or a button, WAI’s page on functional images says the alt text should describe the action, not the picture: “Search” rather than “magnifying lens”, “Print this page” rather than “printer”. A logo that links to the home page should say so:
<a href="/">
<img src="logo.png" alt="Example Bookshop home">
</a>
<button type="submit">
<img src="magnifier.svg" alt="Search">
</button>
If the link already contains visible text, such as a logo next to the words “Example Bookshop home”, the logo gets an empty alt so the name is not read out twice.
Common mistakes
- Starting with “image of” or “picture of”. Screen readers already announce that there is an image, so these words add nothing.
- Putting a space in an empty alt. Write
alt=""with nothing between the quotes. With a space, some screen readers still announce the image. - Writing a paragraph. Alt text should be the most concise description possible of the image’s purpose. If you need more than a short phrase or sentence, use one of the long description methods WAI gives for complex images, such as putting the information in the page text.
- Describing a button’s picture. “Magnifying glass” describes the icon, not the action; “Search” tells the user what the button does.
- Putting text in images. Apart from logos, WAI advises avoiding images of text. If you must use one, the alt text should contain the same words.
Before writing alt text, ask what the image is doing on the page: informing, decorating or acting as a control. Then write the shortest text that does the same job, with the most important information first, or leave the alt empty if the image adds nothing. The WAI tutorials have more examples for groups of images, image maps and complex images such as graphs when you need them.


