Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Check for accessibility issues on critical pages of your Netlify website.

🚧 Note: This plugin is pre-release software. Until version 1.0.0 is released, its API could change at any time. If you experience unexpected behavior while using this plugin, check the changelog for any changes you might have missed, and please feel free to report an issue or submit a pull request about any issues you encounter.

What does this plugin do?

This plugin uses pa11y (which in turn uses axe-core) to check your Netlify project for accessibility issues.

If issues are found, the plugin generates a report which provides:

  • the path to the HTML file in which the error was found
  • a description of the error with a link to the relevant Deque University rule
  • the name of the error within the aXe API
  • the path to the the DOM element associated with the error
  • the DOM element itself
  • the total number of issues on the page
  • the sum of all issues across all pages that were checked

By default, the plugin checks all your site's pages for violations of WCAG 2.1 level AA, and fails the site build if any a11y issues are found.


The demo site is an Eleventy blog containing some pages that have accessibility issues:

With these errors, the logs for the demo look like this:

Screenshot of demo site build log.

Text from screnshot of demo site build log
9:49:36 PM: Results for URL: file:///opt/build/repo/demo/404.html
9:49:36 PM:  • Error: ARIA hidden element must not contain focusable elements (
9:49:36 PM:    ├── aria-hidden-focus
9:49:36 PM:    ├── #content-not-found. > a
9:49:36 PM:    └── <a class="direct-link" href="#content-not-found." aria-hidden="true">#</a>
9:49:36 PM:  • Error: Elements must have sufficient color contrast (
9:49:36 PM:    ├── color-contrast
9:49:36 PM:    ├── html > body > main > p > a
9:49:36 PM:    └── <a href="/" style="color:#aaa">home</a>
9:49:36 PM: 2 Errors
9:49:36 PM: Results for URL: file:///opt/build/repo/demo/posts/2018-05-01/index.html
9:49:36 PM:  • Error: Images must have alternate text (
9:49:36 PM:    ├── image-alt
9:49:36 PM:    ├── html > body > main > div:nth-child(2) > figure > img
9:49:36 PM:    └── <img src="/img/cats-570x720.png" width="570" height="720">
9:49:36 PM: Creating deploy upload records
9:49:36 PM: 1 Errors
9:49:36 PM: Results for URL: file:///opt/build/repo/demo/contact-me/index.html
9:49:36 PM:  • Error: Form elements must have labels (
9:49:36 PM:    ├── label
9:49:36 PM:    ├── html > body > main > div:nth-child(2) > form > textarea
9:49:36 PM:    └── <textarea height="auto" rows="10" width="100%" style="width: 100%"></textarea>
9:49:36 PM: 1 Errors
9:49:36 PM: 4 accessibility issues found! Check the logs for more information.

Installation via the Netlify UI

To install the plugin in the Netlify UI, use this direct in-app installation link or go to the plugins directory.

When installed this way, the plugin follows its default behavior, which is to check all your site's pages for violations of WCAG 2.1 level AA, and fail the site build if any a11y issues are found.

To change the plugin's behavior, you'll want to install it throigh your netlify.toml file.

Installation via the netlify.toml file

First, install the plugin as a dev dependency. If you're using NPM to manage your packages, run the following:

npm install --save-dev @netlify/plugin-a11y

If you're using Yarn, run the following:

yarn add --dev @netlify/plugin-a11y

Next, add @netlify/plugin-a11y to the plugins section of your netlify.toml file.

  package = "@netlify/plugin-a11y"

⚠️ In .toml files, whitespace is important! Make sure package is indented two spaces.

If you want to use the plugin's default settings (check all pages of your site for violations of WCAG 2.1 level AA; fail the netlify build if issues are found), this is all you need to do. If you want to change the way the plugin behaves, read on to the next section.


If you've installed the plugin via netlify.toml, you can add a [[plugins.inputs]] field to change how the plugin behaves. This table outlines the inputs the plugin accepts. All of them are optional.

Input name Description Value type Possible values Default value
checkPaths Indicates which pages of your site to check Array of strings Any directories or HTML files in your project ['/']
failWithIssues Whether the build should fail if a11y issues are found Boolean true or false true
ignoreDirectories Directories that should not be checked for a11y issues Array of strings Any directories in your project []
ignoreElements Indicates elements that should be ignored by a11y testing String (CSS selector) Comma-separated string of CSS selectors undefined
ignoreGuidelines Indicates guidelines and types to ignore (pa11y docs) Array of strings Comma-separated string of WCAG Guidlines []
wcagLevel The WCAG standard level against which pages are checked String 'WCAG2A' or 'WCAGA2A' or 'WCAG2AAA' 'WCAG2AA'

Here's how these inputs can be used in netlify.toml, with comments to explain how each input affects the plugin's behavior:

  package = "@netlify/plugin-a11y"
    # Check all HTML files in this project (the default behavior)
    checkPaths = ['/']
    # Do not fail the build if a11y issues are found
    failWithIssues = false
    # Ignore all HTML files in `/admin`
    ignoreDirectories = ['/admin']
    # Ignore any accessibility issues associated with an element matching this selector
    ignoreElements = '.jumbotron > h2'
    # Ignore any accessibility issues associated with this rule code or type
    ignoreGuidelines = ['WCAG2AA.Principle1.Guideline1_4.1_4_6.G17']
    # Perform a11y check against WCAG 2.1 AAA
    wcagLevel = 'WCAG2AAA'


Build a more accessible web! Run your critical pages through pa11y and fail build if accessibility failures are found.


Code of conduct





No packages published