Rule: image-alt-text
Alt text is the text description of an image for screen readers and search engines. Without it, visually impaired users can't understand your images, and Google can't index them for image search. This rule uses a proportional threshold: if more than half your images are missing alt text, it's an error. Below half is a warning. The goal is universal alt text coverage.
What it checks
In crawl mode, Indxel fetches the page and finds all <img> elements. For each image, it checks whether the alt attribute exists and is non-empty. Images with alt="" (empty string) are counted as intentionally decorative and excluded from the missing count. The percentage of images missing alt text determines the result.
Thresholds
All images have alt attributes (or are intentionally empty for decorative images)
Less than 50% of images are missing alt text
50% or more of images are missing alt text
Edge cases
Decorative images with alt="" (intentionally empty) are excluded from the missing count. This is correct — decorative images should have empty alt text per WCAG guidelines.
Images without an alt attribute at all (no alt attribute in the HTML) are counted as missing. There's a difference between alt="" (intentional) and no alt attribute (oversight).
Background images set via CSS are not detected. Indxel only checks <img> elements in the DOM.
SVG elements are not checked by this rule. SVGs should use <title> or aria-label for accessibility, but that's outside this rule's scope.
Next.js Image component (<Image />) requires alt as a prop. If you use it consistently, this rule should always pass. Vanilla <img> tags are more prone to missing alt.
Lazy-loaded images (loading="lazy") are still checked. The alt attribute should be present regardless of loading strategy.
Configuration
// indxel.config.ts
import { defineSEO } from "indxel";
export default defineSEO({
rules: {
"image-alt-text": true, // enabled by default
},
});
// Content image — descriptive alt:
<Image
src="/dashboard.png"
alt="SEO dashboard showing score 94/100 with 3 warnings"
width={800}
height={400}
/>
// Decorative image — intentionally empty alt:
<Image
src="/bg-pattern.png"
alt=""
role="presentation"
width={100}
height={100}
/>Frequently asked questions
Why is the error threshold at 50%?
A single missing alt text on a page with 20 images is a minor oversight. But if 10+ images out of 20 are missing alt text, it indicates a systemic problem — the developer isn't thinking about accessibility at all. The 50% threshold separates occasional misses from fundamental issues.
Should every image have alt text?
Every content image should have descriptive alt text. Decorative images (backgrounds, dividers, visual flourishes) should have alt="" to tell screen readers to skip them. The distinction is: does this image convey information? If yes, describe it. If no, use empty alt.
Does alt text help with SEO?
Yes. Alt text is the primary way Google understands image content. Good alt text helps your images appear in Google Image Search and provides additional keyword context for the page. But write alt text for users first, search engines second.