Image alt text

What is image alt text and why does the alt attribute exist?

Image alt text is a textual description of an image, provided through the alt attribute on HTML <img> elements. When an image fails to load, or when a user cannot see the image (whether through blindness, low bandwidth, or because they're an AI agent without vision capabilities), the alt text stands in its place. A well-formed <img> tag looks like <img src="product.jpg" alt="Red leather messenger bag with brass buckles">. The description should convey the image's meaning and context, not just enumerate its visual features.

The Web Content Accessibility Guidelines (WCAG) 2.2, specifically success criterion 1.1.1 (Non-text Content), requires that all non-decorative images have a text alternative that serves the equivalent purpose. The W3C maintains a decision tree for alt text that walks through different image types—informative, decorative, functional, complex—and prescribes how each should be handled. Decorative images—think spacers, purely aesthetic flourishes—should carry an empty alt="" to signal they can be safely ignored. Everything else needs meaningful, concise text.

Why does image alt text matter for AI agents like ChatGPT and Claude?

Most AI agents cannot see images in the way a vision model does. When ChatGPT's browsing mode crawls your site, when Claude Desktop scrapes a product listing, when Perplexity indexes a blog post, they rely on the HTML source. If your product photography is wrapped in <img src="shoe.jpg"> with no alt attribute, the agent sees nothing—no brand name, no color, no feature callouts. Your $200 running shoe becomes an opaque blob. That product won't be recommended. That comparison table becomes unusable. That how-to diagram vanishes from agent-generated summaries.

The business impact is direct. E-commerce sites without alt text see lower citation rates in shopping-assistant agents; support documentation without alt text forces agents to hallucinate or skip steps; marketing sites lose out when agents can't describe hero images or testimonials. Vision-capable agents (GPT-4V, Claude 3.5 with vision) can interpret images on the fly, but they still prefer alt text—it's faster, cheaper, and more reliable than a real-time vision API call. If you want agents to confidently cite, recommend, or transact with your content, every meaningful image needs alt text. No exceptions.

Is image alt text required, recommended, or optional for agent readiness?

This check is recommended for most sites. If your site uses images to convey information—product photos, diagrams, screenshots, infographics, team headshots—then alt text moves from "nice to have" to "business critical." The exceptions are rare: a purely decorative portfolio site with no textual information, or an internal tool where images are generated dynamically and carry no semantic weight. Even then, you should still use alt="" for decorative images to pass the WCAG baseline.

The threshold we measure is simple: what percentage of your <img> tags have a non-empty alt attribute? Above 80% is healthy. Below 50% is a red flag. If you're an e-commerce site under 50%, assume agents are blind to half your catalog.

What the WCAG standard says about image alt text

• Every <img> must have an alt attribute. Omitting alt entirely is a WCAG Level A failure.
• Decorative images use alt="" to signal they convey no information.
• Informative images use concise, descriptive text that conveys the image's purpose. Avoid "image of" or "picture of"—just describe what matters.
• Functional images (e.g., icons used as buttons) should describe the action, not the icon. alt="Search" not alt="Magnifying glass icon".
• Complex images (charts, diagrams) need both a short alt and a longer description nearby, often via <figcaption> or an adjacent paragraph.

Minimum valid example:

<img src="/products/sneaker-blue.jpg" 
     alt="Men's blue running sneaker with white sole and mesh upper" 
     width="600" 
     height="400">

For a decorative divider:

<img src="/assets/divider.svg" alt="" role="presentation">

What good image alt text implementation looks like in production

Shopify enforces alt text at the theme level. Every product image uploaded through the admin UI prompts for an alt description, and the default themes render it correctly. A typical product page might show:

<img src="https://cdn.shopify.com/s/files/1/0001/2345/products/leather-tote.jpg" 
     alt="Brown full-grain leather tote bag with adjustable shoulder strap" 
     loading="lazy">

GitHub's documentation provides alt text for every screenshot and diagram. Their contribution guides explicitly require alt text in Markdown image syntax:

![Screenshot of the pull request review interface showing inline comments](pr-review.png)

Companies like Stripe, Notion, and Atlassian publish documentation and marketing sites with consistently descriptive alt text. Study their HTML; every informative image carries context an agent can consume.

How do I add image alt text to my site or SaaS product?

1. Audit your existing images. Run a quick DOM query in your browser console:

   document.querySelectorAll('img:not([alt])').length
   

   If that returns more than a handful, you have work to do.

2. Add alt to static HTML. For hand-authored pages, add alt attributes directly. Use the W3C decision tree to decide what text is appropriate.

3. Enforce alt in your CMS or component library. If you're using React, create a linter rule:

   // .eslintrc.js
   rules: {
     'jsx-a11y/alt-text': 'error',
   }
   

   For Next.js, the built-in <Image> component requires alt:

   import Image from 'next/image'
   
   <Image 
     src="/product.jpg" 
     alt="Stainless steel water bottle, 32oz" 
     width={600} 
     height={400} 
   />
   

4. Generate alt text for user-uploaded images. If your platform allows user uploads (marketplace, social, support tickets), use a vision API to generate fallback alt text. OpenAI's GPT-4V and Google's Cloud Vision both offer image captioning. Store the result in your database and render it in the alt attribute.

5. Use alt="" for decorative images. Spacer GIFs, background textures, purely aesthetic SVGs—these should carry an empty alt to avoid polluting screen readers and agent parsers.

How can I test my site's image alt text coverage?

Inspect the HTML source of your page or use a quick curl:

curl -s https://yoursite.com/products/example | grep -o '<img[^>]*>' | grep -v 'alt='

Any <img> tags returned lack an alt attribute.

Or just run a free scan and we'll check this for you alongside 30+ other agent-readiness signals.

Frequently asked questions

Do I need image alt text if my site uses AI vision models like GPT-4V?

Yes. While vision-capable agents can interpret images, they still prefer alt text because it's faster, cheaper, and more reliable than real-time vision API calls. Vision models also use alt text as ground truth when available, improving accuracy and reducing hallucination risk in agent responses.

Is empty alt text (alt="") wrong or lazy?

No—alt="" is correct for decorative images. WCAG explicitly requires empty alt attributes for spacers, dividers, and purely aesthetic images so screen readers and agents skip them. The mistake is omitting the alt attribute entirely, which fails WCAG Level A and confuses agents about image importance.

How does image alt text impact e-commerce sites and product recommendations?

E-commerce sites without alt text see lower citation rates in shopping assistants like ChatGPT and Perplexity. When agents can't read product images—color, material, features—they skip those items in recommendations. Sites under 50% alt coverage risk having half their catalog invisible to agent-driven commerce.

Should SaaS documentation include image alt text for every screenshot?

Absolutely. Support agents and documentation assistants rely on alt text to describe UI workflows. Without it, screenshot-heavy docs become unusable to agents, forcing hallucination or skipped steps. GitHub, Stripe, and Atlassian enforce alt text in every docs screenshot for this reason—agents need context, not image files.

What's the difference between image alt text and the title attribute?

The alt attribute is a text replacement when the image can't be displayed; it's read by screen readers and agents. The title attribute shows a tooltip on hover for sighted users but is ignored by most agents and assistive tech. Use alt for accessibility and agent readiness; use title sparingly for supplementary info.

Can I auto-generate image alt text with AI or is manual writing required?

You can auto-generate alt text using vision models (GPT-4V, Claude 3.5) for uploaded images, especially in CMSs or user-generated content. However, review outputs for accuracy and context—AI descriptions often miss brand names, product codes, or business-critical details that manual editing catches. Hybrid workflows work best.

How do I enforce image alt text in Next.js or React component libraries?

Use the jsx-a11y/alt-text ESLint rule to error on missing alt attributes. Next.js's <Image> component requires alt by default and will throw build errors if omitted. For design systems, wrap native <img> tags in a custom component that mandates the alt prop at the TypeScript level.

Does image alt text help with SEO or is it only for accessibility and agents?

Image alt text benefits SEO, accessibility, and agent readiness simultaneously. Google Images uses alt text for ranking and context; screen readers depend on it; and agents rely on it for product descriptions and content summarization. It's a triple-win investment, not a single-purpose optimization.