Eslint Plugin Jsx A11Y

title: "eslint-plugin-jsx-a11y" weight: 23 description: "Learn how to use eslint-plugin-jsx-a11y to catch accessibility issues during development: enforce alt text, label associations, keyboard handlers, ARIA rules, and semantic HTML in React code." date: 2026-06-28 lastmod: 2026-06-28 tags: [accessibility, react]

eslint-plugin-jsx-a11y is an ESLint plugin that catches accessibility issues at lint time in React code, enforcing rules like alt text on images, label associations on inputs, keyboard event handlers, and ARIA attribute correctness.

## What You'll Learn

You will install and configure eslint-plugin-jsx-a11y, understand the most important rules, fix common lint errors, and integrate it into your development workflow.

## Why It Matters

Linting catches accessibility issues before code is committed -- when they are cheapest to fix. Developers get immediate feedback in their editor as they type, preventing issues from reaching review or testing.

## Real-World Use

A developer writes `<img src="photo.jpg" />`. The linter immediately shows a warning: "img elements must have an alt prop." The developer adds `alt="Photo of product"` before saving. The issue never enters the codebase.

## Linting Rules

```mermaid
flowchart TD
  A[eslint-plugin-jsx-a11y] --> B[Static HTML]
  A --> C[ARIA]
  A --> D[Events]
  A --> E[Forms]
  B --> F[alt-text, heading-has-content]
  C --> G[aria-props, role-has-required-aria]
  D --> H[click-events-have-key-events]
  E --> I[label-has-associated-control]

Configuring the Plugin

Install and configure in your ESLint config.

npm install --save-dev eslint-plugin-jsx-a11y

// .eslintrc.json
{
  "plugins": ["jsx-a11y"],
  "extends": ["plugin:jsx-a11y/recommended"],
  "rules": {
    "jsx-a11y/alt-text": "error",
    "jsx-a11y/click-events-have-key-events": "error",
    "jsx-a11y/label-has-associated-control": "error",
    "jsx-a11y/no-noninteractive-tabindex": "warn",
    "jsx-a11y/anchor-is-valid": ["error", {
      "components": ["Link"],
      "specialLink": ["to"]
    }]
  }
}

// These would trigger lint errors
<img src="photo.jpg" />
// Error: img elements must have an alt prop

<div onClick={handleClick}>Click me</div>
// Error: visible, non-interactive elements with click handlers
// must have keyboard event handlers

<label>Name</label>
<input type="text" />
// Error: label must have associated control

// These pass linting
<img src="photo.jpg" alt="Product photo" />

<button onClick={handleClick}>Click me</button>

<label htmlFor="name">Name</label>
<input type="text" id="name" />

Common Mistakes

• Ignoring lint warnings as unimportant
• Disabling rules without understanding them
• Not integrating linting into the editor
• Using // eslint-disable-next-line without justification
• Not running linting in CI/CD
• Configuring rules too permissively
• Only running linting occasionally instead of on every save

Practice and Challenge

Practice 1: Install the plugin and fix 5 lint errors in a React project. Practice 2: Add alt text rules and fix all violations. Practice 3: Fix label-has-associated-control violations. Practice 4: Add keyboard event handlers to click handlers. Practice 5: Configure the plugin for a Next.js or Gatsby project.

Challenge: Set up eslint-plugin-jsx-a11y with strict rules in a React project. Fix all existing violations (expecting at least 20). Configure the rules to run on every commit (pre-commit hook) and in CI/CD. Document the most common violations found and how they were fixed.

FAQ

Mini Project

Create a strict eslint-plugin-jsx-a11y configuration for a React project. Configure all recommended rules as errors. Add custom rules for the project's specific patterns (Link components, custom button wrappers). Create a pre-commit hook that runs the linter and prevents commits with violations. Document the rule set and configuration.

What's Next

Skip Links in React covers implementing skip links in React applications.