aria-query

What is aria-query?

The aria-query npm package is a library that provides a set of utilities for querying and interacting with ARIA (Accessible Rich Internet Applications) roles, states, and properties. It is designed to help developers create more accessible web applications by providing an easy way to access and manipulate ARIA attributes.

What are aria-query's main functionalities?

Querying ARIA roles

This feature allows developers to query information about ARIA roles. The code sample demonstrates how to import the 'roles' map from the package and retrieve information about the 'button' role.

import { roles } from 'aria-query';
console.log(roles.get('button'));

Querying ARIA states and properties

This feature enables querying ARIA states and properties. The code sample shows how to import the 'aria' map and get details about the 'aria-hidden' property.

import { aria } from 'aria-query';
console.log(aria.get('aria-hidden'));

Mapping HTML elements to ARIA roles

This feature provides a mapping between HTML elements and their corresponding ARIA roles. The code sample illustrates how to get the ARIA roles associated with the 'button' HTML element.

import { elementRoles } from 'aria-query';
const map = elementRoles.get('button');
console.log(map);

Other packages similar to aria-query

react-aria

React Aria is a library of React Hooks that provides accessible UI primitives for building React applications. It is similar to aria-query in that it helps with accessibility concerns but is more focused on providing ready-to-use components and hooks for React.

ally.js

ally.js is a JavaScript library that simplifies certain accessibility features, interactions, and behaviors. It provides a higher-level abstraction over ARIA attributes and focuses on enabling accessible interactions, which is a broader scope compared to the more attribute-focused aria-query.

README

NOTICE: The API for ARIA Query is very much under development until a major version release. Please be aware that data structures might change in minor version releases before 1.0.0 is released.

ARIA Query

Programmatic access to the WAI-ARIA 1.1 Roles Model.

Utilities

Roles

import { roles } from 'aria-query';

A Map of role names to the role definition. For example:

let alertRole = roles.get('alert');
/**
 * Value of alertRole
 * {
 *   "requiredProps": [],
 *   "props": [
 *     "aria-expanded",
 *     "aria-atomic",
 *     "aria-busy",
 *     "aria-controls",
 *     "aria-describedby",
 *     "aria-disabled",
 *     "aria-dropeffect",
 *     "aria-flowto",
 *     "aria-grabbed",
 *     "aria-haspopup",
 *     "aria-hidden",
 *     "aria-invalid",
 *     "aria-label",
 *     "aria-labelledby",
 *     "aria-live",
 *     "aria-owns",
 *     "aria-relevant"
 *   ],
 *   "abstract": false,
 *   "interactive": false,
 *   "childrenPresentational": false,
 *   "baseConcepts": [],
 *   "relatedConcepts": [{
 *     "module": "XForms",
 *     "concept": {
 *       "name": "alert"
 *     }
 *   }]
 * }

Elements to Roles

import { elementRoles } from 'aria-query';

HTML Elements with inherent roles are mapped to those roles. Some elements, such as th, are only mapped to a role when they express specific attributes. In the case of th, the element must have an attribute scope="col" to be mapped to the columnheader role.

Map {
  '{"name":"article"}' => Set { 'article' },
  '{"name":"button"}' => Set { 'button' },
  '{"name":"td"}' => Set { 'cell', 'gridcell' },
  '{"name":"input","attributes":[{"name":"type","value":"checkbox"}]}' => Set { 'checkbox' },
  '{"name":"th","attributes":[{"name":"scope","value":"col"}]}' => Set { 'columnheader' },
  '{"name":"select"}' => Set { 'combobox', 'listbox' },
  '{"name":"menuitem"}' => Set { 'command', 'menuitem' },
  '{"name":"dd"}' => Set { 'definition' },
  '{"name":"dfn"}' => Set { 'definition' },
  '{"name":"figure"}' => Set { 'figure' },
  '{"name":"form"}' => Set { 'form' },
  '{"name":"table"}' => Set { 'grid', 'table' },
  '{"name":"fieldset"}' => Set { 'group' },
  '{"name":"h1"}' => Set { 'heading' },
  '{"name":"h2"}' => Set { 'heading' },
  '{"name":"h3"}' => Set { 'heading' },
  '{"name":"h4"}' => Set { 'heading' },
  '{"name":"h5"}' => Set { 'heading' },
  '{"name":"h6"}' => Set { 'heading' },
  '{"name":"img"}' => Set { 'img' },
  '{"name":"a"}' => Set { 'link' },
  '{"name":"link"}' => Set { 'link' },
  '{"name":"ol"}' => Set { 'list' },
  '{"name":"ul"}' => Set { 'list' },
  '{"name":"li"}' => Set { 'listitem' },
  '{"name":"nav"}' => Set { 'navigation' },
  '{"name":"option"}' => Set { 'option' },
  '{"name":"input","attributes":[{"name":"type","value":"radio"}]}' => Set { 'radio' },
  '{"name":"frame"}' => Set { 'region' },
  '{"name":"rel"}' => Set { 'roletype' },
  '{"name":"tr"}' => Set { 'row' },
  '{"name":"tbody"}' => Set { 'rowgroup' },
  '{"name":"tfoot"}' => Set { 'rowgroup' },
  '{"name":"thead"}' => Set { 'rowgroup' },
  '{"name":"th","attributes":[{"name":"scope","value":"row"}]}' => Set { 'rowheader' },
  '{"name":"input","attributes":[{"name":"type","value":"search"}]}' => Set { 'searchbox' },
  '{"name":"hr"}' => Set { 'separator' },
  '{"name":"dt"}' => Set { 'term' },
  '{"name":"textarea"}' => Set { 'textbox' },
  '{"name":"input","attributes":[{"name":"type","value":"text"}]}' => Set { 'textbox' }
}

The map of elements to roles is keyed by stringified HTML concept. An HTML concept corresponds to the baseConcepts and relatedConcepts of an ARIA role. Concepts exist in the context of a module: HTML, XForms, Dublin Core, for example. The concept representation is an object with a name property (the element name) and an optional attributes array. Use JSON.parse on the map key to rehydrate the HTML concept for inspection.

The roles are provided in a Set.

Role to element

import { roleElements } from 'aria-query';

ARIA roles are mapped to the HTML Elements with the same inherent role. Some roles, such as columnheader are only mapped to an HMTL element that expresses specific attributes. In the case of th, the element must have an attribute scope="col" to be mapped to the columnheader role.

Map {
  'article' => Set { '{"name":"article"}' },
  'button' => Set { '{"name":"button"}' },
  'cell' => Set { '{"name":"td"}' },
  'checkbox' => Set { '{"name":"input","attributes":[{"name":"type","value":"checkbox"}]}' },
  'columnheader' => Set { '{"name":"th","attributes":[{"name":"scope","value":"col"}]}' },
  'combobox' => Set { '{"name":"select"}' },
  'command' => Set { '{"name":"menuitem"}' },
  'definition' => Set { '{"name":"dd"}', '{"name":"dfn"}' },
  'figure' => Set { '{"name":"figure"}' },
  'form' => Set { '{"name":"form"}' },
  'grid' => Set { '{"name":"table"}' },
  'gridcell' => Set { '{"name":"td"}' },
  'group' => Set { '{"name":"fieldset"}' },
  'heading' => Set { '{"name":"h1"}', '{"name":"h2"}', '{"name":"h3"}', '{"name":"h4"}',  '{"name":"h5"}', '{"name":"h6"}' },
  'img' => Set { '{"name":"img"}' },
  'link' => Set { '{"name":"a"}', '{"name":"link"}' },
  'list' => Set { '{"name":"ol"}', '{"name":"ul"}' },
  'listbox' => Set { '{"name":"select"}' },
  'listitem' => Set { '{"name":"li"}' },
  'menuitem' => Set { '{"name":"menuitem"}' },
  'navigation' => Set { '{"name":"nav"}' },
  'option' => Set { '{"name":"option"}' },
  'radio' => Set { '{"name":"input","attributes":[{"name":"type","value":"radio"}]}' },
  'region' => Set { '{"name":"frame"}' },
  'roletype' => Set { '{"name":"rel"}' },
  'row' => Set { '{"name":"tr"}' },
  'rowgroup' => Set { '{"name":"tbody"}', '{"name":"tfoot"}', '{"name":"thead"}' },
  'rowheader' => Set { '{"name":"th","attributes":[{"name":"scope","value":"row"}]}' },
  'searchbox' => Set { '{"name":"input","attributes":[{"name":"type","value":"search"}]}' },
  'separator' => Set { '{"name":"hr"}' },
  'table' => Set { '{"name":"table"}' },
  'term' => Set { '{"name":"dt"}' },
  'textbox' => Set { '{"name":"textarea"}', '{"name":"input","attributes":[{"name":"type","value":"text"}]}' }
}

The HTML concept values are provided in a Set.

An HTML concept corresponds to the baseConcepts and relatedConcepts of an ARIA role. Concepts exist in the context of a module: HTML, XForms, Dublin Core, for example.
The HTML concept values are stringified. Use JSON.parse on the map key to rehydrate the HTML concept for inspection. The concept representation is an object with a name property (the element name) and an optional attributes array.