Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Accessibility audit tooling for the web (beta)

Subscribe to updates I use a11y

Statistics on a11y

Number of watchers on Github 1461
Number of open issues 29
Average time to close an issue 7 days
Main language JavaScript
Average time to merge a PR 1 day
Open pull requests 9+
Closed pull requests 10+
Last commit over 3 years ago
Repo Created over 5 years ago
Repo Last Updated about 2 years ago
Size 42 MB
Homepage http://addyosmani...
Organization / Authoraddyosmani
Latest Releasev0.5.0
Page Updated
Do you use a11y? Leave a review!
View open issues (29)
View a11y activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating a11y for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

npm version Build Status Dependency Status

Easy accessibility audits powered by the Chrome Accessibility Tools


$ npm install --global a11y

PhantomJS, which is used for generating the screenshots, is installed automagically, but in some rare cases it might fail to and you'll get an Error: spawn EACCES error. Download PhantomJS manually and reinstall a11y if that happens.

CLI usage

Run an audit against a URL:

$ a11y todomvc.com

Or multiple URLs:

$ a11y todomvc.com google.com


Also works fine against localhost:

$ a11y localhost:9000

And local files:

$ a11y index.html

Even with glob patterns:

$ a11y '**/*.html'


Query help:

$ a11y --help

Customise viewport size

Type: string
Default: 1024x768

$ a11y --viewport-size=800x600

Set a custom delay before capturing the page

Type: number (seconds)
Default: 1

$ a11y --delay=5

Useful when the site does things after load that you want to capture.

Verbose mode:

$ a11y <url> --verbose

Write audit to file:

$ a11y <url> > audit.txt

Module usage

Audit a remote URL and generate an accessibility report:

const a11y = require('a11y');

a11y('twitter.com', (err, reports) => {
    const audit = reports.audit; // `a11y` Formatted report
    const report = reports.report; // DevTools Accessibility Audit formatted report

Work with the output of reports.audit:

const a11y = require('a11y');

a11y('twitter.com', (err, reports) => {
    for (const report of reports) {
        // Result will be PASS, FAIL or NA
        if (report.result === 'FAIL') {
            // el.heading
            // el.severity
            // el.elements

Passing options:

const a11y = require('a11y');

const options = {
    viewportSize: '800x600'

a11y('twitter.com', options, (err, reports) => {
    // ...

Currently, the only suported option is:

  • viewportSize (String in format WIDTHxHEIGHT, eg 800x600)

Interpreting results

To interpret how to fix individual issues in an audit, see the Audit Rules section of the Accessibility Developer Tools project.

Per the Accessibility Developer Tools, the results in an audit may be one of three types:

  • PASS - implies that there were elements on the page that may potentially have failed this audit rule, but they passed. Congratulations!
  • FAIL - This implies that there were elements on the page that did not pass this audit rule. This is the only result you will probably be interested in.
  • NA - This implies that there were no elements on the page that may potentially have failed this audit rule. For example, an audit rule that checks video elements for subtitles would return this result if there were no video elements on the page.

Build-system integration

If you use Grunt, grunt-a11y is a task by Joo Figueiredo that uses a11y under the hood.


At this time, this module should be relatively reliable when auditing for accessibility issues in static sites.

We are actively working on exploring support for complex web-applications, including those using JavaScript libraries such as Polymer, Angular and React/Flux. We hope to bring this work to the main master branch once it is considered stable.



a11y open issues Ask a question     (View All Issues)
  • almost 4 years Add --quiet option for error-only output
  • almost 4 years Feature Request : ADT configuration
  • about 4 years PhantomJS Issues
  • over 4 years Break the build for html fragments in gulp
  • over 4 years False positives on custom elements that do not appear with the Chrome extension
  • over 4 years option for evaluating html fragments
  • almost 5 years 'null' is not an object (evaluating 'axs.properties.findTextAlternatives
  • about 5 years Not working for me on static local files.
  • about 5 years Disable PhantomJS Redirects
  • over 5 years contrast of some text insufficient
  • over 5 years results contain lots of headings without content?
  • over 5 years new audit button
  • over 5 years "role=main should only appear on significant elements"
  • over 5 years What is the difference between a11y and pa11y
  • over 5 years Improve auditing for webapps
  • over 5 years Author Grunt task for the module
  • over 5 years Show code snippet, filename, and line number for violations
a11y open pull requests (View All Pulls)
  • Allow users to configure ADT with the scope selector option
  • Add a JUnit report
  • Update deprecated phantomjs to phantomjs-prebuilt
  • Added in the ability to pass in a phantomjs configuration file.
  • Allows for custom headers to be sent, helpful for Authorization
  • Fix typos
  • add support for basic auth
  • Update README.md
  • Use require.resolve to locate node_module content
a11y questions on Stackoverflow (View All Questions)
  • How to supress keys caught by iron-a11y-keys
  • Imposible to use core-a11y-keys with Inputs
  • Ionic, Crosswalk, TalkBack, and Accessibility (A11Y)
  • How to make iron-a11y-keys work on the entire page?
  • Useful tools for a11y automation on iOS
  • When should a "hidden" element be available to a screen reader (for accessibility, a11y)?
a11y list of languages used
a11y latest release notes
v0.5.0 0.5.0

Dropped support for Node.js 0.10 and 0.12.

v0.4.0 0.4.0
  • Additional rule properties are now exposed in reports
  • Dependencies bumped
  • We now use XO
Other projects in JavaScript