Web Design

How to Write Alt Text: Informative, Decorative and Functional Images on CMS Sites

A black-and-white film photograph of a plain wooden spindle-back chair on a bare plank floor, with low afternoon sun from the left casting its long, crisp shadow across a whitewashed plaster wall, the shadow keeping the chair's shape and dropping its detail, a visual for how good alt text gives the essential meaning of an image in a few words

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.

  1. 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.
  2. Is it in a link or button, and would the control be unclear without it? Describe the destination or action.
  3. 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.
  4. Is it purely decorative? Use an empty alt.
  5. 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.

Drupal 10 reaches end of life on December 9, 2026. Fold alt text cleanup into the Drupal 11 move so editors fix content once.

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.

Digital Matters

Web Design Desk