Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



Static AST checker for accessibility rules on JSX elements.

Version published
Weekly downloads
decreased by-2%
Install size
9.90 MB
Weekly downloads

Package description

What is eslint-plugin-jsx-a11y?

The eslint-plugin-jsx-a11y npm package is a collection of accessibility-related rules for ESLint that enforce best practices for accessibility in JSX (most commonly used with React). It helps developers write code that is accessible to users with disabilities by checking for common accessibility errors and suggesting improvements.

What are eslint-plugin-jsx-a11y's main functionalities?

Accessible elements

Ensures interactive elements are accessible. For example, this rule checks that buttons have an accessible name and can be interacted with via keyboard.

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

Aria roles

Enforces the use of valid ARIA roles and that elements with ARIA roles have the required attributes for that role.

<div role="button" onClick={this.handleRoleClick}>Role Button</div>

Media captions

Ensures media elements such as audio and video have captions or descriptions to aid users who cannot see or hear the content.

<video><track kind="captions" /></video>

No redundant alt text

Prevents the use of redundant alt text in images, which can be frustrating for screen reader users.

<img src="image.jpg" alt="" />

Keyboard accessibility

Ensures that custom interactive elements are focusable and have keyboard event handlers to mimic native interactive elements.

<div tabIndex="0" onKeyDown={this.handleKeyDown}>Focusable Div</div>

Other packages similar to eslint-plugin-jsx-a11y



v6.8.0 - 2023-11-01


  • Allow title attribute or aria-label attribute instead of accessible child in the "anchor-has-content" rule #727


  • [Docs] aria-activedescendant-has-tabindex: align with changes from #708 #924
  • [Fix] control-has-associated-label: don't accept whitespace as an accessible label #918


  • [Tests] migrate helper parsers function from eslint-plugin-react ce4d57f
  • [Refactor] use es-iterator-helpers 52de824
  • [New] mouse-events-have-key-events: add hoverInHandlers/hoverOutHandlers config db64898
  • [New] add polymorphicPropName setting for polymorphic components fffb05b
  • [Fix] isNonInteractiveElement: Upgrade aria-query to 5.3.0 and axobject-query to 3.2.1 64bfea6
  • [Refactor] use hasown instead of has 9a8edde
  • [actions] update used actions 10c061a
  • [Dev Deps] update @babel/cli, @babel/core, @babel/eslint-parser, @babel/plugin-transform-flow-strip-types, @babel/register, aud, eslint-doc-generator, eslint-plugin-import, minimist 6d5022d
  • [Dev Deps] update @babel/cli, @babel/core, @babel/eslint-parser, @babel/register, eslint-doc-generator, eslint-plugin-import 4dc7f1e
  • [New] anchor-has-content: Allow title attribute OR aria-label attribute e6bfd5c
  • [patch] mouse-events-have-key-events: rport the attribute, not the node eadd70c
  • [Deps] update @babel/runtime, array-includes, array.prototype.flatmap, object.entries, object.fromentries 46ffbc3
  • [Deps] update @babel/runtime, axobject-query, jsx-ast-utils, semver 5999555
  • [Fix] pin aria-query and axe-core to fix failing tests on main 8d8f016
  • [patch] move semver from Deps to Dev Deps 4da13e7
  • [Deps] update ast-types-flow b755318
  • [Dev Deps] update eslint-plugin-import f1c976b
  • [Deps] unpin language-tags 3d1d26d
  • [Docs] no-static-element-interactions: tabIndex is written tabindex 1271153
  • [Deps] Upgrade ast-types-flow to mitigate Docker user namespacing problems f0d2ddb
  • [Dev Deps] pin jackspeak since 2.1.2+ depends on npm aliases, which kill the install process in npm < 6 0c278f4



build status npm version license Coverage Status Total npm downloads

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


Static AST checker for accessibility rules on JSX elements.

Read this in other languages.

Mexican Spanish🇲🇽


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.


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.


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"]


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"
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.

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.

⚠️ 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-emojiEnforce emojis are wrapped in <span> and provide screenreader access.❌
alt-textEnforce all elements that require alternative text have meaningful information to relay back to end user.☑️ 🔒
anchor-ambiguous-textEnforce <a> text to not exactly match "click here", "here", "link", or "a link".☑️
anchor-has-contentEnforce all anchors to contain accessible content.☑️ 🔒
anchor-is-validEnforce all anchors are valid, navigable elements.☑️ 🔒
aria-activedescendant-has-tabindexEnforce elements with aria-activedescendant are tabbable.☑️ 🔒
aria-propsEnforce all aria-* props are valid.☑️ 🔒
aria-proptypesEnforce ARIA state and property values are valid.☑️ 🔒
aria-roleEnforce that elements with ARIA roles must use a valid, non-abstract ARIA role.☑️ 🔒
aria-unsupported-elementsEnforce that elements that do not support ARIA roles, states, and properties do not have those attributes.☑️ 🔒
autocomplete-validEnforce that autocomplete attributes are used correctly.☑️ 🔒
click-events-have-key-eventsEnforce a clickable non-interactive element has at least one keyboard event listener.☑️ 🔒
control-has-associated-labelEnforce that a control (an interactive element) has a text label.☑️ 🔒
heading-has-contentEnforce heading (h1, h2, etc) elements contain accessible content.☑️ 🔒
html-has-langEnforce <html> element has lang prop.☑️ 🔒
iframe-has-titleEnforce iframe elements have a title attribute.☑️ 🔒
img-redundant-altEnforce <img> alt prop does not contain the word "image", "picture", or "photo".☑️ 🔒
interactive-supports-focusEnforce that elements with interactive handlers like onClick must be focusable.☑️ 🔒
label-has-associated-controlEnforce that a label tag has a text label and an associated control.☑️ 🔒
label-has-forEnforce that <label> elements have the htmlFor prop.☑️ 🔒❌
langEnforce lang attribute has a valid value.
media-has-captionEnforces that <audio> and <video> elements must have a <track> for captions.☑️ 🔒
mouse-events-have-key-eventsEnforce that onMouseOver/onMouseOut are accompanied by onFocus/onBlur for keyboard-only users.☑️ 🔒
no-access-keyEnforce that the accessKey prop is not used on any element to avoid complications with keyboard commands used by a screenreader.☑️ 🔒
no-aria-hidden-on-focusableDisallow aria-hidden="true" from being set on focusable elements.
no-autofocusEnforce autoFocus prop is not used.☑️ 🔒
no-distracting-elementsEnforce distracting elements are not used.☑️ 🔒
no-interactive-element-to-noninteractive-roleInteractive elements should not be assigned non-interactive roles.☑️ 🔒
no-noninteractive-element-interactionsNon-interactive elements should not be assigned mouse or keyboard event listeners.☑️ 🔒
no-noninteractive-element-to-interactive-roleNon-interactive elements should not be assigned interactive roles.☑️ 🔒
no-noninteractive-tabindextabIndex should only be declared on interactive elements.☑️ 🔒
no-onchangeEnforce usage of onBlur over onChange on select menus for accessibility.❌
no-redundant-rolesEnforce explicit role property is not the same as implicit/default role property on element.☑️ 🔒
no-static-element-interactionsEnforce that non-interactive, visible elements (such as <div>) that have click handlers use the role attribute.☑️ 🔒
prefer-tag-over-roleEnforces using semantic DOM elements over the ARIA role property.
role-has-required-aria-propsEnforce that elements with ARIA roles must have all required attributes for that role.☑️ 🔒
role-supports-aria-propsEnforce that elements with explicit or implicit roles defined contain only aria-* properties supported by that role.☑️ 🔒
scopeEnforce scope prop is only used on <th> elements.☑️ 🔒
tabindex-no-positiveEnforce tabIndex value is not greater than zero.☑️ 🔒

The following rules have extra options when in recommended mode:


'jsx-a11y/no-interactive-element-to-noninteractive-role': [
    tr: ['none', 'presentation'],


'jsx-a11y/no-noninteractive-element-interactions': [
    handlers: [


'jsx-a11y/no-noninteractive-element-to-interactive-role': [
    ul: [
    ol: [
    li: ['menuitem', 'option', 'row', 'tab', 'treeitem'],
    table: ['grid'],
    td: ['gridcell'],


'jsx-a11y/no-noninteractive-tabindex': [
    tags: [],
    roles: ['tabpanel'],


'jsx-a11y/no-noninteractive-element-interactions': [
    handlers: [

Creating a new rule

If you are developing new rules for this project, you can use the create-rule script to scaffold the new files.

./scripts/create-rule.js my-new-rule

Some background on WAI-ARIA, the AX Tree and Browsers

Accessibility API

An operating system will provide an accessibility API that maps application state and content onto input/output controllers such as a screen reader, braille device, keyboard, etc.

These APIs were developed as computer interfaces shifted from buffers (which are text-based and inherently quite accessible) to graphical user interfaces (GUIs). The first attempts to make GUIs accessible involved raster image parsing to recognize characters, words, etc. This information was stored in a parallel buffer and made accessible to assistive technology (AT) devices.

As GUIs became more complex, the raster parsing approach became untenable. Accessibility APIs were developed to replace them. Check out NSAccessibility (AXAPI) for an example. See Core Accessibility API Mappings 1.1 for more details.


Browsers support an Accessibility API on a per operating system basis. For instance, Firefox implements the MSAA accessibility API on Windows, but does not implement the AXAPI on OSX.

The Accessibility (AX) Tree & DOM

From the W3 Core Accessibility API Mappings 1.1

The accessibility tree and the DOM tree are parallel structures. Roughly speaking the accessibility tree is a subset of the DOM tree. It includes the user interface objects of the user agent and the objects of the document. Accessible objects are created in the accessibility tree for every DOM element that should be exposed to assistive technology, either because it may fire an accessibility event or because it has a property, relationship or feature which needs to be exposed. Generally, if something can be trimmed out it will be, for reasons of performance and simplicity. For example, a <span> with just a style change and no semantics may not get its own accessible object, but the style change will be exposed by other means.

Browser vendors are beginning to expose the AX Tree through inspection tools. Chrome has an experiment available to enable their inspection tool.

You can also see a text-based version of the AX Tree in Chrome in the stable release version.

Viewing the AX Tree in Chrome
  1. Navigate to chrome://accessibility/ in Chrome.
  2. Toggle the accessibility off link for any tab that you want to inspect.
  3. A link labeled show accessibility tree will appear; click this link.
  4. Balk at the wall of text that gets displayed, but then regain your conviction.
  5. Use the browser's find command to locate strings and values in the wall of text.

Pulling it all together

A browser constructs an AX Tree as a subset of the DOM. ARIA heavily informs the properties of this AX Tree. This AX Tree is exposed to the system level Accessibility API which mediates assistive technology agents.

We model ARIA in the aria-query project. We model AXObjects (that comprise the AX Tree) in the axobject-query project. The goal of the WAI-ARIA specification is to be a complete declarative interface to the AXObject model. The in-draft 1.2 version is moving towards this goal. But until then, we must consider the semantics constructs afforded by ARIA as well as those afforded by the AXObject model (AXAPI) in order to determine how HTML can be used to express user interface affordances to assistive technology users.


eslint-plugin-jsx-a11y is licensed under the MIT License.



Last updated on 01 Nov 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc