How to Write Alt Text: A Practical Decision Guide
How do you write useful alt text?
Write alt text by asking what purpose the image serves on this page, then provide the text a person needs when the image is unavailable. Describe meaningful information briefly, name the action of an image used as a control, use an empty alt attribute for decoration, and put a chart's full data or conclusions in nearby page text. Context decides the answer; the same photo may need different alt text on two pages.
Alt text is less a caption contest than a small editorial decision. Its job is equivalent purpose, not a perfect inventory of pixels.
Start with purpose, not appearance
WCAG 2.2 Success Criterion 1.1.1 requires non-text content to have a text alternative that serves an equivalent purpose, with defined exceptions. That wording is useful because it shifts the question from “What can I see?” to “What does this image do here?”
Before writing, read the paragraph, heading, link, or control around the image. Then sort it into one of four jobs:
| Image job | Useful treatment |
|---|---|
| Adds simple information | Briefly convey the information that matters in context |
| Performs an action | Name the action or destination |
| Repeats nearby text or decorates | Use an empty alt attribute: alt="" |
| Carries complex information | Add a short identifier plus the essential data or explanation in page text |
The W3C Web Accessibility Initiative's alt decision tree follows this same sequence. It is a better starting point than an arbitrary character limit.
Describe what changes the reader's understanding
For an informative photograph, include the details that support the surrounding point. On a page explaining curb access, “Person using a wheelchair beside a curb ramp blocked by a delivery van” conveys more purpose than “Street scene.” On a staff page, the same photograph might need a person's name and role instead.
Avoid adding “image of” or “photo of” when that fact adds nothing. Screen-reading software can already announce an image. Keep the medium when it matters, such as “Watercolor map” or “Screenshot of the account menu.”
Do not infer identity, emotion, disability, gender, ethnicity, or motive from appearance. Name what the image reliably shows and what the page needs. The adjective cupboard can remain mostly closed.
Write the action for linked images and controls
When an image is the only content inside a link or button, its text alternative should communicate the destination or action. A magnifying-glass button needs “Search,” not “Magnifying glass.” A logo linked to the home page usually needs the organization name, because that tells the user where the link goes.
Check the result alongside any visible label. Repeating both can make a screen reader announce the same idea twice. The W3C decision tree specifically directs authors to communicate the function when an image makes a link or button understandable.
Leave decorative images silent
A divider flourish, background texture, or stock photograph that contributes no information should use alt="". The empty value tells assistive technology the image can be skipped. Omitting the attribute is different: user agents may announce the file name or other unhelpful information.
An image is not decorative merely because the design team calls it decoration. If the surrounding copy relies on it, or it contains text not repeated elsewhere, it carries meaning and needs an alternative.
Give charts a short label and a real explanation
Charts, maps, diagrams, and organizational trees often contain too much information for one sentence. W3C's complex-images tutorial calls for a two-part alternative: a short description that identifies the image and a longer textual representation of the essential information.
For a chart, the nearby explanation might include the values in a table, the trend, relevant comparisons, and any qualifications needed to interpret it. The short alt text can identify the chart and point toward that explanation. Do not squeeze a spreadsheet into one breath.
This also makes the conclusion available to people using small screens, text-only views, translation tools, or unreliable connections.
Test in context before publishing
Review the page with images hidden or inspect each image's accessible name in browser tools. Ask:
- Does the remaining text preserve the image's purpose?
- Does each image control announce its action?
- Are decorative and redundant images skipped?
- Can a reader get the essential information from every complex image?
- Does the wording avoid guesses the image cannot support?
Automated checks can find missing attributes. Human review must decide whether the words are useful. Keep that review in the wider inclusive web checklist collection. The accessible events section applies the same principle to participant materials. If the image appears on an event page, carry the same discipline into the accessible event checklist, where maps, speaker photos, schedules, and registration controls all need context.
Sources
- W3C: Web Content Accessibility Guidelines 2.2, Success Criterion 1.1.1 — current W3C Recommendation; establishes the requirement for text alternatives that serve an equivalent purpose and the defined exceptions.
- W3C Web Accessibility Initiative: An alt Decision Tree — updated May 13, 2024; supports the context-based choices for informative, functional, redundant, decorative, and complex images.
- W3C Web Accessibility Initiative: Complex Images — supports the short-description plus long-description approach for charts, maps, and diagrams.
An independent publication. Not affiliated with any prior owner of this domain.