eslint-plugin-jsx-a11y

eslint-plugin-jsx-a11y is an ESLint plugin providing 39 lint rules that statically analyze JSX for accessibility violations — missing alt text, invalid ARIA roles and props, keyboard-inaccessible interactive elements, and more — directly in the editor and CI, long before a page ever renders.

Widely adopted across the React ecosystem (bundled into eslint-config-airbnb and historically part of Create React App’s default config), it models the WAI-ARIA role and element interaction matrix in pure AST analysis, supports both legacy .eslintrc and flat ESLint config formats, and lets teams enable an entire recommended or strict ruleset with a single config line.

What You Get

• 39 accessibility lint rules covering ARIA roles/props, alt text, keyboard interaction, labels, language attributes, and more
• Prebuilt “recommended” and “strict” rule presets for both flat config (eslint.config.js) and legacy .eslintrc setups
• Per-rule documentation pages under docs/rules/ with rationale, configurable options, and pass/fail code examples
• Configurable settings for mapping custom components (e.g. a wrapped <Button>) to their native HTML element semantics

Common Use Cases

• React app accessibility gate in CI — a team adds plugin:jsx-a11y/recommended to fail pull requests when JSX is missing an accessible name or keyboard handler
• Design-system component audits — mapping custom <IconButton>/<NavLink> wrappers to their native element via the components setting so they get linted like real HTML
• Legacy codebase remediation — running the plugin without the recommended preset first, then fixing violations rule-by-rule
• Cross-ESLint-version monorepos — packages still on legacy .eslintrc and others migrated to flat config both lint consistently since the plugin ships both formats

Under The Hood

Architecture

The entry point (src/index.js) aggregates every rule module from src/rules/*.js into a flat allRules map, then exports both a legacy config (configs/legacy-config-base.js) and a flat config (configs/flat-config-base.js) so the plugin works across ESLint’s config formats and major versions (3 through 9). Each rule is a self-contained module implementing ESLint’s meta + create(context) visitor interface, and nearly all of them lean on a shared layer of utility modules under src/util/ — getElementType, isInteractiveElement, getImplicitRole, isHiddenFromScreenReader, and similar helpers — that encode JSX/ARIA semantic knowledge once and reuse it everywhere; this utility layer is the load-bearing abstraction, since changing it would ripple through most of the 39 rules. Configuration (polymorphicPropName, components, attributes) flows through ESLint’s context.settings, keeping rule modules stateless and purely functional.

Tech Stack

Plain JavaScript (no TypeScript), built via Babel (@babel/cli, babel-preset-airbnb) into lib/ for publishing. Runtime dependencies include jsx-ast-utils and ast-types-flow for AST attribute inspection, aria-query and axobject-query for ARIA semantics tables, an embedded axe-core reference for its ruleset knowledge, language-tags for lang validation, damerau-levenshtein for typo suggestions, and a set of ES-spec polyfills (array-includes, array.prototype.flatmap, object.fromentries, string.prototype.includes, safe-regex-test) consistent with the Airbnb ecosystem’s conventions. It peer-depends on eslint across a wide version range and optionally types some internals with Flow. CI runs via GitHub Actions.

Code Quality

Tests run on tape (not Jest or Mocha) through a custom __tests__/__util__/RuleTester.js wrapper around ESLint’s own RuleTester, paired with parserOptionsMapper and ruleOptionsMapperFactory helpers that replay each rule’s test cases across multiple parsers (default espree, babel-eslint, TypeScript) and both legacy/flat config shapes — a deliberately engineered harness given the combinatorial surface of 39 rules times several parser and option variants. Coverage is tracked via Coveralls. Errors surface through ESLint’s own context.report() diagnostic mechanism rather than thrown exceptions. The project lints itself with eslint-plugin-eslint-plugin, and CI runs lint, Flow, unit tests, and example-project checks on every push.

What Makes It Unique

Rather than a generic linter, it encodes the WAI-ARIA role/element interaction matrix precisely enough in pure static analysis to catch cases like a <div role="button"> that isn’t focusable or lacks an accessible name — without ever touching a rendered DOM. Its public API favors low ceremony: adding a single extends line enables an entire curated ruleset, rule ids are consistently namespaced and documented, and both legacy and flat ESLint configs are supported so adoption doesn’t require a config rewrite.