How to Write and Fix Image Alt Text for WCAG 2.1 AA

Image alt text is one of the most familiar accessibility topics, but it is also one of the most misunderstood. Many websites either leave image alt attributes empty when the image needs a description, stuff alt text with keywords for SEO, repeat nearby captions, or describe decorative images that should have been ignored by assistive technology.

Good alt text is not about describing every visual detail. It is about communicating the purpose of the image in context. A product photo, logo, chart, icon button, hero image, staff headshot, map, infographic, and decorative background all need different treatment. Some images need concise descriptions. Some need longer explanations nearby. Some need empty alt text. Some should be implemented in CSS instead of HTML. Some need an accessible name because they function as links or buttons.

ADA CodeFix flags missing and suspicious image alt text because images are common across almost every site. This guide explains how to decide whether an image needs alt text, how to write useful alt text, how to handle decorative and functional images, and how to test image accessibility manually.

This page is informational and is not legal advice. Accessibility conformance depends on the full page context, not just whether an alt attribute exists. For legal guidance, consult qualified counsel. For accessibility conformance, combine automated scans with manual testing.

What is alt text?

Alt text is the text alternative for an image. In HTML, it is usually provided with the alt attribute.

Example:

<img src="/images/red-running-shoe.jpg" alt="Red running shoe with white sole">

If the image cannot be seen, the alt text can communicate the image's purpose. Screen readers can announce it. Search engines can use it as one signal to understand the image. Browsers can show it if the image fails to load.

But alt text is not only a technical field. It is a content decision. The right alt text depends on why the image is on the page, what surrounding text already says, and what role the image plays in the layout.

WCAG criterion related to alt text

The main WCAG criterion is 1.1.1 Non-text Content. It requires text alternatives for non-text content so the information or function can be presented in other ways.

In practical terms:

• Informative images need text alternatives.
• Functional images need text that describes the function.
• Decorative images should usually be ignored by assistive technology.
• Complex images need a short alt text plus a longer explanation nearby.
• Images of text should generally be avoided unless necessary.

The most important rule: describe the purpose, not just the pixels

Bad alt text often describes an image without considering context. Imagine a homepage hero image showing a smiling dentist with a patient.

Bad:

<img src="dentist.jpg" alt="Woman in blue shirt sitting in chair with person wearing mask">

Better:

<img src="dentist.jpg" alt="Dentist preparing a patient for an exam">

But if the image is purely decorative next to a heading that already says "Family dental care in Austin," it might be better as:

<img src="dentist.jpg" alt="">

The question is not "what is in the image?" The question is "what does this image contribute here?"

Missing alt attribute vs empty alt text

There is an important difference between a missing alt attribute and an empty alt attribute.

Problem:

<img src="/images/wave-divider.png">

This image has no alt attribute. Some screen readers may announce the file name, which can be noisy and unhelpful.

Decorative image:

<img src="/images/wave-divider.png" alt="">

This image has an empty alt attribute. That tells assistive technology to ignore it.

Informative image:

<img src="/images/team-photo.jpg" alt="ADA CodeFix team reviewing accessibility scan results">

This image has meaningful alt text. Every meaningful img element should have an appropriate alt attribute. The attribute may be empty if the image is decorative, but it should not be missing entirely.

Decorative images

Decorative images do not add meaningful information. They may create mood, visual separation, background texture, or layout. Examples include:

• Abstract background shapes
• Decorative dividers
• Stock photos that do not add information
• Icons repeated next to visible text
• Borders, flourishes, shadows, and ornamental graphics

Use empty alt text:

<img src="/images/blue-shape.svg" alt="">

If an image is purely decorative, consider using CSS instead:

.hero {
  background-image: url("/images/abstract-background.svg");
}

CSS background images are generally ignored by assistive technology, which is often appropriate for decorative visuals. Save HTML img elements for images that carry information or perform a function.

Informative images

Informative images communicate content that is not fully available in nearby text.

Example:

<img
  src="/images/accessibility-dashboard.png"
  alt="Accessibility dashboard showing 12 critical issues, 8 serious issues, and 24 moderate issues"
>

This alt text communicates the information a user would miss if they could not see the image.

For a staff headshot:

<img src="/team/maya.jpg" alt="Maya Chen, accessibility engineer">

For an office location photo:

<img src="/office-entrance.jpg" alt="Main entrance to the clinic on Elm Street">

Keep alt text concise. If the image needs a long explanation, use nearby text instead of stuffing everything into the alt attribute.

Functional images

A functional image performs an action. The alt text should describe the function, not the visual appearance.

Bad:

<a href="/cart">
  <img src="/icons/cart.svg" alt="Shopping cart icon">
</a>

Better:

<a href="/cart">
  <img src="/icons/cart.svg" alt="View cart">
</a>

The image is inside a link. The user needs to know what the link does.

For a search button:

<button type="submit">
  <img src="/icons/search.svg" alt="Search">
</button>

If using inline SVG, handle it like an icon button:

<button type="submit" aria-label="Search">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

For social links:

<a href="https://www.linkedin.com/company/example">
  <img src="/icons/linkedin.svg" alt="Visit us on LinkedIn">
</a>

Do not use alt text like "LinkedIn logo" if the image is the only content in a link. The action is more important than the object.

Linked images

When an image is inside a link, the alt text becomes the accessible name of the link.

Problem:

<a href="/pricing">
  <img src="/images/pricing-card.png" alt="">
</a>

This creates a link with no accessible name.

Better:

<a href="/pricing">
  <img src="/images/pricing-card.png" alt="View ADA CodeFix pricing">
</a>

If the link also contains visible text, the image may be decorative.

<a href="/pricing" class="pricing-card">
  <img src="/images/pricing-card.png" alt="">
  <span>View pricing</span>
</a>

Avoid repeating the same text twice. If the visible link text already describes the destination, the image can usually have alt="".

Product images

Product images usually need descriptive alt text, but the right detail depends on the product.

For ecommerce:

<img
  src="/products/black-leather-wallet.jpg"
  alt="Black leather bifold wallet with six card slots"
>

If the product name is already next to the image, the alt text can be shorter.

<h2>Black Leather Bifold Wallet</h2>
<img src="/products/wallet.jpg" alt="Front view">

But "front view" only works because the product name is nearby. Without that context, it is too vague.

For multiple product images:

<img src="/products/chair-front.jpg" alt="Oak dining chair front view">
<img src="/products/chair-side.jpg" alt="Oak dining chair side view">
<img src="/products/chair-detail.jpg" alt="Close-up of woven seat texture">

Do not keyword-stuff:

<img
  src="/products/wallet.jpg"
  alt="best black leather wallet mens wallet minimalist wallet buy leather wallet online"
>

That is bad for users and can look spammy to search engines as well.

Logos

A logo usually needs alt text that identifies the organization.

<img src="/logo.svg" alt="ADA CodeFix">

If the logo is a home link:

<a href="/">
  <img src="/logo.svg" alt="ADA CodeFix home">
</a>

If nearby text already says the company name, an empty alt may be acceptable, but most header logos use the logo as a home link, so a useful accessible name is important.

Icons

Icons can be decorative or functional depending on where they appear.

Decorative icon next to visible text:

<span class="feature">
  <img src="/icons/check.svg" alt="">
  Automated WCAG scans
</span>

The visible text already says the important thing.

Icon-only button:

<button type="button" aria-label="Open navigation menu">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

Icon with text inside a button:

<button type="button">
  <svg aria-hidden="true" focusable="false">...</svg>
  Download report
</button>

The SVG should be hidden because the button already has visible text.

Charts and graphs

Charts are complex images. A short alt attribute is usually not enough to communicate all the data. Use short alt text plus a nearby explanation.

<img
  src="/images/contrast-issues-chart.png"
  alt="Bar chart comparing accessibility issue counts by severity"
>

Then provide the key takeaway in text:

<p>
  The scan found the highest number of issues in the moderate category,
  followed by serious issues. Critical issues were less frequent but should
  be fixed first because they create the largest barriers.
</p>

If the chart contains important data, consider adding a table.

<table>
  <caption>Accessibility issues by severity</caption>
  <thead>
    <tr>
      <th>Severity</th>
      <th>Issue count</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Critical</td>
      <td>4</td>
    </tr>
    <tr>
      <td>Serious</td>
      <td>12</td>
    </tr>
    <tr>
      <td>Moderate</td>
      <td>31</td>
    </tr>
  </tbody>
</table>

This is often more accessible than trying to place every number in the alt text.

Images of text

Avoid images of text when possible. Real HTML text is more flexible. Users can resize it, translate it, select it, adjust spacing, and use it with assistive technology.

Problem:

<img src="/sale-banner.png" alt="Spring sale 40% off all services">

Better:

<section class="sale-banner">
  <h2>Spring sale</h2>
  <p>Save 40% on all services.</p>
</section>

If you must use an image of text, the alt text should include the same text unless the text is already provided nearby.

How to write good alt text

Use these rules:

1. Be concise.
2. Describe the purpose of the image.
3. Avoid "image of" or "picture of" unless relevant.
4. Do not stuff keywords.
5. Do not repeat nearby text unnecessarily.
6. Use empty alt text for decorative images.
7. Describe function for linked or clickable images.
8. Provide longer explanations for complex images outside the alt attribute.
9. Consider the page context.
10. Test with a screen reader or accessibility tree when possible.

How ADA CodeFix detects image alt issues

ADA CodeFix can flag common image accessibility problems such as:

• Missing alt attributes
• Empty alt text on images that may be informative
• Non-empty alt text on images that may be decorative
• Linked images without accessible names
• Icon-only buttons without accessible names
• SVGs that may be exposed incorrectly
• Images of text that may need HTML alternatives
• Very long or suspicious alt text
• Duplicate alt text repeated across many images

Automated tools can detect missing attributes, but they cannot always decide whether the alt text is good. A scanner can tell you that an image has alt="photo", but a human must decide whether that is meaningful in context.

Manual alt text review checklist

Use this checklist after making changes.

1. Does every img element have an alt attribute?
2. Are decorative images marked with alt=""?
3. Do informative images explain the purpose of the image?
4. Do linked images describe the link destination or action?
5. Do icon-only buttons have accessible names?
6. Are charts explained in nearby text or tables?
7. Are images of text avoided where possible?
8. Is alt text concise and useful?
9. Is keyword stuffing avoided?
10. Does the alt text make sense in context?

A useful test is to cover the image and read only the alt text. If the page still communicates the important information, the alt text is probably doing its job.

Common mistakes to avoid

Mistake 1: Using the file name as alt text

Bad:

<img src="/images/IMG_4920.jpg" alt="IMG_4920">

Better:

<img src="/images/IMG_4920.jpg" alt="Customer using an accessible checkout form">

Mistake 2: Keyword stuffing

Bad:

<img
  src="/audit-dashboard.png"
  alt="ADA compliance scanner WCAG accessibility checker best ADA scanner accessibility audit tool"
>

Better:

<img
  src="/audit-dashboard.png"
  alt="Accessibility scan dashboard showing issues grouped by severity"
>

Mistake 3: Describing decorative images

Bad:

<img src="/divider.svg" alt="Blue wavy decorative divider">

Better:

<img src="/divider.svg" alt="">

Mistake 4: Empty alt text on functional images

Bad:

<a href="/report">
  <img src="/icons/download.svg" alt="">
</a>

Better:

<a href="/report">
  <img src="/icons/download.svg" alt="Download report">
</a>

Mistake 5: Repeating captions exactly

If an image has a caption that already explains it, the alt text can be shorter. Do not force screen reader users to hear the same full sentence twice.

Platform-specific notes

WordPress

WordPress has an alt text field in the Media Library, but that does not mean every image should use the same alt text everywhere. The right alt text can change depending on context. Review important images directly on the page where they appear, not only in the media library.

Shopify

Product images, collection images, variant images, logo links, payment icons, and search/cart icons need review. Product image alt text should describe the product and view when helpful, not just repeat the product title that already appears next to the image.

Webflow

Check image settings for alt text and decorative marking. For background images used decoratively, CSS background images may be appropriate. For meaningful content, use actual image elements with text alternatives.

React and Next.js

When using image components, always pass appropriate alt text.

<Image
  src="/dashboard.png"
  alt="Accessibility dashboard showing critical, serious, and moderate issues"
  width={1200}
  height={800}
/>

For decorative images:

<Image
  src="/decorative-shape.svg"
  alt=""
  aria-hidden="true"
  width={200}
  height={200}
/>

Do not make alt optional in reusable components unless the component clearly handles decorative images.

Final takeaway

Alt text is not a box to check. It is a way to make visual information or functionality available to people who cannot see the image. The right approach depends on context.

Informative images need useful descriptions. Decorative images usually need empty alt text. Functional images need alt text that describes the action. Complex images need nearby explanations, not overloaded alt attributes. ADA CodeFix can help identify missing and suspicious alt text, but a human should review whether the text actually communicates the image's purpose. Good alt text improves accessibility, usability, and often content clarity for everyone.

Sources

• W3C WCAG Understanding 1.1.1 Non-text Content (opens in new tab)
• W3C WAI Images Tutorial (opens in new tab)
• W3C WCAG Understanding 1.3.1 Info and Relationships (opens in new tab)
• W3C WCAG Quick Reference (opens in new tab)
• W3C Web Accessibility Initiative (WAI) (opens in new tab)