How to Configure JSX A11Y Rules for Accessibility in the Airbnb ESLint Config

The Airbnb JavaScript style guide automatically enables JSX accessibility rules through the react-a11y.js configuration file, which you can customize by overriding specific jsx-a11y/* rule definitions in your ESLint config.

The airbnb/javascript repository provides one of the most widely adopted ESLint configurations for React applications. Its dedicated accessibility layer—defined in packages/eslint-config-airbnb/rules/react-a11y.js—imports the eslint-plugin-jsx-a11y plugin and enforces sensible defaults for WCAG-compliant JSX. You can inspect the source code to understand the exact rule severity levels and options, then selectively override them in your own configuration file.

How the Airbnb JSX Accessibility Rules Are Structured

The react-a11y rule set is a plain JavaScript module that exports an ESLint configuration object. According to the source code in packages/eslint-config-airbnb/rules/react-a11y.js, the file is organized into four distinct sections:

• Plugin registration (lines 2‑5): Declares jsx-a11y and react as required plugins
• Parser options (lines 7‑11): Enables JSX parsing through ecmaFeatures: { jsx: true }
• Active rule definitions (line 13 onward): Lists every jsx-a11y/* rule with its severity ("error", "warn", or "off") and optional configuration objects
• Deprecated rules (lines 39‑68): Separates rules that have been removed from current versions of eslint-plugin-jsx-a11y

When you extend "airbnb" in your ESLint configuration, the index.js entry point automatically merges this react-a11y.js file into your rule set. Because the configuration is a standard JavaScript object, any key you redefine in your local rules section will completely override the Airbnb default.

Extending the Base Configuration

To inherit all accessibility rules as defined by Airbnb, add the shareable config to your extends array. This pulls in the full rule set from packages/eslint-config-airbnb/rules/react-a11y.js without requiring manual plugin installation.

{
  "extends": ["airbnb"]
}

This single line enables every jsx-a11y rule that Airbnb maintains, including alt-text validation and anchor-is-valid checks.

Customizing Rule Severity and Options

Because the Airbnb config exports a plain object, you can override any specific rule by redeclaring it in your configuration's rules section. Only the rules you explicitly list will change; all other accessibility rules remain exactly as defined in the source file.

Disabling a Rule

To turn off a rule that conflicts with your architecture—such as when using a custom routing component that wraps anchors—set its severity to "off". The following example disables jsx-a11y/anchor-is-valid, which is defined on lines 33‑40 of react-a11y.js:

{
  "extends": ["airbnb"],
  "rules": {
    "jsx-a11y/anchor-is-valid": "off"
  }
}

Changing Error Levels

You can downgrade a rule from "error" to "warn" if you want non-blocking feedback during development. For example, jsx-a11y/no-distracting-elements is set to "error" on lines 55‑58, but you can override this:

{
  "extends": ["airbnb"],
  "rules": {
    "jsx-a11y/no-distracting-elements": "warn"
  }
}

Configuring Custom Components

Many jsx-a11y rules accept an options object to account for design system components. The anchor-is-valid rule, defined with default options on lines 35‑39, allows you to specify which components should be treated as links:

{
  "extends": ["airbnb"],
  "rules": {
    "jsx-a11y/anchor-is-valid": [
      "error",
      {
        "components": ["Link", "RouterLink"],
        "specialLink": ["to"],
        "aspects": ["noHref", "invalidHref", "preferButton"]
      }
    ]
  }
}

This configuration tells ESLint to validate Link and RouterLink components with the same rigor as standard <a> tags.

Modifying Rule Parameters

You can also narrow the scope of rules like jsx-a11y/alt-text. While Airbnb's default configuration (lines 20‑27) checks multiple element types, you can restrict validation to only img elements:

{
  "extends": ["airbnb"],
  "rules": {
    "jsx-a11y/alt-text": [
      "error",
      {
        "elements": ["img"]
      }
    ]
  }
}

Implementing Custom Accessibility Rules

If you need to bypass the Airbnb react-a11y defaults entirely and define your own accessibility profile, you can manually register the plugin and enable only specific rules. This approach requires explicitly declaring jsx-a11y in your plugins array and enabling JSX parsing:

{
  "plugins": ["jsx-a11y", "react"],
  "parserOptions": {
    "ecmaFeatures": { "jsx": true }
  },
  "rules": {
    "jsx-a11y/alt-text": "error",
    "jsx-a11y/anchor-is-valid": ["error", { "components": ["Link"] }]
  }
}

Note that this configuration does not extend "airbnb", so you must manually install eslint-plugin-jsx-a11y as a dev dependency.

Summary

• The Airbnb ESLint config ships JSX accessibility rules through packages/eslint-config-airbnb/rules/react-a11y.js, which registers the jsx-a11y plugin and sets default severities.
• Extending "airbnb" automatically merges these rules into your project without additional configuration.
• Override any rule by declaring it in your config's rules section using the jsx-a11y/[rule-name] key.
• Pass options arrays to customize rule behavior for design system components or specific element types.
• Review lines 20‑27 for alt-text defaults and lines 33‑40 for anchor-is-valid defaults when planning your overrides.

Frequently Asked Questions

How do I completely disable the Airbnb JSX accessibility rules?

You cannot selectively exclude the react-a11y.js file when extending "airbnb", but you can override every active rule by setting each one to "off" in your rules section. Alternatively, extend "airbnb-base" instead of "airbnb" to omit the React and accessibility rules entirely, then manually add only the React rules you need.

Can I add custom components to the anchor-is-valid rule validation?

Yes. The jsx-a11y/anchor-is-valid rule accepts a components option array where you can list custom routing components like Link or RouterLink. Refer to the default options on lines 35‑39 of react-a11y.js for the expected schema, then extend the components array in your override.

Where does Airbnb define the default severity for accessibility rules?

All default severity levels and options for JSX accessibility are defined in packages/eslint-config-airbnb/rules/react-a11y.js. Active rules begin at line 13, while deprecated rules are catalogued separately on lines 39‑68 for reference.

What is the difference between "error" and "warn" in these rule configurations?

"error" causes ESLint to exit with a non-zero status code, blocking builds in CI/CD pipelines, while "warn" logs violations without failing the linting process. Airbnb sets most accessibility rules to "error" by default (as seen on lines 55‑58 for no-distracting-elements), but you can downgrade any rule to "warn" in your local configuration if you need a gradual migration path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}