Skip to content

fix(img-redundant-alt): only flag alts that are purely redundant or use 'word of' prefix#1085

Open
rhuyck wants to merge 3 commits intojsx-eslint:mainfrom
rhuyck:rhuyck-modify-img-redundant-alt
Open

fix(img-redundant-alt): only flag alts that are purely redundant or use 'word of' prefix#1085
rhuyck wants to merge 3 commits intojsx-eslint:mainfrom
rhuyck:rhuyck-modify-img-redundant-alt

Conversation

@rhuyck
Copy link
Copy Markdown

@rhuyck rhuyck commented Apr 1, 2026

Summary

The current rule flags any alt text that contains the words image, photo, or picture anywhere — which produces false positives for legitimate, descriptive alt text like "disk image", "profile photo", or "satellite image overlay". These compound nouns carry real meaning and should not be flagged.

This PR tightens the rule to two specific cases that are genuinely unhelpful to screen-reader users:

  1. Purely redundant alts — the entire alt is nothing but redundant words (e.g. alt="image", alt="photo"). These are flagged as before.
  2. "word of …" prefix — the alt opens with a redundant word followed by "of" (e.g. alt="image of a cat"). Screen-readers already announce the element as an image; the "image of" prefix adds nothing — only the description after it matters. These are flagged with a separate, softer message so they can be configured at a different severity in consumer ESLint configs. I am very open to other words, like "showing," but even that one I feel could mean showing in the figurative sense..

Everything else — compound nouns, descriptive labels that happen to include one of the words, template literals with meaningful context — is left alone.

Changes

  • src/rules/img-redundant-alt.js

    • Removed unused stringIncludes import
    • Replaced single containsRedundantWord check with two named functions (isOnlyRedundantWords, startsWithRedundantWordOf) that encode the intent explicitly
    • Switched to messages + messageId in meta so each case can be configured at different severity levels
    • Non-ASCII path now requires an exact whole-value match (previously used substring match, which would flag words like "imagery")
  • __tests__/src/rules/img-redundant-alt-test.js

    • Updated error assertions to use messageId instead of hardcoded message strings
    • Moved template-literal-with-context cases (picture doing ${things} etc.) to valid
    • Added valid cases demonstrating meaningful compound alt text: "disk image", "profile photo", "cover picture", "satellite image overlay", etc.
    • Added invalid cases for the new "word of" prefix check with explanatory comments

See here for some examples of alt texts that I believe should be entirely valid: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/pull/1085/changes#diff-c42207e7115fb61778d9d614ea8a38b2af9bcaefd070f14014c73716fcb05bb5R100-R110

All 38,607 existing tests pass.

Motivation

The rule as written is commonly perceived as overly aggressive. A rule that fires on alt="disk image" or alt="passport photo ID" trains developers to ignore or disable it (or just use a workaround like replacing "photo" with "photograph" rather than write better alt text — the opposite of the intended effect. Tightening the signal improves compliance with the cases that actually matter.

Additionally, after searching the Issues on this repo, it seems others years ago had similar thoughts: #417

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant