Get professional support for eslint-plugin-jsx-a11y on Tidelift

eslint-plugin-jsx-a11y

Static AST checker for accessibility rules on JSX elements.

Read this in other languages.

Mexican Spanish🇲🇽

Why?

This plugin does a static evaluation of the JSX to spot accessibility issues in React apps. Because it only catches errors in static code, use it in combination with @axe-core/react to test the accessibility of the rendered DOM. Consider these tools just as one step of a larger a11y testing process and always test your apps with assistive technology.

Installation

If you are installing this plugin via eslint-config-airbnb, please follow these instructions.

You'll first need to install ESLint:

# npm
npm install eslint --save-dev

# yarn
yarn add eslint --dev

Next, install eslint-plugin-jsx-a11y:

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

# yarn
yarn add eslint-plugin-jsx-a11y --dev

Note: If you installed ESLint globally (using the -g flag in npm, or the global prefix in yarn) then you must also install eslint-plugin-jsx-a11y globally.

Usage - Legacy Config (.eslintrc)

Add jsx-a11y to the plugins section of your .eslintrc configuration file. You can omit the eslint-plugin- prefix:

{
  "plugins": ["jsx-a11y"]
}

Then configure the rules you want to use under the rules section.

{
  "rules": {
    "jsx-a11y/rule-name": 2
  }
}

You can also enable all the recommended or strict rules at once. Add plugin:jsx-a11y/recommended or plugin:jsx-a11y/strict in extends:

{
  "extends": ["plugin:jsx-a11y/recommended"]
}

Configurations

As you are extending our configuration, you can omit "plugins": ["jsx-a11y"] from your .eslintrc configuration file.

{
  "settings": {
    "jsx-a11y": {
      "polymorphicPropName": "as",
      "components": {
        "CityInput": "input",
        "CustomButton": "button",
        "MyButton": "button",
        "RoundButton": "button"
      },
      "attributes": {
        "for": ["htmlFor", "for"]
      }
    }
  }
}

Usage - Flat Config (eslint.config.js)

The default export of eslint-plugin-jsx-a11y is a plugin object.

const jsxA11y = require('eslint-plugin-jsx-a11y');

module.exports = [
  …
  {
    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
    plugins: {
      'jsx-a11y': jsxA11y,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
    rules: {
      // ... any rules you want
      'jsx-a11y/alt-text': 'error',
    },
    // ... others are omitted for brevity
  },
  …
];

Shareable Configs

There are two shareable configs, provided by the plugin.

• flatConfigs.recommended
• flatConfigs.strict

CJS

const jsxA11y = require('eslint-plugin-jsx-a11y');

export default [
  jsxA11y.flatConfigs.recommended,
  {
    // Your additional configs and overrides
  },
];

ESM

import jsxA11y from 'eslint-plugin-jsx-a11y';

export default [
  jsxA11y.flatConfigs.recommended,
  {
    // Your additional configs and overrides
  },
];

Note: Our shareable configs do NOT configure files or languageOptions.globals. For most of the cases, you probably want to configure some of these properties yourself.

const jsxA11y = require('eslint-plugin-jsx-a11y');
const globals = require('globals');

module.exports = [
  …
  {
    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
    ...jsxA11y.flatConfigs.recommended,
    languageOptions: {
      ...jsxA11y.flatConfigs.recommended.languageOptions,
      globals: {
        ...globals.serviceworker,
        ...globals.browser,
      },
    },
  },
  …
];

Component Mapping

To enable your custom components to be checked as DOM elements, you can set global settings in your configuration file by mapping each custom component name to a DOM element type.

Attribute Mapping

To configure the JSX property to use for attribute checking, you can set global settings in your configuration file by mapping each DOM attribute to the JSX property you want to check. For example, you may want to allow the for attribute in addition to the htmlFor attribute for checking label associations.

Polymorphic Components

You can optionally use the polymorphicPropName setting to define the prop your code uses to create polymorphic components. This setting will be used determine the element type in rules that require semantic context.

For example, if you set the polymorphicPropName setting to as then this element:

<Box as="h3">Configurations </Box>

will be evaluated as an h3. If no polymorphicPropName is set, then the component will be evaluated as Box.

To restrict polymorphic linting to specified components, additionally set polymorphicAllowList to an array of component names.

⚠️ Polymorphic components can make code harder to maintain; please use this feature with caution.

Supported Rules

💼 Configurations enabled in.\ 🚫 Configurations disabled in.\ ☑️ Set in the recommended configuration.\ 🔒 Set in the strict configuration.\ ❌ Deprecated.

Name	Description	💼	🚫	❌
accessible-emoji	Enforce emojis are wrapped in <span> and provide screen reader access.			❌
alt-text	Enforce all elements that require alternative text have meaningful information to relay back to end user.	☑️ 🔒
anchor-ambiguous-text	Enforce <a> text to not exactly match "click here", "here", "link", or "a link".		☑️
anchor-has-content	Enforce all anchors to contain accessible content.	☑️ 🔒
anchor-is-valid	Enforce all anchors are valid, navigable elements.	☑️ 🔒
aria-activedescendant-has-tabindex	Enforce elements with aria-activedescendant are tabbable.	☑️ 🔒
aria-props	Enforce all aria-* props are valid.	☑️ 🔒
aria-proptypes	Enforce ARIA state and property values are valid.	☑️ 🔒
aria-role	Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.	☑️ 🔒
aria-unsupported-elements	Enforce that elements that do not support ARIA roles, states, and properties do not have those attributes.	☑️ 🔒
autocomplete-valid	Enforce that autocomplete attributes are used correctly.	☑️ 🔒
click-events-have-key-events	Enforce a clickable non-interactive element has at least one keyboard event listener.	☑️ 🔒
control-has-associated-label	Enforce that a control (an interactive element) has a text label.		☑️ 🔒
heading-has-content	Enforce heading (h1, h2, etc) elements contain accessible content.	☑️ 🔒
html-has-lang	Enforce <html> element has lang prop.	☑️ 🔒
iframe-has-title	Enforce iframe elements have a title attribute.	☑️ 🔒
img-redundant-alt	Enforce <img> alt prop does not contain the word "image", "picture", or "photo".	☑️ 🔒
interactive-supports-focus	Enforce that elements with interactive handlers like onClick must be focusable.	☑️ 🔒
label-has-associated-control	Enforce that a label tag has a text label and an associated control.	☑️ 🔒
label-has-for	Enforce that <label> elements have the htmlFor prop.		☑️ 🔒	❌
lang	Enforce lang attribute has a valid value.
media-has-caption	Enforces that <audio> and <video> elements must have a <track> for captions.	☑️ 🔒
mouse-events-have-key-events	Enforce that onMouseOver/onMouseOut are accompanied by onFocus/onBlur for keyboard-only users.	☑️ 🔒
no-access-key	Enforce that the accessKey prop is not used on any element to avoid complications with keyboard commands used by a screen reader.	☑️ 🔒
no-aria-hidden-on-focusable