Access ARIA information from JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib return empty description if same as name Jul 7, 2018
test query: fix getAttribute() on conflicts with native semantics May 3, 2018
.gitignore Gardening Feb 3, 2018
.travis.yml bump version to 0.2.6 Jul 7, 2018
LICENSE Create LICENSE Mar 12, 2017
Makefile migrate from phantomjs to chrome-headless Mar 6, 2018 fix links in README Dec 28, 2018


WAI-ARIA allows websites to provide additional semantics to assistive technologies. Roles and attributes can be set either explicitly (e.g. <span role="link">click me</span>) or implicitly (<a href="//">click me</a> implicitly has the role "link").

While the implicit mappings make authoring accessible websites simpler, it makes the task of calculating an element's role and attributes more complicated. This library takes care of exactly that.


npm install aria-api

This installation method works best if you use tools like webpack or browserify. There is also an UMD build included as dist/aria.js.


var aria = require('aria-api'):

aria.querySelector('landmark').forEach(function(landmark) {
    if (!aria.matches(landmark, ':hidden')) {
        var role = aria.getRole(landmark);
        var name = aria.getName(landmark);
        console.log(role, name);


Calculate an element's role.

Note that this will return only the most specific role. If you want to know whether an element has a role, use matches() instead.

getAttribute(element, attribute)

Calculate the value of an element's attribute (state or property). The "aria-" prefix is not included in the attribute name.


Calculate an element's name according to the Accessible Name and Description Computation.


Calculate an element's description according to the Accessible Name and Description Computation.

matches(element, selector)

Similar to Element.matches(), this allows to check whether an element matches a selector. A selector can be any of the following:

  • role: Matches if the element has the specified role. This also works for hierarchical roles such as "landmark".
  • :attribute: Matches if the attribute is truthy. The "aria-" prefix is not included in the attribute name.
  • [attribute="value"]: Matches if the value of the attribute converted to string equals the specified value.

Note that combinations of selectors are not supported (e.g. main link, link:hidden, :not(:hidden)). The single exception to this rule are comma-separated lists of roles, e.g. link,button.

querySelector(element, selector)

Similar to Element.querySelector(). See matches() for details.

querySelectorAll(element, selector)

Similar to Element.querySelectorAll(). See matches() for details.

closest(element, selector)

Similar to Element.closest() See matches() for details.

What is this for?

First of all, I thought that something like this should exist. I currently use it for a11y-outline, a web extension that generates outlines based on WAI-ARIA roles.

That said, this is what I think it could also be used for:

  • Providing features based on the additional information provided by ARIA, e.g. landmark navigation.
  • Tools helping developers with improving accessibility.


  • This is a pet project. I do not have the time to do extensive testing and may skip some details now and then. I am happy to receive bug reports and pull requests though.
  • This library does not do any validity checks. Invalid attributes or roles will not produce any warnings.
  • In order to calculate the "hidden" attribute, Window.getComputedStyle() is called. This only seems to return reliable values if the element is attached to document.

Related projects