Accessible Rich Internet Applications (WAI-ARIA) 1.0

Skip to Content (Press Enter)

2. Using WAI-ARIA

This section is informative.

Complex web applications become inaccessible when assistive technologies cannot determine the semantics behind portions of a document or when the user is unable to effectively navigate to all parts of it in a usable way (see the WAI-ARIA Primer [ARIA-PRIMER]). WAI-ARIA divides the semantics into roles (the type defining a user interface element) and states and properties supported by the roles.

Authors need to associate elements in the document to a WAI-ARIA role and the appropriate states and properties (aria-* attributes) during its life-cycle, unless the elements already have the appropriate implicit ARIA semantics for states and properties. In these instances the equivalent host language states and properties take precedence to avoid a conflict while the role attribute will take precedence over the implicit role of the host language element.

Authors need to associate elements in the document to a WAI-ARIA role and the appropriate states and properties (aria-*) during its life-cycle.

2.1. WAI-ARIA Roles

An WAI-ARIA role is set on an element using a role attribute, similar to the role attribute defined in the XHTML Role Attribute Module [XHTML-ROLES].

<li role="menuitem">Open file…</li>

The roles defined in this specification include a collection of document landmarks and the WAI-ARIA role taxonomy.

The roles in this taxonomy and their expected behaviors are modeled using RDF/OWL [OWL]. Features of the role taxonomy provide the following information for each role:

Attaching a role gives assistive technologies information about how to handle each element.

2.2. WAI-ARIA States and Properties

WAI-ARIA provides a collection of accessibility states and properties which are used to support platform accessibility APIs on the various operating system platforms. assistive technologies may access this information through an exposed user agent DOM or through a mapping to the platform accessibility API. When combined with roles, the user agent can supply the assistive technologies with information to render the information to the user at any instance in time. Changes in states or properties will result in a notification to assistive technologies, which may alert the user that a change has occurred.

In the following example, a list item (html:li) has been used to create a checkable menu item, and JavaScript events will capture mouse and keyboard events to toggle value of aria-checked. A role is used to make the behavior of this simple widget known to the user agent. Attributes that change with user actions (such as aria-checked) are defined in the states and properties section.

<li role="menuitemcheckbox" aria-checked="true">Sort by Last Modified</li>

Some accessibility states, called managed states, are controlled by the user agent. Examples of managed state include keyboard focus and selection. Managed states often have corresponding CSS pseudo-classes (such as :focus and ::selection) to define style changes. In contrast, the states in this specification are typically controlled by the author and are called unmanaged states. Some states managed by the user agent, such as aria-posinset and aria-setsize, can be overridden by web application authors, but the author can override them if the DOM is incomplete and would cause the user agent calculation to be incorrect. User agents map both managed and unmanaged states to the platform accessibility APIs.

Most modern user agents support CSS attribute selectors ([CSS]), and can allow the author to create UI changes based on WAI-ARIA attribute information, reducing the amount of scripts necessary to achieve equivalent functionality. In the following example, a CSS selector is used to determine whether or not the text is bold and an image of a check mark is shown, based on the value of the aria-checked attribute.

[aria-checked="true"] { font-weight: bold; }
[aria-checked="true"]:before { background-image: url(checked.gif); }

Note: At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise force the browser to redraw the styles properly.

If CSS is not used to toggle the visual representation of the check mark, the author could include additional markup and scripts to manage an image that represents whether or not the menuitemcheckbox is checked.

<li role="menuitemcheckbox" aria-checked="true">
  <img src="checked.gif" role="presentation" alt=""> <!-- additional scripts required to toggle image source -->
  Sort by Last Modified

2.3. Managing Focus

An application should always have an element with focus when in use, as applications require users to have a place to provide user input. The element with focus should not be destroyed or hidden. It should also not be scrolled off-screen unless through user intervention. All interactive objects should be focusable. All parts of composite interactive objects should either be focusable or have a documented alternative method to achieve their function, such as a keyboard shortcut. There should be an obvious, discoverable way, either through tabbing or other standard navigation techniques, for keyboard users to move the focus to any interactive element. See User Agent Accessibility Guidelines, Guideline 9 ([UAAG], Guideline 9).

When using standard HTML and basic WAI-ARIA widgets, application developers can simply manipulate the tab order or use a script to create keyboard shortcuts to elements in the document. Use of more complex widgets requires the author to manage focus within them. SVG Tiny provides a similar focus mechanism that, by default, follows document source code order and which should be implemented using system dependent input facilities (the TAB key on most desktop computers). SVG authors may place elements in the navigation order by manipulating the focusable property and they may dynamically specify the navigation order by modifying elements' navigation attributes.

WAI-ARIA includes a number of "managing container" widgets, also known as "composite" widgets. Typically, the container is responsible for tracking the last descendant which was active (the default is usually the first item in the container). When a previously focused container is refocused, the new active descendant should be the same element as the active descendant when the container was last focused. For example, if the second item of a tree group was the active descendant when the user tabbed out of the tree group, then the second item of the tree group remains the active descendant when the tree group gets focus again. The user may also activate the container by clicking on one of the descendants within it.

When something in the container has focus, the user may navigate through the container by pressing additional keys such as the arrow keys to move relative to the current item. Any additional press of the main navigation key (generally the Tab key) will move out of the container to the next widget.

For example, a grid may be used as a spreadsheet with thousands of gridcell elements, all of which may not be present in the document at one time. This requires their focus to be managed by the container using the aria-activedescendant attribute, on the managing container element, or by the container managing the tabindex of its child elements and setting focus on the appropriate child. For more information, see Providing Keyboard Focus in WAI-ARIA Authoring Practices ([ARIA-PRACTICES]).

Containers that manage focus in this way are:

More information on managing focus can be found in the Using Tabindex to Manage Focus Among Widgets section of the WAI-ARIA Authoring Practices [ARIA-PRACTICES].