Free Trial

Configuring axe DevTools Linter

Link to Configuring axe DevTools Linter copied to clipboard

Reference guide for configuring axe DevTools Linter

Free Trial

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

Types of Configuration

There are two types of configuration used with axe DevTools Linter:

  1. A YAML file called axe-linter.yml included in the root of your project when using the VSCode extension, axe Accessibility Linter.
  2. A config object included in the REST request for the [/lint-source endpoint](axe-linter-rest-apis#the-lint-endpoint-lint-source]. (This configuration is a JSON object.) See The config Object for more information.

Example Configurations

The following YAML example demonstrates a simple configuration that uses the rules option for use with the VSCode extension:

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.

Configuration Options

exclude

The exclude option excludes matching files from being linted. You can use wildcards and globs. Its use is mainly for the VSCode extension 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 two wildcard 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 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" /> become <button>ABC</button>

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

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

Only attributes relevant for 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 a walkthrough showing how to use the custom component mapping, see Linting Custom Components.

global-libraries

axe DevTools Linter comes with built-in support for several popular libraries and frameworks. When enabled, components from those libraries are tested for accessibility in the same way native HTML elements can be.

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

global-libraries:
  - '@mui/material'

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.

The following libraries are currently supported:

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

We are looking for feedback on this new feature. If you discover any issues, please see our issue reporting page. If this feature is a success, expect more libraries to be added.

overrides

You can change how axe DevTools Linter is configured on a per-file basis 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 of filenames or glob patterns 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 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

See Also

Is this page helpful?

Help us improve this page

Try axe DevTools® Linter

Free Trial

Still need help?