Using ESLint Plugin jsx-a11y With Recommended and Custom Rules

Creating “Accessible” web apps is both courteous and a business-savvy goal. Ease of use for the physically impaired increases the potential user base for the apps and may generate good will with users who appreciate such gestures.

The ESLint plugin jsx-a11y (also known as eslint-plugin-jsx-a11y) gives developers warnings in their IDE if their code might lead to known accessibility issues. Here’s the plugin correcting me when I use a scope tag where I shouldn’t:

jsx-a11y is simple to add and configure with “recommended” rules. I’ll show how to add it to a new app generated by create-react-app.

I’ll also discuss configuring eslint-plugin-jsx-a11y, the difference in recommended, strict, and custom set rules, and what the rules are based on. There will also be a generous amount of links to documentation and screenshots of the rules being enforced on my (bad) code.

jsx-a11y setup and Usage

**This was published in September 2021. All stats and code configs are as of that date.

Many developers (over 100K per week) create their react apps using the create-react-app command. You can do so by following the steps here.

Currently, create-react-app does not automatically install jsx-a11y. However, you can include it after the install by running the following:

npx install-peerdeps --dev eslint-config-airbnb

This will install eslint-config-airbnb, as well as peer dependencies such as eslint and eslint-plugin-jsx-a11y. It also installs them as devDependencies (that’s good, we don’t need them in prod). If you need TypeScript, don’t forget to install @typescript-eslint/eslint-plugin.

Recommended, Strict, and Customized Rules in jsx-a11y

At this point, we have jsx-a11y installed and available for use. Now we want to configure it in our .eslintrc file.

We have three configuration choices to make. Some of them can be mixed together:

• Use the plugin’s “Recommended” rules
• Use “Strict” rules
• Use a custom list of rules. This can be mixed with recommended and strict, and the custom list takes precedence

The difference between recommended and strict is that recommended gives an error “with options” for some of the rules. This allows for exceptions to the rules; recommended is less restrictive than strict.

I expect many people simply take the recommended rules from jsx-a11y. That’s a great starting point.

However, recommended and strict can both be overridden by a customized rules list. Take a look at the rules section below where I changed alt-text and aria-role to throw a warning instead of an error.

{
  "extends": [
    "plugin:jsx-a11y/recommended"
  ],
  "plugins": [
    "jsx-a11y"
  ],
  "rules": {
    "jsx-a11y/alt-text": "warn",
    "jsx-a11y/aria-role": "warn"
  }
}

Now images without alt text or elements with an incorrect (nonexistent) aria role will be flagged with warnings, but these will not stop successful code compilation.

<img src={logo} className="App-logo" /> //missing alt tag
<div role="barf">Test</div> //bad role

Customizing rules with warn is a way to disable recommended rules.

jsx-a11y Docs, NPM, and Rules List

The documentation is extensive and contains good examples. Github Repo/Docs link here. NPM Download is here.

A quick overview of the eslint-plugin-jsx-a11y rules is here. Alternatively, here’s a more detailed link where each rule has it’s own readme file with a description and example usage.

Each rule has code examples showing how to use any available options. For example, if you are using jsx-a11y/image-redundant-alt and you want it to check your custom Pic component, you might add the following option:

{
  "rules": {
    "jsx-a11y/img-redundant-alt": [ 2, {
      "components": [ "Pic" ],
      "words": [ "Picture", "Pic", "Photograph" ]
    }]
  }
}

This ensures that you will be notified if you add “Picture”, “Pic”, or “Photograph” in the alt tag of your Pic component. You will still be shown default warnings for img-redundant-alt. Here’s a screenshot of img-redundant-alt enforcing the rule on my Pic component (which is just a div with some text in it). It throws the error “Redundant alt attribute. Screen-readers already announce ‘img’ tags as an image. You don’t need to use the word ‘image'”.

The rules in jsx-a11y are based on WCAG and WAI-ARIA standards. These provide guidance on web accessibility. Enforcing them via jsx-a11y ensures that you provide an accessible experience even if you are new to accessibility.

Here’s a list of the top five most-searched (in Google) jsx-a11y rules and how to use them.

Resources

Normally I link to a Code Sandbox. However, this setup is so simple there is no additional code beyond what is shown above.

Here’s how to configure the no-unused-vars rule.

Here’s a YouTube version of this video.

If you want to dive deep into more aspects of ESLint, see the below articles:

• Why Use AirBnB’s ESLint Config? A Review of AirBnB’s Rules List
• How and When to Specify Globals in Eslintrc
• How to Ignore and Disable Type Rules Using TypeScript-ESLint