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

> Learn how to configure JSX accessibility rules in your Airbnb ESLint config. Customize accessibility standards and ensure inclusive React development with simple overrides.

- Repository: [Airbnb/javascript](https://github.com/airbnb/javascript)
- Tags: how-to-guide
- Published: 2026-02-24

---

**The Airbnb JavaScript style guide automatically enables JSX accessibility rules through the [`react-a11y.js`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/index.js) entry point automatically merges this [`react-a11y.js`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/packages/eslint-config-airbnb/rules/react-a11y.js) without requiring manual plugin installation.

```json
{
  "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`](https://github.com/airbnb/javascript/blob/main/react-a11y.js):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/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`](https://github.com/airbnb/javascript/blob/main/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.