Good alt text says what an image means in the place it appears, in as few words as that takes. The same photo can need a full sentence on one page and an empty alt attribute on another. The writer decides by asking what job the image does.
Our plain guide to web accessibility names missing alt text as one of the most common failures and moves on. This post goes deeper on the writing. It covers WCAG 1.1.1, the W3C’s decision tree, image types, logos, charts, length, examples, the WordPress and Drupal fields, and AI tools.
The short version: decide the image’s job first. Informative images get a short description of what matters. Decorative images get an empty alt attribute, never a missing one. Linked images and buttons get the destination or action. Charts get a short alt plus the data in text nearby. AI tools can draft descriptions, but a person who knows the page still has to check every one.
What WCAG 1.1.1 asks for
WCAG success criterion 1.1.1, Non-text Content, is Level A. It says all non-text content "has a text alternative that serves the equivalent purpose," with listed exceptions. The Understanding 1.1.1 page explains each one.
Two exceptions matter on CMS sites. Controls need "a name that describes its purpose." Pure decoration must be "implemented in a way that it can be ignored by assistive technology."
The criterion sets no word or character count. It says short and long text alternatives "can be used as needed." A chart or diagram needs both.
The WebAIM Million 2026 report found 16.2% of home page images had no alt text, down from 18.5% in 2025. Of images that had it, 10.8% had questionable or repetitive text, such as "image," "blank" or a file name. One in four linked images had none.
The W3C alt decision tree, in plain terms
The W3C’s alt decision tree asks five questions in order. Stop at the first one that fits.
- Does the image contain text? If the same text is on the page nearby, or the text is only visual effect, use an empty alt. If the text is not repeated anywhere, put it in the alt.
- Is it in a link or button, and would the control be unclear without it? Describe the destination or action.
- Does it add meaning? For a simple photo or graphic, write a brief description. For a graph or complex image, put the information elsewhere on the page. If nearby text already says the same thing, use an empty alt.
- Is it purely decorative? Use an empty alt.
- None of the above? Go to the full W3C Images Tutorial.
WordPress links its alt text help to this tree. The W3C’s tips page adds a test: imagine reading the page aloud over the phone to someone who needs to understand it.
Informative, decorative and functional images
| Type | What it does | What the alt should hold |
|---|---|---|
| Informative | Shows a concept, person, place or event | The essential information, in a short phrase or sentence |
| Decorative | Adds visual interest only, or repeats nearby text | alt=”” (empty, with no space between the quotes) |
| Functional | Is a link or button, or the only content of one | The destination or action, such as “Search” or “Print this page” |
Informative. The W3C’s informative images page asks for "at least a short description conveying the essential information." Context decides what is essential.
Decorative. The decorative images page is firm on one point: "Leaving out the alt attribute is also not an option." Without it, some screen readers read out the file name. An empty alt tells them to skip the image.
Functional. The text describes what happens, not what the icon looks like. A magnifying-glass button is "Search," not "magnifying glass."
Logos and linked images
An unlinked logo is an image of text. The W3C’s images of text page uses the organization’s name as the alt and says "There’s no need to mention that it is a logo."
A linked logo is a functional image. The W3C’s functional images page uses "W3C home" for a logo that links to the home page. WebAIM’s alternative text article says the name alone is usually enough, because a screen reader user hearing it as a link at the top of the page will know where it goes. Either is fine. "Logo" is the word to drop.
When an image and text share one link, the image usually needs an empty alt. A card with a photo and the headline "Annual Report" in the same link should not announce the title twice.
With no alt and no other text, a linked image leaves the link with no name, and a screen reader may read the URL instead. Check linked images alongside our keyboard accessibility test when you audit links and buttons.
Charts, graphs and infographics
A chart needs two parts, according to the W3C’s complex images page. The first is a short description that identifies the image. The second is a long description: "a textual representation of the essential information."
The W3C’s short alt example names the chart type, what it measures, the period and the subjects. The long part can sit in text after the chart, a figcaption, a data table or a linked page.
Microsoft’s alt text guide adds a caution. A line like "A bar chart showing sales over time" is not useful on its own. Give the finding.
For infographics, publish the content as real text on the page and give the graphic a short alt. For charts inside annual reports, see our accessible PDF checklist.
How long should alt text be?
Some guides quote a fixed character limit for alt text. WCAG 1.1.1 sets none, and neither does the W3C tutorial.
What the sources say instead:
- W3C tips: “the most concise description possible of the image’s purpose.” If it needs more than a short phrase or sentence, use a long description.
- WebAIM: “Typically, only a few words are necessary, though rarely a short sentence or two may be appropriate.”
- Microsoft: no longer than “a sentence or two,” and usually “a few thoughtfully selected words.”
Put the most important information first, as the W3C suggests. Skip "image of" and "picture of," since screen readers already announce an image. Name the medium only when it matters, such as a painting in an art collection. Use normal punctuation so the text reads naturally aloud.
Before and after: alt text examples
These examples are invented for illustration. They are not taken from any real site.
| Image and context | Before | After |
|---|---|---|
| Event photo on a news post about a food drive | IMG_4471.jpg | Volunteers stacking boxes of canned food at the spring food drive |
| Association logo linked to the home page | logo | Example Teachers Association home |
| Heart icon that is the only content of a donate link | red heart icon | Donate |
| Swirl divider between sections | decorative swirl graphic | alt=”” (empty) |
| Membership chart with numbers in a table below | chart | Bar chart of membership by region, 2022 to 2025; data in the table below |
| Event flyer image with date and place, not repeated in text | flyer | The flyer’s full text, or better, that text on the page and a short alt |
Context still rules. On a gallery page where a caption says the same thing, the food drive photo could take an empty alt.
Alt text in WordPress
WordPress has two places to enter alt text, and they behave differently. The Image block documentation says alt text added in the block settings "only applies to the image on that specific page or post." Alt text set in the Media Library "sets the default alt text when you insert the image elsewhere."
So a Media Library fix helps future posts. Check images already placed in older posts separately.
The Image block also has a "Mark as decorative" option. Nothing in the Image block documentation makes alt text required, so enforcing it falls to editor training, a checker plugin or a review step. Our Gutenberg walkthrough covers the block settings panel.
Alt text in Drupal
Drupal core’s image field requires alt text by default. In the Drupal 11 ImageItem source, both the Alt field and "Alt field required" default to on, and the settings form says "Making this field required is recommended." A site builder can turn it off per field, so check older content types.
That default covers image fields, not every image. Images placed through CKEditor 5 follow a separate path. Drupal core issue 3222757, "Make image alt text required or strongly encouraged," covers that path. It is closed as fixed, and its completed steps include a decorative image toggle.
See what Drupal 10 end of life means for your site, and our plain-language post on the Drupal Webform advisories for why patching comes first.
Is AI-generated alt text good enough? (as of October 2026)
AI tools now draft alt text inside common editors. As of October 2026:
- WordPress: the AI plugin (version 1.4.0, 60,000+ active installs) adds a “Generate Alt Text” button to the Image block and bulk generation in the Media Library. Its listing says all AI features need manual triggering.
- Drupal: the AI Image Alt Text module (1.0.3, released October 1, 2026) uses a human-in-the-loop approach by default, so editors “review and edit the AI suggestion before saving.”
- Microsoft 365: Word and PowerPoint generate alt text. Microsoft’s AI alt text FAQ says descriptions “can be incomplete, overly general, or imprecise” and strongly encourages users to review them.
The vendors agree a person has to check the result. A model sees pixels, not the page, the purpose or the people. A reviewer should check:
- Purpose. Is the image decorative, informative or a link? Only the editor knows how it is used.
- Names and events. Who is pictured, at which event. Microsoft says the feature should not be used to identify individuals.
- Destinations. A linked image needs where the link goes, which the image does not show.
- Text and numbers. Transcribed text and chart values must match exactly.
For a large backlog, generation can run as a batch API job with review after. AI drafts save typing, but the editor still makes the call on each image.
Frequently Asked Questions
What is alt text?
The text alternative for an image, stored in the HTML alt attribute. Screen readers read it aloud.
Is alt text required by WCAG?
Yes. WCAG 1.1.1 Non-text Content is Level A. Decorative images are the exception: they must be hidden from assistive technology.
What is the difference between empty alt and missing alt?
Empty alt (alt=””) tells screen readers to skip a decorative image. Missing alt gives no instruction, so some screen readers read the file name instead.
Is there a character limit for alt text?
No. WCAG and the W3C tutorial set none. The W3C, WebAIM and Microsoft all advise a few words or a sentence or two, with a long description for anything bigger.
Should alt text include the word “logo”?
Usually not. Use the organization’s name. If the logo links to the home page, the W3C example adds “home.”
How do I write alt text for a chart?
Give a short alt that names the chart and what it shows. Then put the key data or finding in text near the chart, in a caption, or in a data table.
Does Drupal require alt text?
Drupal core image fields require alt text by default, and a site builder can change that per field. Images in CKEditor 5 have their own alt text prompt and a decorative toggle.
Can we use AI to write alt text for our whole media library?
AI can draft it, but vendors say to review the results. A person should confirm purpose, names, link destinations and any text or numbers.