How to Write Alt Text for Images: A Practical Decision Guide

Alt text describes purpose, not pixels

The same photograph can require different alternatives on different pages. A photo of a crowded train may document rush-hour conditions in a transport report, introduce a story about commuting, or merely fill space behind a heading. Its visual pixels are unchanged, but its purpose is different.

Before writing, ask what a reader would miss if the image were unavailable. The answer—not the file name, search keyword, or generic object inventory—is the basis of the alternative.

What WCAG requires from non-text content

WCAG 2.2 Success Criterion 1.1.1, Non-text Content, is Level A. It requires non-text content presented to users to have a text alternative that serves the equivalent purpose, with defined treatments for controls, time-based media, tests, sensory experiences, CAPTCHA, and decoration.

The goal is not to make every visual experience identical in words. It is to preserve the information or function so it can be presented in speech, braille, enlarged text, simplified form, or another modality.

Use a context-first decision process

Do not begin by asking how many characters to write. Begin with the role. A short sequence of questions normally identifies the correct treatment.

When the answer remains unclear, consult the W3C image decision tree and review the editorial intention. An automated image-recognition description cannot know why the author included the image.

Describe the meaning of informative images

An informative image conveys a simple fact, concept, impression, or relevant appearance that can usually be expressed in a short phrase or sentence. Include the detail needed to understand the surrounding content and leave out visual details that do not affect that understanding.

Usually omit phrases such as “image of” or “picture of”; assistive technology already identifies an img as an image. Include the medium only when it matters—for example, “watercolor illustration” in an art review or “satellite image” in a weather analysis.

Use empty alt text for decorative and redundant images

A decorative image adds styling or atmosphere but contributes no information required to understand the page. An image can also be redundant when nearby real text already communicates everything it contributes. In both cases, announcing it creates noise rather than value.

<img src="leaf-divider.svg"
     alt="Green decorative leaf divider">

<img src="leaf-divider.svg"
     alt="">

The empty value is intentional: alt="". It tells assistive technology that the image can be skipped. Omitting the attribute is different; some screen readers may announce the file name or URL, leaving users to wonder whether information is missing.

Purely decorative imagery can also be implemented through CSS when it conveys no information. Never place essential content only in a CSS background image, because it has no native text-alternative mechanism.

Name functional images by the action or destination

When an image is the only content of a link or button, the alternative becomes the control’s accessible name. Describe what activation does, not the icon’s shape.

<a href="/search/">
  <img src="magnifier.svg"
       alt="Magnifying glass">
</a>

<a href="/search/">
  <img src="magnifier.svg"
       alt="Search the site">
</a>

If visible link text already names the destination, the accompanying icon often uses alt="" to avoid repetition. A company logo linked to the home page usually needs an accessible name identifying the organization or home destination. An image input uses its alternative to name the submitted action.

Read How to Write Accessible Link Text for a fuller treatment of image links, repeated destinations, and accessible names.

Preserve words shown only inside an image

If an image contains meaningful words that are not available as real text nearby, the alternative should include those words. For a logo, the brand name is normally the important text. For a poster or event graphic, a short alt value may not be enough to reproduce dates, venue, price, and registration details; provide the complete essential information as HTML near the image.

Avoid images of text when ordinary text can achieve the presentation. Real text adapts better to zoom, custom colors, translation, responsive layouts, and user style changes.

Give complex images both an identity and an equivalent

Charts, maps, process diagrams, infographics, and technical illustrations often contain more information than a concise alt attribute can communicate. Use short alternative text to identify the graphic and indicate where the complete explanation is available. Then provide the meaningful data, relationships, and conclusion in nearby prose, a data table, or a clearly linked description.

<figure>
  <img src="quarterly-sales.png"
       alt="Quarterly sales chart; data table follows">
  <figcaption>Sales rose in each quarter of 2025.</figcaption>
</figure>
<table>
  <!-- Equivalent quarterly values and headers -->
</table>

The long equivalent should serve the same purpose as the graphic. For a trend chart, include the trend, significant comparisons, anomalies, and exact values needed for the task—not every decorative grid line. For a process diagram, preserve sequence and decision branches. For a map, provide the locations or directions a user needs.

Handle groups, galleries, and repeated thumbnails as one experience

Several images can convey one combined idea. A star-rating graphic built from five separate images should not announce “star” five times; one alternative can communicate the overall rating while the remaining images are ignored. A composite diagram sliced into multiple files similarly needs one coherent equivalent.

In a gallery, each image may be informative and need a distinct description. Repeated thumbnails linked to larger versions need names that distinguish the destination. If the caption already identifies each photo and sits inside the same linked structure, avoid duplicating identical words unnecessarily.

Write concise alternatives without imposing a character myth

WCAG does not set a universal alt-text character limit. Keep a short alternative as concise as the purpose permits, but do not delete essential information to meet an arbitrary number. When the equivalent becomes detailed, move that detail into visible text or a longer description rather than forcing a paragraph into the attribute.

A good editing test is to read the page with image announcements substituted by their alternatives. Remove:

• Redundant “image of” openings unless the medium itself matters.
• File names, camera settings, stock-photo keywords, and search phrases unrelated to purpose.
• Unverified interpretations or demographic assumptions.
• Information already stated immediately nearby when repetition adds no value.
• Visual detail that does not change the reader’s understanding or action.

Keep the language natural and match the language of the surrounding page. Punctuation can improve speech output, but do not turn the attribute into a keyword list.

Choose alt text in the page, not only the WordPress Media Library

WordPress provides an Alt Text field for media, but the appropriate alternative depends on each use. A reusable photo may be informative in an article, decorative in a hero, and functional when linked as a thumbnail. One attachment-level phrase cannot make every context correct.

1. Identify the image’s role in this block.Decide whether it adds information, repeats text, performs an action, or is purely decorative.
2. Inspect the generated HTML.Confirm that the final img has the intended attribute and that the theme has not changed or omitted it.
3. Review featured images and cards.The theme may link them, repeat the post title, or use them decoratively; each pattern needs a deliberate name.
4. Check captions separately.Determine whether the caption identifies, credits, interprets, or fully describes the image.
5. Test responsive sources.srcset variants of the same image normally share one purpose, while art-directed replacements must preserve equivalent meaning.
6. Review lazy-loaded and dynamic media.Confirm the alternative exists when the image is inserted, swapped, filtered, or opened in a gallery.
7. Read the complete page linearly.Listen for repetition, vague file names, missing destinations, and descriptions that arrive in the wrong order.

Use the DOFIW Alt Attribute Checker to inventory the image markup supplied to it before conducting this contextual review.

What the Alt Attribute Checker can—and cannot—verify

The checker can find img elements, report missing, empty, and non-empty alt attributes, expose common placeholder values or file-name text, and identify image links that need a functional name. Analysis occurs locally in the browser; supplied HTML and files are not uploaded to a server.

An empty alt value can be exactly right or seriously wrong. A polished sentence can be inaccurate or redundant. Dynamic images and CSS backgrounds may not exist in copied HTML. For these reasons, a clean report is not proof of WCAG conformance.

Common alt-text mistakes and direct fixes

• Missing alt attribute: decide the image’s purpose and add either meaningful text or an intentional empty value.
• alt="image": replace it with the information or function, or use empty alt if decorative.
• File-name alternative: discard names such as IMG_2048-final.jpg and write for the page context.
• Keyword stuffing: describe the user-relevant meaning in natural language.
• Every decorative image announced: use empty alt so repeated ornaments do not interrupt reading.
• Every image marked decorative: restore information that disappears when the image is removed.
• Icon described by shape: name the link destination or button action.
• Chart crammed into alt: add a short identifier and a complete visible or linked equivalent.
• Caption copied into alt: remove needless repetition and assign each text element a clear purpose.
• People or emotions guessed: include only verified and contextually relevant details.
• One library value reused everywhere: review the image’s role in each WordPress placement.
• Only article images audited: include logos, icons, featured images, cards, galleries, forms, and template media.

Alt text review checklist

Continue the DOFIW image-content workflow

Frequently asked questions