Fix: Missing image alt text

Missing image alt text means your images are invisible to screen readers and Google Image Search crawlers. When Googlebot parses an <img> tag without an alt attribute, it drops the asset from Google Images indexing entirely. For accessibility, screen readers fall back to reading the raw filename out loud—meaning visually impaired users hear "screenshot-2024-11-04-final.png" instead of "Vercel deployment dashboard showing a successful build".

The Indxel image-alt-text rule evaluates every <img> node in your DOM and every Open Graph image definition in your metadata. If 50% or more of the images on a page lack an alt attribute, the check fails with a critical error. Below the 50% threshold, it triggers a warning. Fixing this resolves WCAG 2.1 Level A compliance (Success Criterion 1.1.1) and prevents Google Search Console from silently ignoring your visual assets.

How to detect missing alt text

Run the Indxel CLI against your local development server or production URL to catch missing alt attributes. The output highlights the exact DOM nodes failing the check.

npx indxel check http://localhost:3000 --rule image-alt-text

Crawling http://localhost:3000...
Scanned 44/47 pages.
 
/blog/nextjs-caching-guide
  Line 142: <img> tag missing alt attribute
  Line 185: <img> tag has empty alt attribute but lacks role="presentation"
 
/docs/api-reference
  Line 45: <img> tag missing alt attribute
 
✖ 3 issues found.
  image-alt-text: WARNING (4 pages affected)

The fix

The fix requires adding descriptive context to content-bearing images, and explicitly hiding decorative images from accessibility trees.

Next.js App Router

The Next.js <Image> component enforces the alt prop at the TypeScript level. However, developers frequently bypass this compiler check by passing an empty string. If the image conveys meaning, an empty string is an accessibility failure.

// ❌ Bad: Bypassing the TypeScript compiler with an empty string
import Image from 'next/image';
 
export default function Dashboard() {
  return (
    <Image 
      src="/seo-score-chart.png" 
      alt="" 
      width={800} 
      height={400} 
    />
  );
}

// ✅ Good: Specific, contextual description
import Image from 'next/image';
 
export default function Dashboard() {
  return (
    <Image 
      src="/seo-score-chart.png" 
      alt="Line chart showing organic traffic increasing by 45% over 30 days" 
      width={800} 
      height={400} 
    />
  );
}

Next.js Open Graph Images (Indxel SDK)

Alt text applies to metadata, not just DOM elements. When you define Open Graph images for social sharing, Twitter and LinkedIn use the alt property for accessibility. Using the Indxel SDK createMetadata wrapper enforces this requirement.

// ✅ Good: Enforcing Open Graph alt text via Indxel SDK
import { createMetadata } from '@indxel/sdk';
 
export const metadata = createMetadata({
  title: 'SEO Infrastructure Guide',
  openGraph: {
    images: [
      {
        url: 'https://indxel.com/og/infrastructure.png',
        width: 1200,
        height: 630,
        // Indxel SDK throws a type error if this is omitted
        alt: 'Indxel dashboard showing a 98/100 SEO score for a Next.js application',
      },
    ],
  },
});

Plain HTML

For standard HTML, the rule is identical. Omit the alt attribute entirely and the browser fails. Add a descriptive string.

<!-- ❌ Bad: No alt attribute -->
<img src="/avatars/user-123.jpg" class="rounded-full" />
 
<!-- ✅ Good: Descriptive alt attribute -->
<img src="/avatars/user-123.jpg" alt="Profile picture of Sarah Jenkins" class="rounded-full" />

Handling Decorative Images

If an image is purely decorative—like a background pattern, a dividing line, or an abstract shape—it should not have descriptive alt text. Reading "blue squiggly line" disrupts the screen reader experience.

Pass an empty string alt="" and add role="presentation". Indxel explicitly checks for this combination and marks it as a PASS for decorative images.

// ✅ Good: Explicitly decorative image
import Image from 'next/image';
 
export function Divider() {
  return (
    <Image 
      src="/wave-divider.svg" 
      alt="" 
      role="presentation"
      aria-hidden="true"
      width={1200} 
      height={50} 
    />
  );
}

Prevention: CI guard

Catch missing alt text before it merges to main. Add the Indxel CLI to your continuous integration pipeline to fail builds that introduce inaccessible images.

Vercel Build Command

Override your default Vercel build command to run the Indxel check first. This prevents deployments containing missing alt text.

npx indxel check --ci && next build

GitHub Actions

For a dedicated workflow, run Indxel against your deployment previews. Using the --diff flag ensures the CLI only evaluates files changed in the current PR, keeping CI times under 15 seconds.

name: Indxel SEO Guard
on: [pull_request]
 
jobs:
  validate-seo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run Indxel Check
        # Fails the PR if any new image lacks alt text
        run: npx indxel check --ci --diff --fail-on=image-alt-text

Edge cases

Developers frequently miss alt text when working with dynamic CMS data and inline SVGs.

Dynamic CMS Content When mapping over arrays of content from Sanity, Contentful, or Strapi, the image object might lack an alt field if the content editor forgot to fill it out. Do not fall back to the image filename or the post title. Fall back to an empty string and rely on your CI pipeline to catch the missing data at build time, or enforce the field at the CMS schema level.

// ❌ Bad: Falling back to useless data
<Image 
  src={post.coverImage.url} 
  alt={post.coverImage.alt || post.title} // Screen readers announce "Blog Post Title" twice
/>
 
// ✅ Good: Strict CMS typing
<Image 
  src={post.coverImage.url} 
  alt={post.coverImage.alt} // Enforce required alt fields in your CMS schema
/>

Inline SVGs Indxel does not flag <svg> tags for the image-alt-text rule because SVGs do not support the alt attribute. If your SVG contains meaningful content, you must use <title> and aria-labelledby.

// ✅ Good: Accessible inline SVG
<svg aria-labelledby="chart-title" viewBox="0 0 100 100">
  <title id="chart-title">Pie chart showing 60% mobile traffic</title>
  <circle cx="50" cy="50" r="40" />
</svg>

Related rules

• missing-og-image: Validates the presence and dimensions of Open Graph images in your document <head>.
• thin-content: Flags pages with a low text-to-HTML ratio, which often correlates with pages relying entirely on inaccessible images for content.

Should decorative images have alt text?

No. Decorative images like background patterns, layout dividers, and abstract shapes should use an empty alt attribute (alt="") and role="presentation". This explicitly instructs screen readers to skip the element entirely rather than reading out a useless description. Indxel validates this pattern and counts empty alt strings as intentional when paired with presentation roles.

How long should image alt text be?

Keep alt text under 125 characters. Screen readers typically chunk text into 125-character blocks, and longer descriptions get cut off mid-sentence. Use concise, specific language and avoid redundant prefixes like "Image of" or "Photo of", as screen readers announce the element type automatically.

Does Next.js automatically handle alt text?

No. While the Next.js <Image> component enforces the presence of the alt prop at the TypeScript level, it cannot validate the quality or context of the string you provide. Passing alt="" satisfies the compiler but fails accessibility and SEO checks if the image contains actual content. You must manually write descriptive strings or pull them from your database.