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:
- A YAML file called axe-linter.yml included in the root of your project when using the VSCode extension, axe Accessibility Linter.
- 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.)
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
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
- For a reference to the REST APIs provided by axe DevTools Linter, see The axe DevTools Linter REST API Reference.
- For a walkthrough to creating custom-component mappings, see Linting Custom Components.
- To download the VSCode extension, see axe Accessibility Linter