Configuring axe DevTools Linter

Link to Configuring axe DevTools Linter copied to clipboard

A reference guide for configuring axe DevTools Linter

This article provides a reference for axe DevTools Linter configuration options.

Overview

The REST API endpoint uses JSON for configuration, and the axe Accessibility Linter extension for VS Code, the JetBrains plugin, and the axe DevTools Linter Connector use YAML for configuration. Both JSON and YAML examples of axe DevTools Linter configurations are shown in this guide.

Example Configurations

The following YAML example demonstrates a simple configuration that uses the rules option for use with the axe Accessibility Linter extension for VS Code, the JetBrains plugin, or axe DevTools Linter Connector:

rules:
  html-has-lang: false

The following example demonstrates the same configuration as a complete request object with the rules option for the axe DevTools Linter REST service with its embedded config object highlighted:

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {    "rules": {      "html-has-lang": false    },    "exclude": [],
    "tags": []
  }
}

In both cases, these configurations cause axe DevTools Linter to ignore accessibility errors when the html element is missing a lang attribute. (See the html-has-lang rule for more information.)

note

For all of the JSON examples in this article, the config object is included to provide a reference location for the configuration.

The following sections describe each configuration option and give examples of their usage.

Multiple Configuration Files

The axe Accessibility Linter extension for VS Code, the JetBrains plugin, and the axe DevTools Linter Connector (when used with the --config option with no parameter) will search the current directory and parent directories for axe-linter.yml configuration files in your project directory tree and use the first one they find. A useful practice is placing a configuration file in the root of your project containing your default configuration and overriding it (if needed) with config files in different subdirectories. You can also place a configuration file in your home directory that will be used by default if there are no configuration files in your project.

The steps used to locate axe-linter.yml configuration files are:

Use the configuration file in the current directory (the directory containing the file being edited with VS Code, a JetBrains IDE, or the command prompt's current directory with axe DevTools Linter Connector).
If no configuration is found in step 1, search parent directories until an axe-linter.yml configuration file is found, stopping at your home folder if the project is in your home directory tree or the root directory if it's outside your home folder.
Use an axe-linter.yml configuration file located in your home directory (even if your project is located in a directory outside your home folder or on another drive on Windows). For example, these are the typical files used:
- /home/username/axe-linter.yml (Linux)
- /Users/username/axe-linter.yml (macOS)
- C:\Users\username\axe-linter.yml (Windows)

Searching stops when the first axe-linter.yml file is found.

Summary of Configuring axe DevTools Linter

Product	Type of Configuration	Description
axe Accessibility Linter extension for VS Code or the JetBrains plugin	One or more YAML files named `axe-linter.yml`	See Multiple Configurations.
axe Linter Connector	One or more YAML files named `axe-linter.yml`	Follows the steps in Multiple Configurations when used with the `--config` option with no parameter.
axe Linter Connector	One YAML file named filename	When used with `--config` filename.
axe Linter REST API	JSON config object	See The config Object.

Configuration Options

`element`

The element option allows you to change the emitted element based on your component's specified attribute value. For instance, you could have a custom component emit an img element in certain cases and a button element in other cases, allowing for more complex use cases.

The example configuration below specifies that the as attribute on the my-button component can change the emitted element from the default of button:

YAML:

global-components:
  my-button:
    element: button
    attributes:
      - as: <element>

JSON:

{
  "config": {
    "global-components": {
      "my-button": {
        "element": "button",
        "attributes": [
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

The example usage below emits an img element instead of the default button element because the as attribute specifies the output element:

<my-button as="img"></my-button>

The output img element will then be linted and found to be missing an alt attribute.

`exclude`

The exclude option prevents matching files from being linted. You can use wildcards and globs. Its use is mainly for the VS Code extension or JetBrains plugin and is ignored by the REST endpoint.

exclude: *.tmp

`global-components`

The global-components configuration option directs axe DevTools Linter how to map your own custom components or components from third-party libraries to native HTML elements, allowing you to lint your components as though they were native HTML elements. For example, the following configuration will treat all custom DqButton components as though they were native HTML button elements. This automatically maps every attribute on DqButton to button, thus requiring an accessible name for all DqButton components.

YAML:

global-components:
  DqButton: button

JSON:

{
  "config": {
    "global-components" {
      "DqButton": "button"
    }
  }
}

Alternatively, for components that don't map all attributes to native HTML components, you can list the attributes required for accessibility conformance using the attributes option. You can list attributes the component supports as well as rename attributes. There are three special values:

The aria-* value tells axe DevTools Linter that all attributes that start with aria- are mapped to the native HTML element as-is. Note the value ends with an asterisk.
The <text> value tells axe DevTools Linter that a property is used to set the content (the value between the open and close tags) of the native HTML element.
The <element> value tells axe DevTools Linter that the emitted element can take the value of this attribute, which lets you change the emitted element depending on the value of the specified attribute.

The following YAML example shows all the values that can be used with global-components:

global-components:
  DqButton:
    element: button
    # Ignore all attributes on <DqButton> except the following:
    attributes:
      - role # Map the role attribute from <DqButton /> to <button />
      - aria-* # Map all attributes starting with aria-
      - action: type # <DqButton action="submit" /> maps to <button type="submit" />
      - label: <text> #  <DqButton label="ABC" /> emits <button>ABC</button>
      - as: <element> # <DqButton as="img" /> emits <img> instead of <button>. (You don't have to use *as* for the attribute name.)

An equivalent JSON version (inside the config object) is as follows:

{
  "config": {
    "global-components": {
      "DqButton": {
        "element": "button",
        "attributes": [
          "role",
          "aria-*",
          {
            "action": "type"
          },
          {
            "label": "<text>"
          },
          {
            "as": "<element>"
          }
        ]
      }
    }
  }
}

Only attributes relevant to accessibility need to be in the attributes list. Element names are case-sensitive. Camel case, as shown above, is commonly used with .jsx files, but kebab case (which is used in Vue, Angular, and HTML custom elements) can be used.

For walkthroughs showing how to use the custom component mapping, see Linting Custom Components.

`global-libraries`

axe DevTools Linter has built-in support for several popular component libraries and frameworks.

The following libraries are currently supported:

react-native
@mui/material
@deque/cauldron-react

To enable library component linting, add the NPM package name of the library to the global-libraries array for YAML configuration files:

global-libraries:
  - '@mui/material'
  - '@deque/cauldron-react'
  - react-native

note

You need to quote @mui/material and @deque/cauldron-react in YAML because @ is interpreted as a reserved character.

Or the equivalent JSON configuration is shown below:

{
  "config": {
    "global-libraries": [
      "@mui/material"
    ]
  }
}

Any component with the same name as a component from the global library will be treated as that library component, allowing re-exporting and redeclaring components without losing their mapping.

For more information, see Preconfigured Component Libraries.

`overrides`

You can change how axe DevTools Linter is configured per-file by using the overrides configuration option. Multiple overrides on the same file are resolved in order. That is, the last override listed has the highest precedence.

Currently, only the linter override is supported and is used to change the linter used on the matched files.

overrides:
  - files: # An array or single string of filename(s) or glob pattern(s) that match this override setting
      - vue/**/*.html
    linter: vue # Specify that all files that match the pattern should be linted as Vue
  - files: php/**/*.html
    linter: null # Disable axe-linter for these files

`rules`

You can allow or disallow rules individually with the rules option in your configuration:

rules:
  some-rule: false # turn off rule
  other-rule: true # turn on rule

Or in the config object in your JSON REST request:

{
  "config": {
    "rules": {
      "some-rule": false,
      "other-rule": true
    }
  }
}

For information about using rules with the REST API, see The rules Property. If you want to use rules with the axe DevTools Linter connector, see Configuration File. To see the rules that axe DevTools Linter follows, see Accessibiliity Rules. See tags below for more information on using the tags option to exclude collections of rules from being processed.

`tags`

You can disallow rules as a group based on the WCAG standard they are associated with using the tags option:

tags: # Disallow all rules other than WCAG 2.1 A, WCAG 2.1 AA, and best practices.
  - wcag21a
  - wcag21aa
  - best-practices