@microsoft/eslint-plugin-fluentui-jsx-a11y

eslint-plugin-fluentui-jsx-a11y

A set of eslint rules against FluentUI to prevent common accessibility issues.

Finally! Lint rules against React props.

Covers hard-coded string props and variables for props.

<Label htmlFor="some-id">Some Label</Label>
<Input id="some-id" />

<Label htmlFor={someId}>Some Label</Label>
<Input id={someId} />

Rules for FluentUI v9 end in -v9. Fluent UI React v9

Rules for v8 have no ending.

Developed and maintained by the Microsoft Research Ireland Accessibility V-Team.

Installation

You'll first need to install ESLint:

# npm
npm install eslint --save-dev

# yarn
yarn add eslint --dev

Next, install @microsoft/eslint-plugin-fluentui-jsx-a11y:

# npm
npm install @microsoft/eslint-plugin-fluentui-jsx-a11y --save-dev

# yarn
yarn add @microsoft/eslint-plugin-fluentui-jsx-a11y --dev

Or add this package to your package.json file:

"devDependencies": {
    "@microsoft/eslint-plugin-fluentui-jsx-a11y": "1.0.0"
  }

And then you can run

  npm install

Usage

You will need to add the plugin to your .eslintrc configuration file. As we support both v8 and v9 right now, you will need to add the rules individually to the rules section.

V9 Suggested Configuration:

{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2018,
    "sourceType": "module"
  },
  "plugins": [
    "@typescript-eslint",
    "react-hooks",
    "@microsoft/fluentui-jsx-a11y"
  ],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",
    "react/prop-types": "off",
    "@microsoft/fluentui-jsx-a11y/no-empty-buttons": "error",
    "@microsoft/fluentui-jsx-a11y/checkbox-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/image-link-missing-aria-v9": "error",
    "@microsoft/fluentui-jsx-a11y/input-missing-label-v9": "error",
    "@microsoft/fluentui-jsx-a11y/switch-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/text-area-missing-label-v9": "error",
    "@microsoft/fluentui-jsx-a11y/image-button-missing-aria-v9": "error",
    "@microsoft/fluentui-jsx-a11y/toolbar-missing-aria-v9": "error",
    "@microsoft/fluentui-jsx-a11y/avatar-needs-name-v9": "error",
    "@microsoft/fluentui-jsx-a11y/breadcrumb-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/no-empty-buttons-v9": "error",
    "@microsoft/fluentui-jsx-a11y/dropdown-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/spin-button-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/combobox-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/compound-button-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/no-empty-components-v9": "error",
    "@microsoft/fluentui-jsx-a11y/accordion-header-needs-labelling-v9": "error",
    "@microsoft/fluentui-jsx-a11y/accordion-item-needs-header-and-panel-v9": "error",
    "@microsoft/fluentui-jsx-a11y/tooltip-not-recommended-v9": "error",
    "@microsoft/fluentui-jsx-a11y/spin-button-unrecommended-labelling-v9": "error"
  },

Why?

This plugin does a static code analysis of the React JSX to spot accessibility issues in apps built with FluentUI. That way, common accessibility issues are detected before the pull request stage and will be prevented from being checked into a code base.

As the plugin can only catch errors in static source code, please 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.

We also recomend that you use this plugin in conjuction with the eslint-plugin-jsx-a11y plugin. Please configure eslint-plugin-jsx-a11y to work with FluentUI components.

Example:

{
    "settings": {
        "jsx-a11y": {
            "components": {
                "Button": "button",
                "Image": "img"
            }
        }
    }
}

ESLint

This plugin was generated with The ESLint generator for Yeoman: eslint/generator-eslint.

eslint:plugin

yo eslint:plugin

eslint:rule

If you want to create a new ESLint rule, make sure you're in the top-level directory of an ESLint repo clone or an ESLint plugin and type:

yo eslint:rule

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Rules

🔧 Automatically fixable by the --fix CLI option.

Name	Description	🔧
accordion-header-needs-labelling-v9	The accordion header is a button and it needs an accessibile name e.g. text content, aria-label, aria-labelledby.
accordion-item-needs-header-and-panel-v9	An AccordionItem needs exactly one header and one panel
avatar-needs-name-v9	Accessibility: Avatar must have an accessible labelling: name, aria-label, aria-labelledby
breadcrumb-needs-labelling-v9	All interactive elements must have an accessible name
checkbox-needs-labelling-v9	Accessibility: Checkbox without label must have an accessible and visual label: aria-labelledby
combobox-needs-labelling-v9	All interactive elements must have an accessible name
compound-button-needs-labelling-v9	Accessibility: Compound buttons must have accessible labelling: title, aria-label, aria-labelledby, aria-describedby
dropdown-needs-labelling-v9	Accessibility: Dropdown menu must have an id and it needs to be linked via htmlFor of a Label
icon-text-content-button-does-not-need-aria	Accessibility: an image button with text content does not need aria labelling. The button already has an accessible name and the aria-label or aria-labelledby will override the text content for screen reader users.
image-button-missing-aria	Accessibility: Image buttons must have accessible labelling: aria-label, aria-labelledby, aria-describedby
image-button-missing-aria-v9	Accessibility: Image buttons must have accessible labelling: title, aria-label, aria-labelledby, aria-describedby
image-button-prefer-aria-over-title-attribute	Accessibility: prefer wai-aria over title or placeholder attributes. Title/placeholder can be used in addition to wai-aria. aria-label, aria-labelledby, aria-describedby
image-link-missing-aria-v9	Accessibility: Image links must have an accessible name	🔧
input-missing-label-v9	Accessibility: Input fields must have accessible labelling: aria-label, aria-labelledby or an associated label
menu-item-needs-labelling-v9	Accessibility: MenuItem without label must have an accessible and visual label: aria-labelledby
no-empty-buttons	Accessibility: buttons must either text content or accessible labelling
no-empty-buttons-v9	Accessibility: Button, ToggleButton, SplitButton, MenuButton, CompoundButton must either text content or icon or child component
no-empty-components-v9	FluentUI components should not be empty
object-literal-button-no-missing-aria	Accessibility: Object literal image buttons must have accessible labelling: aria-label, aria-labelledby, aria-describedby
radio-button-missing-label-v9	Accessibility: Radio button without label must have an accessible and visual label: aria-labelledby
radiogroup-missing-label-v9	Accessibility: RadioGroup without label must have an accessible and visual label: aria-labelledby
spin-button-needs-labelling-v9	Accessibility: SpinButtons must have an accessible label
spin-button-unrecommended-labelling-v9	Accessibility: Unrecommended accessibility labelling - SpinButton
switch-needs-labelling-v9	Accessibility: Switch must have an accessible label
text-area-missing-label-v9	Accessibility: Textarea must have an accessible name
text-content-button-does-not-need-aria	Accessibility: a button with text content does not need aria labelling. The button already has an accessible name and the aria-label will override the text content for screen reader users.
toolbar-missing-aria-v9	Accessibility: Toolbars need accessible labelling: aria-label or aria-labelledby
tooltip-not-recommended-v9	Accessibility: Prefer text content or aria over a tooltip for these components MenuItem, SpinButton