eslint-plugin-jsx-a11y
Advanced tools
Package description
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.
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>Similar to eslint-plugin-jsx-a11y, but specifically tailored for Vue.js applications. It provides a set of accessibility rules for Vue.js templates.
While not exclusively focused on accessibility, eslint-plugin-react includes some rules related to accessibility. It is a broader linting tool for React-specific code practices.
Although not an ESLint plugin, axe-core is a library for accessibility testing that can be integrated into testing frameworks. It provides comprehensive accessibility checks that can be run on rendered HTML, complementing the static analysis provided by eslint-plugin-jsx-a11y.
Changelog
v6.7.0 - 2023-01-09
#833aria-role: add now-passing test #756control-has-associated-label: fix metadata #892no-aria-hidden-on-focusable rule #881eslint-doc-generator 6d7a8573d77c84anchor-ambiguous-text rule 7f6463egetAccessibleChildText util 630116bisFocusable utils method e199d17eslint-doc-generator to v1.0.0 6b9855bno-noninteractive-element-interactions: Ignore contenteditable elements in no-noninteractive-element-interactions 9aa878banchor-ambiguous-text: ignore punctuation bbae2c4anchor-ambiguous-text, getAccessibleChildText: Implements check for alt tags on <img /> elements bb84abcnpmignore to autogenerate an npmignore file 6ad2312auto-changelog 283817b79b975aaria-query, axobject-query 7b3cda3@babel/cli, @babel/core, @babel/eslint-parser, @babel/plugin-transform-flow-strip-types, aud, object.assign 0852947.eslintignore to ignorePatterns 65be35b@babel/cli, @babel/core, aud, eslint-doc-generator 60c2df5@babel/runtime, array-includes, axe-core 4abc751@babel/runtime, axe-core 89f766ce411ce3@babel/core, minimist cccdb62markdown-magic 3382059prefer-tag-over-role 38d52f8label-has-for: reran generate-list-of-rules 9a2af01language-tags to v1.0.5 f84bb74@babel/core cf3f8d0axe-core 0a73cf4@babel/runtime 053f04d@babel/runtime bccf0aejsx-ast-utils c9687cc8b889bfprefer-tag-over-role: rename docs file 0bdf95bno-interactive-tabindex: allow role assignments using a ternary with literals on both sidesno-static-element-interactions: allow role assignments using a ternary with literals on both sides (#865)no-noninteractive-tabindex, no-static-element-interactions: document allowExpressionValues (#870)axe-coreaxe-core to v4.4.1, due to a breaking change in a patch@babel/runtime@babel/runtime, jsx-ast-utils@babel/cli, @babel/core, @babel/eslint-parser, @babel/plugin-transform-flow-strip-types, @babel/register@babel/cli, @babel/core, @babel/plugin-transform-flow-strip-types, @babel/registerno-noninteractive-element-interactions: add passing test cases (#876)no-noninteractive-element-interactions: add passing tests for form with onSubmit (#871)no-static-element-interactions: add passing test casesaria-role: add allowedInvalidRoles option (#828)no-redundant-roles, role-supports-aria-props: Remove implicit role from dl element (#848)role-supports-aria-props: clean up the logic a bit[].concat idiomno-static-element-interactions: Update error message (#843)@babel/runtime, array-includes, axe-core, jsx-ast-utilsjsx-ast-utils@babel/runtime, jsx-ast-utils@babel/runtime, axe-core, minimatch@babel/runtime, minimatch, semver@babel/runtime, axe-core, damerau-levenshteinexport default instead of module.exports (#861)@babel/cli, @babel/core, @babel/eslint-parser, @babel/plugin-transform-flow-strip-types, aud, eslint-plugin-eslint-plugin, eslint-plugin-flowtype, eslint-plugin-import@babel/core, @babel/register, eslint-plugin-import, minimist@technote-space/doctoc because v2.5 is a breaking change@babel/cli, @babel/core, @babel/eslint-parser, @babel/plugin-transform-flow-strip-types, eslint-plugin-eslint-plugin@babel/cli@babel/cli, @babel/core, @babel/eslint-parsernpm run flow (#856)img-redundant-alt-test: add passing tests (#832)module.exports (#824)eslint-plugin-import@babel/runtime, axe-core@babel/cli, @babel/core, @babel/eslint-parser, @babel/plugin-transform-flow-strip-types, eslint-config-airbnb-baseanchor-has-content: add missing close / for jsx succeed example (#821)master references in URLs to HEADeslint-plugin-eslint-plugin (#818)export default syntax for exporting rules (#819)@babel/runtime, array-includes, axe-core, jsx-ast-utils@babel/cli, @babel/core, @babel/eslint-parser, eslint-plugin-import, estraverse, safe-publish-latest@babel/eslint-parser instead of babel-eslint (#811).github reposcope: replace duplicate scope word (#799)no-access-key: Fix wording and grammar (#800)@babel/cli, @babel/core, @babel/plugin-transform-flow-strip-types, aud, eslint-plugin-flowtype, eslint-plugin-import@babel/runtime, axe-core, damerau-levenshteinsrc/util/getComputedRole-test.js test in node 6autocomplete-valid: move some failed tests to passingimport typeprepublishOnly script for npm 7+flow-bin to support aarch64 (#784)@babel/cli, @babel/core, @babel/plugin-transform-flow-strip-types, aud, eslint-plugin-flowtype, jscodeshift@babel/runtime, array-includes, axe-core, emoji-regexnode/install actionanchor-is-valid: general cleanup (#728)no-redundant-roles: Adds missing closing square bracket (#775)anchor-is-valid: Add Next.js case (#769)no-noninteractive-tabindex: Add example for tabIndex on seemingly non-interactive element (#760)aud in posttestlabel-has-associated-control: Add glob support (#749)strict config: Turn off label-has-for (#734)no-onchange: Remove rule from recommended/strict configs, and deprecate (#757)axe-core, jsx-ast-utils@babel/cli, @babel/core, @babel/plugin-transform-flow-strip-types, eslint-plugin-flowtype, eslint-plugin-import, estraverse, expect, object.assign@babel/runtime, axe-coreno-static-element-interactions: Fixed rule name in commentsautocomplete-valid: workaround for axe not being able to handle nullimg-redundant-alt: removing a use of somelabel-has-associated-control: add test for <div><label /><input /></div>@babel/runtime, array-includes, axe-core, axobject-query, damerau-levenshtein, jsx-ast-utils@babel/cli, @babel/core, @babel/plugin-transform-flow-types, babel-eslint, babel-jest, coveralls, eslint-config-airbnb-base, eslint-plugin-flowtype, eslint-plugin-import, estraverse, in-publish, jest, minimist, rimraf, safe-publish-latestlanguage-tags package to check the lang ruleimg<img> with alt=""plugin:jsx-a11y/{recommended,strict} configslabel-has-for: textareas are inputs too #470.npmignore with / so it only matches the top-level directorysrc and flow from package to resolve flow issues for consuming packages.anchor-is-valid. See documentation for configuration options. Thanks @AlmeroSteyn.href-no-hash replaced with anchor-is-valid in the recommended and strict configs. Use the invalidHref aspect (active by default) in anchor-is-valid to continue to apply the behavior provided by href-no-hash.label-has-for now allows inputs nested in label tags. Previously it was strict about requiring a for attribute. Thanks @ignatiusreza and @mjaltamirano.interactive-supports-focus. Recommended and strict configs for now contain a trimmed-down whitelist of roles that will be checked.media-has-caption. Thanks @ismail-syed.aria-props rule incorrectly threw errors for these new properties.label-has-for: add "required" option to allow customization (#240)anchor-is-valid (#224)interactive-supports-focus: Split interactive supports focus into tabbable and focusable cases (#236)anchor-is-valid: add aspects option (#251)flow directory from .npmignore to accommodate explicit imports from v5.0.2.img-has-alt rule into alt-text ruleonclick-has-role is removed. Replaced with no-static-element-interactions and no-noninteractive-element-interactions.onclick-has-focus is removed. Replaced with interactive-supports-focus.media-has-caption ruleignoreNonDOM option to no-autofocus.no-interactive-element-to-noninteractive-roleno-noninteractive-element-to-interactive-roleno-noninteractive-tabindexno-static-element-interactions and no-noninteractive-element-interactions. Options allow for fine-tuning of elements and event handlers to check.Add new rules:
jsx-a11y/accessible-emojijsx-a11y/aria-activedescendant-has-tabindexjsx-a11y/iframe-has-titlejsx-a11y/no-autofocusjsx-a11y/no-distracting-elements (breaking: consolidated no-marquee and no-blink into this rule.)jsx-a11y/no-redundant-rolesignoreNonDomaria-invalid values true and false pass for rule aria-proptypeshref-no-hash accepts new schema property specialLink to check for custom href properties on elements. (fixes #76)img-has-alt now prefers alt="" over role="presentation". You can set both, but not just role="presentation" by itself to ensure a11y across all devices.Note - see rule documentation for updated schemas.
switch aria role.x-has-content rules now pass with children prop set.tablist role to include missing property aria-multiselectable.click-events-have-key-events rule.no-static-element-interactions rule.eslint, eslint-config-airbnb, mocha to latest.error syntax over 2 syntax in recommended config.aria-checked for roles that are subclasses of checkboxanchor-has-content rule.img-redundant-alt (mainly for i18n).heading-has-content: dangerouslySetInnerHTML will pass.no-onchange rule to select menu elements only.eslint v3 as a peerDependency.eslint as a peerDependency.<ELEMENT role /> for role-supports-aria-props.img-redundant-alt rule to use getLiteralPropValue from jsx-ast-utils.heading-has-content for children content.jsx-ast-utils to use propName function. More support for namespaced names on attributes and elements.aria-unsupported-elements and role-supports-aria-props when reporting.aria-* propsrole value is a string before converting to lowercase in img-has-alt rule.tabIndex expression values, but still retain validation logic for literal tabIndex values.Button vs button).BinaryExpression type.NewExpression type.ObjectExpression type.ConditionalExpression type.onclick-has-focus.ThisExpression type.[breaking] Rename img-uses-alt to img-has-alt
[breaking] Rename onlick-uses-role to onclick-has-role
[breaking] Rename mouse-events-map-to-key-events to mouse-events-have-key-events
[breaking] Rename use-onblur-not-onchange to no-onchange
[breaking] Rename label-uses-for to label-has-for
[breaking] Rename redundant-alt to img-redundant-alt
[breaking] Rename no-hash-href to href-no-hash
[breaking] Rename valid-aria-role to aria-role
[new] Implement aria-props rule
[new] Implement aria-proptypes rule
[new] Implement aria-unsupported-elements rule
[new] Implement onclick-has-focus rule
[new] Implement role-has-required-aria-props rule
[new] Implement role-supports-aria-props rule
[new] Implement tabindex-no-positive rule
<Component prop={foo || "foobar"} />Object.Property i.e. UX.LayoutReadme
Get professional support for eslint-plugin-jsx-a11y on Tidelift
Static AST checker for accessibility rules on JSX elements.
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"]
}
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.
{
"settings": {
"jsx-a11y": {
"components": {
"CityInput": "input",
"CustomButton": "button",
"MyButton": "button",
"RoundButton": "button"
}
}
}
}
alt-text: Enforce all elements that require alternative text have meaningful information to relay back to end user.
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.
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.
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 screenreader.
no-autofocus: Enforce autoFocus prop is not used.
no-distracting-elements: Enforce distracting elements are not used.
no-interactive-element-to-noninteractive-role: Interactive elements should not be assigned non-interactive roles.
no-noninteractive-element-interactions: Non-interactive elements should not be assigned mouse or keyboard event listeners.
no-noninteractive-element-to-interactive-role: Non-interactive elements should not be assigned interactive roles.
no-noninteractive-tabindex: tabIndex should only be declared on interactive elements.
no-onchange: Enforce usage of onBlur over onChange on select menus for accessibility.
no-redundant-roles: Enforce explicit role property is not the same as implicit/default role property on element.
no-static-element-interactions: Enforce that non-interactive, visible elements (such as <div>) that have click handlers use the role attribute.
role-has-required-aria-props: Enforce that elements with ARIA roles must have all required attributes for that role.
role-supports-aria-props: Enforce that elements with explicit or implicit roles defined contain only aria-* properties supported by that role.
scope: Enforce scope prop is only used on <th> elements.
tabindex-no-positive: Enforce 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': [
'error',
{
tr: ['none', 'presentation'],
},
]
'jsx-a11y/no-noninteractive-element-interactions': [
'error',
{
handlers: [
'onClick',
'onMouseDown',
'onMouseUp',
'onKeyPress',
'onKeyDown',
'onKeyUp',
],
},
]
'jsx-a11y/no-noninteractive-element-to-interactive-role': [
'error',
{
ul: [
'listbox',
'menu',
'menubar',
'radiogroup',
'tablist',
'tree',
'treegrid',
],
ol: [
'listbox',
'menu',
'menubar',
'radiogroup',
'tablist',
'tree',
'treegrid',
],
li: ['menuitem', 'option', 'row', 'tab', 'treeitem'],
table: ['grid'],
td: ['gridcell'],
},
]
'jsx-a11y/no-noninteractive-tabindex': [
'error',
{
tags: [],
roles: ['tabpanel'],
},
]
'jsx-a11y/no-noninteractive-element-interactions': [
'error',
{
handlers: [
'onClick',
'onMouseDown',
'onMouseUp',
'onKeyPress',
'onKeyDown',
'onKeyUp',
],
},
]
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
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.
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.
chrome://accessibility/ in Chrome.accessibility off link for any tab that you want to inspect.show accessibility tree will appear; click this link.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.
FAQs
Static AST checker for accessibility rules on JSX elements.
The npm package eslint-plugin-jsx-a11y receives a total of 10,573,477 weekly downloads. As such, eslint-plugin-jsx-a11y popularity was classified as popular.
We found that eslint-plugin-jsx-a11y demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
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.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.
Security News
GitHub is susceptible to a CDN flaw that allows attackers to host malware on any public repository.
Security News
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.