How to Add Alt Text to Images for Accessibility
Learn when to write descriptive alt text, when to use alt="", and how to handle links, charts, and images containing text.
To add alt text, give each HTML <img> an alt attribute that fits the image’s purpose in context. Describe the essential information in an informative image; use alt="" for decorative or redundant images; name the action or destination when an image is the only content in a link or button. For a complex chart or diagram, give it a short identifying alt text and provide its important details in nearby text, such as a description or data table.
The right alternative depends on what the image contributes to the page, not just what it looks like. The W3C WAI Images Tutorial organizes guidance by image purpose.
1. Decide what the image does in context
Before writing, ask what a reader would lose if the image were unavailable. Check the surrounding copy, link text, and nearby captions too. The same image can need different alt text on different pages because its purpose changes with context.
- Does it convey information? State the essential meaning, instruction, or takeaway.
- Does it provide only decoration or repeat nearby information? Use an empty value:
alt="". - Is the image the only content in a link or button? Name the action or destination.
- Does it contain substantial information, such as a chart? Identify it briefly in alt text, then provide the full equivalent in nearby content.
- Does it contain important text? Include words that are not available elsewhere, unless the image is redundant with adjacent content.
The W3C alt decision tree is a useful second check when a case is not obvious.
2. Write concise alt text for informative images
Describe the information the image adds, rather than listing every visible object or visual detail. A useful alternative lets someone understand the point without seeing the image. For example, if an illustration teaches how to open a bottle, describe the instruction rather than merely naming a cap and bottle. See the W3C guidance on informative images.
<img src="cap.png" alt="Push the cap down and turn it counter-clockwise">Use wording specific to the actual image and page. Avoid adding details that do not help convey its meaning. There is no universal phrase that makes an alternative correct in every context; judge whether it communicates the image’s essential contribution.
3. Mark decorative and redundant images with an empty value
When an image adds no information or repeats information already available in nearby text, use alt="". This tells assistive technology it can skip the image.
<img src="border.png" alt="">Do not omit the attribute to mean “decorative.” A missing alt is different from an empty one; some screen readers may announce the image’s file name when the attribute is absent. The W3C explains this distinction in its guidance on decorative images.
4. Describe an image’s action or destination
If an image is the only content in a link or button, write alt text that communicates what activating it does or where it goes. A printer icon that prints a page could use “Print this page”; a magnifying-glass control that starts a search could use “Search.” The alternative should name the function, not just the icon’s appearance.
<a href="/print">
<img src="print.png" alt="Print this page">
</a>If visible text in the same link already names the action or destination, the image may be redundant; in that case an empty alt value can prevent the same wording from being announced twice. Check the whole link, not only the image. See the W3C guidance on functional images.
5. Handle complex charts, maps, and diagrams
A short alt value is not a substitute for the detail in a dense chart or diagram. Identify the image briefly, then give readers access to the important information in a longer equivalent. That can be a nearby explanation, a structured description grouped with the figure, a data table, or a clearly identified link to a description.
<figure>
<img src="chart.png" alt="Bar chart of monthly visitors by site; detailed data follows">
<figcaption>
<p>The table below gives the monthly visitor counts and highlights the rise in visits during the final quarter.</p>
<table>
<caption>Monthly visitors by site</caption>
<thead>
<tr><th scope="col">Month</th><th scope="col">Site A</th><th scope="col">Site B</th></tr>
</thead>
<tbody>
<tr><th scope="row">January</th><td>120</td><td>95</td></tr>
<tr><th scope="row">February</th><td>145</td><td>110</td></tr>
</tbody>
</table>
</figcaption>
</figure>Replace the sample explanation and values with the chart’s actual content. The longer equivalent needs to convey the material details and relationships that the visual presents, not just repeat its title. The W3C discusses options for complex images.
6. Include important text that appears inside an image
If an image contains words that matter and those words do not appear elsewhere, include them in the text alternative. If the same words are already present in adjacent content and the image adds nothing else, an empty value may avoid repetition. Treat meaningful text in an image as content, not as incidental visual detail.
7. Add alt text in HTML and content editors
In HTML
Write the alternative in the alt attribute of the image element. Include the attribute on each content image, even when its value should be empty.
<img src="team.jpg" alt="Two engineers reviewing a printed site plan">
<img src="divider.png" alt="">In a CMS or editor
Open the image’s editing controls and enter the alternative text in the field for alternative text or image description. Interface names and workflows vary by platform, so check that editor’s documentation if the field is unclear. For a decorative image, set its alternative text to empty using the editor’s supported control; do not assume that leaving the field unset produces an empty alt attribute in the published HTML.
In code review
Review the rendered HTML as well as the source component or content record. Confirm that informative images have a meaningful value, decorative images have alt="", and image-only controls expose their purpose. If a component accepts alt text as a prop, verify that the prop reaches the rendered <img>.
8. Common mistakes and fixes
| Problem | Why it causes trouble | Fix |
|---|---|---|
Leaving off alt |
Missing and empty alternatives are not equivalent; a screen reader may announce a file name. | Add a useful value or explicitly use alt="" for a decorative or redundant image. |
| Describing a decorative image | It adds narration without useful information. | Use an empty value when the image contributes nothing beyond the surrounding content. |
| Naming an icon instead of its function | “Printer” does not say what activating the control does. | Use a phrase such as “Print this page” when that is the action. |
| Repeating the adjacent link label | The same purpose can be announced twice. | If the image adds nothing to the visible link text, use an empty alt value for the image. |
| Giving a chart only a title | A title alone may not convey its key values, trend, or relationship. | Provide a short identifier plus an accessible detailed equivalent nearby. |
| Using the filename as the description | Filenames rarely explain the image’s meaning in context. | Write the intended alternative; do not rely on the file name. |
| Putting important text only in the image | Readers may not have access to that visual text as page content. | Include the important words in alt text or make them available in adjacent content. |
Assuming a blank editor field publishes alt="" |
An editor may omit the attribute or handle an unset value differently. | Inspect the rendered HTML and use the platform’s explicit decorative-image setting when available. |
Or skip the browser setup
If you are capturing a page to review its rendered images and surrounding context, ScreenshotNeo provides a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. Here is the one-call example; see the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com \
-o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and whether the request was billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and capture 1,000 screenshots a month with no card.
9. Check the result
- Can someone understand the information the image adds without seeing it?
- Does a decorative or redundant image use
alt=""rather than a missing attribute? - Does an image-only link or button name its action or destination?
- Does a complex image have a longer equivalent that provides its meaningful detail?
- Is important text from the image available in the alternative or nearby content?
- Does the published HTML contain the intended value?
W3C’s Image Alt Text easy checks can help with a quick review. WCAG 2.2 Success Criterion 1.1.1 concerns non-text content. W3C’s H37 technique describes using a short text alternative with the alt attribute on img elements, but techniques are examples, not mandatory methods; meeting the criterion is the requirement, not copying one particular technique or phrase. See W3C Technique H37.
Frequently asked questions
Should every image have an alt attribute?
For an HTML <img>, provide an alt attribute. Its value can be descriptive text or empty when the image is decorative or redundant.
Is alt="" the same as no alt attribute?
No. An empty value marks an image to be skipped; a missing attribute may cause assistive technology to announce other information, such as the filename.
Does WCAG require a specific wording or character limit?
The cited W3C guidance does not prescribe one universal phrase. Write an alternative that conveys the image’s essential purpose in its page context, and provide a longer equivalent when a short value cannot carry the necessary detail.
Should I start alt text with “Image of”?
Usually the surrounding technology already identifies the content as an image. Use the limited text to convey its meaning or function unless identifying it as an image adds useful context.
Can automated checks decide whether alt text is good?
A check can help find images with missing attributes, but deciding whether the wording communicates the right information requires understanding the image and its context.
For further guidance, consult the W3C WAI Images Tutorial and its pages on decorative, informative, functional, and complex images.
