How to Write Alt Text for Images: The Complete Guide with 25+ Examples

Missing alt text is the single most common WCAG violation on the web. In our scan data across thousands of pages, images without alt attributes appear on roughly 85% of sites we audit. It is also one of the easiest violations to fix. No code changes. No redesign. Just a few words written with purpose.

This guide gives you everything you need to write good alt text: a decision tree for classifying any image, 25 before-and-after examples you can copy, platform-specific instructions for WordPress, Shopify, and Squarespace, and the common mistakes that waste an easy accessibility and SEO win.

If you want to find every image on your site that is missing alt text, install the PageAudit Chrome extension or run a free scan at PageAuditors. Both take under a minute, no signup required.

What Alt Text Is (and Who Uses It)

Alt text is the value of the alt attribute on an HTML <img> element. It is read by three distinct audiences, and writing good alt text means serving all three:

1. Screen reader users. Blind and low-vision users rely on assistive technology to read web pages aloud. When the screen reader reaches an image, it announces the alt text. If the alt attribute is missing, most screen readers fall back to reading the image filename, which is almost always meaningless ("hero-banner-v3-final-final.png").
2. Search engines. Google cannot actually see images. It can only read the alt attribute, the surrounding text, and a handful of other signals to guess what an image depicts. Alt text is the primary ranking factor for Google Image Search, and it gives Google additional context for ranking the page as a whole.
3. Users with broken images. When a slow connection, a blocked CDN, or a broken link prevents an image from loading, the browser displays the alt text in its place. A user who sees "Maria, founder of PageAuditors, at her desk" learns something. A user who sees a broken image icon learns nothing.

The first audience is the legal and ethical reason alt text exists. The other two are the reason skipping alt text also costs you search rankings and conversion.

The Alt Text Decision Tree

Before you write a single word, classify the image. Every image on a web page falls into one of four categories, and each category has a different rule.

Is the image purely decorative?
  (No meaning lost if removed: dividers, background textures, stock art next to text)
    -> YES: use alt=""
    -> NO: continue

Is the image inside a link or button with no visible text?
  (Icon-only buttons, logo that is also a home link, image that is a link)
    -> YES: alt text describes the ACTION or DESTINATION, not the picture
    -> NO: continue

Is the image complex (chart, diagram, infographic, map)?
    -> YES: short alt text + longer description nearby or via aria-describedby
    -> NO: continue

Standard informational image:
    -> Write 1-2 sentences (under 125 chars) describing what the image
       communicates IN CONTEXT of the surrounding text

Memorize the four categories: decorative, functional, complex, informational. Every example in this guide maps back to one of them.

25 Before-and-After Examples

Each example shows a failing version and a passing version, with a short note on which category the image belongs to and why the fix works.

Example 1: Hero Image on a Landing Page

Category: informational.

<!-- Before (failing) -->
<img src="/hero.jpg" />

<!-- Before (filename masquerading as alt text) -->
<img src="/hero.jpg" alt="hero.jpg" />

<!-- After (passing) -->
<img src="/hero.jpg" alt="Developer reviewing a PageAudit scan report on a laptop, showing 12 WCAG violations highlighted on an ecommerce page" />

The passing version describes what the image communicates in context (a user reviewing scan results), not just what is visible.

Example 2: Team Member Headshot

Category: informational.

<!-- Before -->
<img src="/maria.jpg" alt="photo of woman" />

<!-- After -->
<img src="/maria.jpg" alt="Maria Chen, co-founder and head of engineering at PageAuditors" />

Headshots should identify the person by name and role. "Photo of woman" is a description of the image; the name and role is information the page actually needs.

Example 3: Decorative Divider Line

Category: decorative.

<!-- Before (announces nothing useful) -->
<img src="/divider.svg" alt="divider" />

<!-- After -->
<img src="/divider.svg" alt="" />

A horizontal line between sections adds zero meaning. An empty alt="" tells screen readers to skip it entirely. The attribute must still be present; omitting it is a WCAG violation.

Example 4: Decorative Stock Photo Next to a Feature List

Category: decorative.

<!-- Before -->
<img src="/stock-handshake.jpg" alt="two people shaking hands" />

<!-- After -->
<img src="/stock-handshake.jpg" alt="" />

If the feature list already explains the point, the stock photo is purely visual padding. Mark it decorative so screen reader users are not interrupted by an irrelevant description.

Example 5: Icon-Only Button (Download)

Category: functional.

<!-- Before -->
<button>
  <img src="/icons/download.svg" alt="arrow pointing down" />
</button>

<!-- After -->
<button>
  <img src="/icons/download.svg" alt="Download scan report as PDF" />
</button>

The button is functional. Describe what it does, not what the icon depicts. A user who cannot see the icon does not care that the arrow points down; they care that clicking this button downloads a PDF.

Example 6: Icon Next to a Visible Text Label

Category: decorative (when paired with a visible label).

<!-- Before -->
<button>
  <img src="/icons/download.svg" alt="Download" />
  Download
</button>

<!-- After -->
<button>
  <img src="/icons/download.svg" alt="" />
  Download
</button>

When the icon is paired with a visible text label, the icon becomes decorative. Leaving a non-empty alt value causes screen readers to announce "Download Download", which is annoying and confusing.

Example 7: Logo That Is Also a Home Link

Category: functional.

<!-- Before -->
<a href="/">
  <img src="/logo.svg" alt="logo" />
</a>

<!-- After -->
<a href="/">
  <img src="/logo.svg" alt="PageAuditors home" />
</a>

The logo inside an anchor tag becomes the accessible name for the link. "Logo" is useless; "PageAuditors home" tells screen reader users where the link goes.

Example 8: Logo in a Footer (Not Linked)

Category: decorative or informational, depending on context.

<!-- If the logo is purely branding, next to company info already in text: -->
<img src="/logo.svg" alt="" />

<!-- If the logo is the only way the reader sees the company name: -->
<img src="/logo.svg" alt="PageAuditors" />

A logo's role changes depending on whether the company name is already present in the surrounding text. If the footer already says "PageAuditors, Inc.", the logo is decorative. If the logo is the sole branding, it needs a name.

Example 9: Ecommerce Product Photo

Category: informational.

<!-- Before -->
<img src="/products/red-tshirt.jpg" alt="t-shirt" />

<!-- After -->
<img src="/products/red-tshirt.jpg" alt="Cherry red cotton crewneck t-shirt, front view" />

Product photos should describe color, material, and view angle. This is also what Google Image Search rewards: descriptive, keyword-rich alt text directly improves product ranking.

Example 10: Ecommerce Product Gallery (Multiple Angles)

Category: informational, with distinct alt text per image.

<!-- Before (same alt for every angle) -->
<img src="/products/red-tshirt-front.jpg" alt="red t-shirt" />
<img src="/products/red-tshirt-back.jpg" alt="red t-shirt" />
<img src="/products/red-tshirt-detail.jpg" alt="red t-shirt" />

<!-- After -->
<img src="/products/red-tshirt-front.jpg" alt="Cherry red cotton crewneck t-shirt, front view showing rounded neckline" />
<img src="/products/red-tshirt-back.jpg" alt="Cherry red cotton crewneck t-shirt, back view showing tagless neck label" />
<img src="/products/red-tshirt-detail.jpg" alt="Close-up of red t-shirt fabric showing ribbed cotton texture and flat-lock seam" />

Each angle shows something different. The alt text for each should describe what is distinctive about that specific image.

Example 11: Screenshot in a Tutorial

Category: informational.

<!-- Before -->
<img src="/tutorial/step-3.png" alt="screenshot" />

<!-- After -->
<img src="/tutorial/step-3.png" alt="PageAudit popup showing the 'Run Scan' button highlighted in the top-right corner of the extension interface" />

Tutorial screenshots should describe what the user needs to see and do. "Screenshot" is never sufficient. The alt should function as written instructions for someone who cannot see the screen.

Example 12: Chart or Graph

Category: complex.

<!-- Before -->
<img src="/charts/monthly-scans.png" alt="chart showing scan volume" />

<!-- After: short alt + long description in the page body -->
<img src="/charts/monthly-scans.png"
     alt="Bar chart of monthly PageAudit scans, 2025 to 2026, showing steady growth"
     aria-describedby="monthly-scans-desc" />
<p id="monthly-scans-desc" class="visually-hidden">
  Monthly scan volume rose from 1,200 in January 2025 to 14,800 in March 2026,
  with the largest single-month jump of 3,400 scans in October 2025 following
  the WCAG 2.2 post publication. No month saw a decline of more than 5%.
</p>

For complex images, a 125-character summary cannot capture everything. Provide a short alt for quick recognition, and link a longer description via aria-describedby or include the full data in a nearby paragraph.

Example 13: Infographic

Category: complex.

<!-- Before -->
<img src="/infographics/lawsuit-stats.png" alt="accessibility lawsuit infographic" />

<!-- After -->
<img src="/infographics/lawsuit-stats.png"
     alt="Infographic: 2024 web accessibility lawsuits by industry. See full breakdown below."
     aria-describedby="lawsuit-stats-desc" />
<div id="lawsuit-stats-desc">
  <p>Total accessibility lawsuits filed in 2024: 4,605. Top five industries by filing count:</p>
  <ul>
    <li>Ecommerce: 1,820 (40%)</li>
    <li>Restaurants: 695 (15%)</li>
    <li>Hospitality: 410 (9%)</li>
    <li>Healthcare: 385 (8%)</li>
    <li>Financial services: 330 (7%)</li>
  </ul>
</div>

Infographics typically contain text as part of the image. That text must be available elsewhere in machine-readable form, either in a long description or in the page content itself.

Example 14: Quote Card (Text Rendered as Image)

Category: informational. The alt text must contain the quote verbatim.

<!-- Before -->
<img src="/quotes/sarah-testimonial.png" alt="customer quote" />

<!-- After -->
<img src="/quotes/sarah-testimonial.png"
     alt='"PageAudit found 47 violations on our site that our last agency missed. Worth every penny." Sarah Kim, CTO at Plainline.' />

If the image contains readable text, that text must appear in the alt. Losing a testimonial because it is rendered as a graphic is both an accessibility failure and an SEO failure.

Example 15: Before / After Comparison Image

Category: informational.

<!-- Before -->
<img src="/comparisons/contrast-fix.png" alt="before after" />

<!-- After -->
<img src="/comparisons/contrast-fix.png" alt="Before and after: light gray #999 body text on white (failing 2.85:1) compared to dark gray #595959 body text on white (passing 7:1)" />

Comparison images need to describe both states and what changed between them.

Example 16: Map

Category: informational or complex, depending on detail level.

<!-- Before -->
<img src="/maps/office.png" alt="map" />

<!-- After (simple marker map) -->
<img src="/maps/office.png" alt="Map showing PageAuditors office location at 123 Main Street, Brooklyn, NY, two blocks from the Jay Street subway station" />

For interactive maps, provide an address or directions in text. Static map images should describe what the map is showing and why.

Example 17: Icon in a Bulleted Feature List

Category: decorative.

<!-- Before -->
<ul>
  <li><img src="/icons/check.svg" alt="checkmark" /> Free forever plan</li>
  <li><img src="/icons/check.svg" alt="checkmark" /> No credit card required</li>
</ul>

<!-- After -->
<ul>
  <li><img src="/icons/check.svg" alt="" /> Free forever plan</li>
  <li><img src="/icons/check.svg" alt="" /> No credit card required</li>
</ul>

Repeating "checkmark checkmark checkmark" for every bullet makes pages painful to listen to. Mark list-bullet icons decorative.

Example 18: Avatar Next to a Comment or Review

Category: usually decorative.

<!-- Before -->
<img src="/avatars/sarah.jpg" alt="Sarah's avatar" />
<p><strong>Sarah K.</strong> This scanner is the real deal.</p>

<!-- After -->
<img src="/avatars/sarah.jpg" alt="" />
<p><strong>Sarah K.</strong> This scanner is the real deal.</p>

When the commenter's name is already visible next to the avatar, the image is decorative. Announcing "Sarah's avatar" before "Sarah K." is redundant.

Example 19: Background Image (CSS vs img Tag)

Category: decorative if purely visual.

<!-- Purely decorative: use CSS background-image, no img tag at all -->
<section style="background-image: url('/bg-pattern.svg')">
  <h2>Start scanning today</h2>
</section>

<!-- If you must use an img tag for layout reasons: -->
<img src="/bg-pattern.svg" alt="" aria-hidden="true" />

The best fix for decorative background graphics is to use CSS background-image instead of an <img> element. Background images in CSS are invisible to assistive technology by default. If you are stuck with an <img> tag, combine alt="" with aria-hidden="true" so it is skipped in every traversal.

Example 20: Captcha or Security Image

Category: functional (special case).

<!-- Before -->
<img src="/captcha.png" alt="" />

<!-- After -->
<img src="/captcha.png" alt="Type the letters you see above. If you cannot see the image, click the audio button to hear them instead." />

Captchas are a known accessibility problem. At minimum, tell the user the image contains challenge text and point them to an alternative such as an audio captcha. Do not leave the alt empty; that traps screen reader users.

Example 21: Linked Thumbnail in a Card

Category: functional (the whole card is a link).

<!-- Before -->
<a href="/blog/wcag-errors">
  <img src="/thumbnails/wcag-errors.jpg" alt="blog thumbnail" />
  <h3>How to Fix the 7 Most Common WCAG Errors</h3>
</a>

<!-- After -->
<a href="/blog/wcag-errors">
  <img src="/thumbnails/wcag-errors.jpg" alt="" />
  <h3>How to Fix the 7 Most Common WCAG Errors</h3>
</a>

When a card is wrapped in a single link and the heading is the accessible name, the thumbnail image should be decorative. Otherwise screen readers announce the image and the heading as two separate link texts.

Example 22: Social Share Icons

Category: functional.

<!-- Before -->
<a href="https://twitter.com/intent/tweet">
  <img src="/icons/twitter.svg" alt="twitter icon" />
</a>

<!-- After -->
<a href="https://twitter.com/intent/tweet">
  <img src="/icons/twitter.svg" alt="Share on Twitter" />
</a>

Social share icons inside links should describe the action, not the brand logo. "Twitter icon" is a description of the picture; "Share on Twitter" is the action the user takes.

Example 23: Flag or Language Selector

Category: functional.

<!-- Before -->
<a href="/es">
  <img src="/flags/es.svg" alt="Spanish flag" />
</a>

<!-- After -->
<a href="/es">
  <img src="/flags/es.svg" alt="Español" />
</a>

Flag icons in language selectors should name the language, not the country. A user whose language is Spanish is looking for "Español", not a flag description.

Example 24: Animated GIF (Tutorial or Demo)

Category: informational.

<!-- Before -->
<img src="/demos/scan-demo.gif" alt="animated gif" />

<!-- After -->
<img src="/demos/scan-demo.gif" alt="Animation of a PageAudit scan: user pastes a URL, clicks Scan, results appear showing 8 accessibility violations categorized by severity" />

Animated demos should describe the full sequence of events, not just that the image moves.

Example 25: Image Used as a Spacer or Layout Trick

Category: decorative.

<!-- Before -->
<img src="/spacer.gif" alt="spacer" />

<!-- After (if you must keep it) -->
<img src="/spacer.gif" alt="" />

<!-- Best: remove the spacer entirely and use CSS margin or padding -->

Spacer GIFs and 1x1 tracking pixels should have alt="" at minimum. Ideally, remove them entirely and use CSS for layout. Modern browsers handle whitespace better than 1999 did.

Common Mistakes

These are the patterns we see most often in PageAudit scan results. If you recognize any of them on your own site, they are worth fixing today.

Mistake 1: Using the Filename as Alt Text

<img src="/hero-banner-v3-final.png" alt="hero-banner-v3-final.png" />

Some CMSes and CMS plugins auto-populate the alt field with the filename when a human forgets to fill it in. This is worse than leaving the alt blank because a screen reader announces "hero dash banner dash v three dash final dot p n g" as if it were content. Always replace filename alt values.

Mistake 2: Starting with "Image of" or "Picture of"

<img src="/team.jpg" alt="Image of the PageAuditors team" />

Screen readers already announce the element as an image before reading the alt text. Saying "image of" is like starting a spoken sentence with "Word: The". Remove the prefix and lead with the content: alt="The PageAuditors team at our Brooklyn office".

Mistake 3: Redundant Alt Text Next to Visible Captions

<figure>
  <img src="/chart.png" alt="Bar chart of scan volume by month in 2025" />
  <figcaption>Bar chart of scan volume by month in 2025</figcaption>
</figure>

When a visible caption already describes the image, either use an empty alt (if the caption is fully sufficient) or write alt text that adds additional context the caption omits. Duplicating the exact text wastes the screen reader user's time.

Mistake 4: Alt Text That Describes Appearance Instead of Purpose

<!-- Weak: describes appearance -->
<img src="/founder.jpg" alt="Smiling man with glasses in front of a brick wall" />

<!-- Strong: describes purpose -->
<img src="/founder.jpg" alt="Chris Otto, founder of PageAuditors" />

Ask yourself: if this image did not exist, what would the reader need to know? The answer is the alt text.

Mistake 5: Missing the Alt Attribute Entirely

<img src="/whatever.jpg" />

The most common failure we find. Every <img> tag on every page needs an alt attribute, even if the value is empty. Omitting it is a WCAG 1.1.1 Level A violation, and most screen readers will fall back to reading the filename.

Mistake 6: Stuffing Keywords

<img src="/red-shoes.jpg" alt="red shoes, red sneakers, red footwear, womens red shoes, athletic red shoes, red running shoes" />

Keyword stuffing in alt text does not help SEO (Google detects it and discounts it) and makes screen reader audio miserable. Write one natural sentence that would be useful to a human.

CMS-Specific Instructions

You rarely need to edit HTML directly. Here is how to add alt text in the three most common CMS platforms.

WordPress

1. Go to Media > Library in the WordPress admin.
2. Click any image thumbnail to open the attachment details.
3. Fill the Alternative Text field at the top of the sidebar.
4. Changes save automatically.

For existing content, you can also edit alt text inline:

1. Open any post or page in the block editor.
2. Click the image block.
3. The Alt text (alternative text) field appears in the block settings sidebar on the right.

Bulk editing: Plugins like "Bulk Alt Text Editor" or "Media Library Assistant" let you edit alt text for hundreds of images at once. Useful after an audit reveals many missing values.

WordPress auto-populates the alt field with the image filename if you leave it blank. This produces the worst-case screen reader experience. Always replace it with something meaningful, even if that something is an empty string.

Shopify

For product images:

1. Open the product in Products > All Products.
2. Click the image thumbnail in the product page.
3. Click Add alt text in the image editor.
4. Type the description and click Save.

For theme-level images (logos, banners, sliders):

1. Go to Online Store > Themes > Customize.
2. Click the image block you want to edit.
3. Look for the Image alt text or Alternative text field in the block settings.
4. Save the theme.

Shopify also supports alt text on variant images and collection images. Each one is edited separately by clicking the image in the relevant admin page.

Shopify tip: Product alt text directly affects Google Shopping image rankings. Generic alt text like "t-shirt" leaves traffic on the table. Use the full product title plus color, view angle, and distinguishing features.

Squarespace

1. Open the page containing the image in the Squarespace editor.
2. Click the image to open the image editor.
3. In the Design tab of the image panel, find the Image Alt Text field.
4. Type the description. It saves when you click elsewhere or close the panel.

For gallery blocks:

1. Click the gallery block to open it.
2. Click the specific image you want to edit.
3. The Alt text field appears in the sidebar.
4. Save the block.

Squarespace caveat: Images added via Markdown blocks need alt text written in Markdown syntax: ![alt text here](image-url). Empty brackets ![]() is not valid empty alt; use ![](image-url) or switch to an image block.

Complex Images: When 125 Characters Is Not Enough

Some images carry too much information for a one-sentence alt attribute. Charts, infographics, diagrams, flowcharts, and maps often fall into this category. For these, use a two-part approach:

1. Short alt text that identifies the image and its purpose in one sentence.
2. Long description provided via one of:
   • aria-describedby pointing to an id containing the detailed description
   • A visible paragraph directly below the image
   • A link next to the image labeled something like "View full description"
   • The <figcaption> element inside a <figure>

The long description should contain whatever a sighted reader would extract from the image: data points, labels, trends, relationships. If the image is a chart, include the underlying data. If it is a flowchart, describe each step and connection.

How PageAudit Finds Missing Alt Text

The PageAudit Chrome extension and the web scanner at PageAuditors both check every <img> element on a page for alt-text issues. The rule is called image-alt and it catches:

• Images with no alt attribute at all
• Images with an alt value that matches the src filename
• Images inside links where the combined accessible name is empty
• Images where the alt value is only whitespace

Each violation is reported with the exact element location, a snippet of the surrounding HTML, and a plain-English explanation of how to fix it. You can sort by severity so that meaningful images get fixed before decorative ones.

Running the scan takes under a minute. Fixing the violations it finds usually takes an afternoon, even on a large site, because the fix for each image is just a few words.

For ongoing coverage, set up a recurring scan so that new images get checked as they are added. This is especially important for content-heavy sites where editors add images faster than developers can audit them.

Quick-Start Checklist

Copy this checklist and walk through it for any page you are reviewing.

• Every <img> tag has an alt attribute (even if empty)
• No alt attribute contains a filename or file extension
• Decorative images use alt="" or are moved to CSS background-image
• Functional images (icons, buttons, linked images) describe the action
• Informational images describe what they communicate in context, under 125 characters
• Complex images (charts, infographics) have both short alt and a long description
• No alt text starts with "image of" or "picture of"
• Icons paired with visible text labels use alt=""
• Text rendered as an image appears verbatim in the alt or nearby text
• A free scan confirms zero image-alt violations

Next Steps

Alt text is the fastest high-impact accessibility fix you can make. It takes minutes per image, requires no code changes on most platforms, and improves both WCAG compliance and image search rankings at the same time.

If you want to find every missing alt attribute on your site right now, run a free scan at PageAuditors or install the PageAudit Chrome extension for instant results on any page you visit. Both check against WCAG 2.1 AA and 2.2, flag every image-alt violation with its exact location, and give you plain-English fix instructions.

Once you have alt text covered, the next highest-impact fixes are the seven most common WCAG errors, starting with color contrast and missing form labels. Most sites can reach WCAG 2.1 AA compliance in a single focused week of work, and automated scanning does the heavy lifting of finding what needs fixing.