axe Accessibility Linter

Coding for accessibility made easy.

Features

• Checks React (.js .jsx .tsx), Vue (.vue), Angular (.component.html), HTML (.html .htm), and Markdown (.md .markdown) files so you can avoid common accessibility defects. Inline Angular templates are not currently supported.
• Consistent with the open-source axe-core rules engine to provide early warnings of real accessibility defects -- zero false positives, so you don't have to write a bunch of ignore flags.
• Dedicated react-native rules
• Support for popular component libraries like @mui/material (BETA)
• Shareable project-specific configurations, so your team can work from the same accessibility standard or rules.

Quickstart

Once the plugin is installed, axe-linter installs and configures itself automatically. This can sometimes take a few minutes. Once this step is completed, axe-linter will start running on compatible source files.

CI/CD Integration

Axe-linter is now available on a multitude of other platforms! We currently provide integrations for:

• GitHub Actions
• Git Pre-Commit Hooks
• SonarQube
• Jenkins, Azure DevOps, CircleCI, and more!

To start your free trial head to deque.com. In the mean time, check out all the details on axe-linter's other integrations or our full axe-linter platform documentation

Settings

The rules axe-linter uses and components it can lint are configurable by adding a file called axe-linter.yml at your project's root level. You can enable and disable specific rules individually, or by groups. You can also configure axe-linter to work with custom components.

Rule Configuration

You can enable/disable rules individually with the rules entry:

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

You can also disable rules as a group based on WCAG standard they are associated with using the tags entry:

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

Available Accessibility Tags

The following tags are available for configuration in axe-linter:

Available Rules

axe-linter has the following rules, by default all are enabled:

• area-alt
• aria-allowed-attr
• aria-allowed-role
• aria-command-name
• aria-dialog-name
• aria-input-field-name
• aria-meter-name
• aria-progressbar-name
• aria-required-attr
• aria-roles
• aria-roledescription
• aria-text
• aria-toggle-field-name
• aria-tooltip-name
• aria-treeitem-name
• aria-valid-attr-value
• aria-valid-attr
• autocomplete-valid
• button-name
• definition-list
• empty-heading
• empty-table-header
• frame-title
• html-has-lang
• html-lang-valid
• image-alt
• input-button-name
• input-image-alt
• label
• link-name
• list
• meta-refresh
• meta-viewport
• nested-interactive
• object-alt
• presentation-role-conflict
• role-img-alt
• select-name
• svg-img-alt
• tabindex
• valid-lang

React-native rules:

React-native rules are off by default, to enable add the following to your axe-linter.yml file:

global-libraries:
  - react-native

Once enabled, the following rules for react-native are part of linting .js, .jsx, and .tsx files.

• image-has-accessibility-label
• has-accessibility-role
• has-valid-accessibility-actions
• has-valid-accessibility-role
• has-valid-accessibility-state
• has-valid-accessibility-value

Markdown(MD) Rules:

• heading-order

Global Components

The global-components setting in axe-linter.yml tells axe-linter how to map your own custom components or components from third party libraries to native HTML elements. This allows you to lint your components as though they were native HTML elements. For example, the following 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.

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 property. You can list attributes the component supports, as well as rename attributes. There are two wildcard values - aria-* tells axe-linter that all attributes that start with aria- are mapped to the native HTML element as-is. The <text> value tells axe-linter that a property is used to set the content of the native HTML element.

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>

Only attributes relevant for accessibility need to be in the attributes list. Element names are case sensitive. CamelCase as shown above as a common JSX example, but kebab-case which is used in Vue, Angular, and HTML custom elements can be used.

For full documentation on our custom component support, head to our docs site

If you need a hand setting up your global-components configuration, drop us a line and we'll be happy to help.

Global Libraries (BETA)

Axe-linter comes with built-in support for a number of 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 in your axe-linter.yml file:

global-libraries:
  - '@mui/material'

Any component with the same name of a component from the global library will be treated as that library component. This allows re-exporting and redeclaring components without losing its mapping.

The following libraries are currently supported:

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

BETA: We are looking for feedback on this new feature. If you discover any issues, please reach out for support. If this feature is a success, expect more libraries to get added in the future.

Support

• To report an issue or request a feature check out our issue reporting page
• To get in ontact with the axe-linter development team and other axe-linter users join our accessibility slack channel

Telemetry

Axe-linter gathers a minimal amount of telemetry in order to assist in monitoring the plugin's heartbeat. The collected data is limited to the date and time of scans, the axe-linter engine version, and identification of the data as being axe-linter related. We've also added telemetry to gather all error messages as needed to help provide a better end user experience.