Accessible Rich Internet Applications (WAI-ARIA) Version 1.0

1.1. Scope

The design aims of creating this specification include:

• Define what state information may be controlled by the author.
• Support device independence - new devices coming on line, such as telephones, PDA's, tablets, televisions, etc. mean that it is imperative to have a design that allows you to author once and render in different ways on different devices, rather than authoring new versions of the document for each type of device.
• Improve the accessibility of dynamic content such as that generated by script.
• Provide for interoperability with Assistive Technologies.

This draft currently handles two aspects of roles: GUI functionality and structural relationships of the element. For more information see the WAI-ARIA Primer [ARIA-PRIMER] for the use of roles in making interactive content accessible.

The role taxonomy is designed in part to support the common roles found in platform accessibility APIs. Reference to roles found in this taxonomy by dynamic Web content may be used to support interoperability with assistive technologies.

The schema to support this standard has been designed to be extensible so that custom roles can be created by extending base roles. This allows user agents to support at least the base role, and user agents that support the custom role can provide enhanced access. Note that much of this could be formalized in XML Schema [XSD]. However, being able to define similarities between roles, such as baseConcepts and more descriptive definitions, would not be available in XSD. While this extensibility is possible, this version of the specification does not define how this extension is to be achieved.

WAI-ARIA is supported by a set of informative resources. In addition to the WAI-ARIA Roadmap, the WAI-ARIA Primer [ARIA-PRIMER] provides a basic introduction to the concepts behind and reason for ARIA, and the WAI-ARIA Best Practices [ARIA-PRACTICES] describe recommended usage patterns for Web content developers. These documents are intended to help authors learn the practice of putting WAI-ARIA to use.

1.2. Use Cases

Keyboard accessible content helps users of alternate input devices. The new semantics when combined by our style guide work will allow alternate input solutions to facilitate command and control on via an alternate input solution.

Low vision solutions benefit from ARIA markup in that the improved keyboard navigation helps people with extremely low vision. Low vision solutions offer a degree of screen reading functionality (like AI Squared's Zoom text). Furthermore, ARIA introduces navigation landmarks both through our taxonomy and the XHTML role landmarks which dramatically improves keyboard navigation productivity. This is a huge benefit for alternate input solutions as well.

ARIA will also be used to assist people with cognitive impairments. The additional semantics will allow authors to restructure and substitute alternative content in adaptive Web 2.0 solutions.

Assistive technology needs the ability to support alternative input forms by getting and setting the current value of widgets. AT also needs to determine what objects are selected, and manage widgets that allow multiple selections.

Todo: fill out using content from discussion on list relating to Henri Sivonen's feedback

ARIA is used as a supplement for native language semantics, not a replacement. When the host language provides a feature that is equivalent to the ARIA feature, use the host language feature. ARIA should only be used in cases where the host language lacks the needed role, state, or property indicator. Use a host language feature that is as similar as possible to the ARIA feature, then refine the meaning using ARIA. For instance, a multiselectable grid could be implemented as a table, and then ARIA used to clarify that it is a grid, not just a table. This allows for the best possible fallback for user agents that do not support ARIA and preserves the integrity of the host language semantics.

2.1. WAI-ARIA Roles

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

<div role = "checkbox">

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

The Roles in this taxonomy were modeled using RDF/OWL [OWL] to build rich descriptions of the expected behaviors of each role. Features of the role taxononmy provide the following information for each role:

• describes the context of a role, for example a listitem should be inside a list;
• defines a hierarchy of roles with related properties, for example a directory is a type of list;
• makes use of OWL to provide a type hierarchy allowing for semantic inheritance similar to a class hierarchy;
• makes references to related concepts in other specifications;
• provides descriptions for each role;
• describes what states are supported for each role, for example, a checkbox supports being checked.

Attaching a role from the role taxonomy to an element in the document gives assistive technology the information it needs to handle an element correctly.

2.2. WAI-ARIA States and Properties

ARIA provides a collection of accessibility states and properties which are used to support platform accessibility APIs on the various operating system platforms. Assistive technology 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 technology 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 an assistive technology to let them know that a change in behavior has occurred.

In the following example, a span has been used to create a checkbox which in this case has three possible states. A role is used to make the behavior of this simple widget known to the user agent. Properties that may change with user actions (such as checked) are defined in the States and Properties.

<span role="checkbox" aria-checked="mixed"
    onkeydown="return checkBoxEvent(event);" 
    onclick="return checkBoxEvent(event);" >
  A checkbox label
</span>

It should be noted that some accessibility state information is managed and controlled by the user agent. These are called managed states. Often these states have corresponding CSS pseudo-classes to reflect necessary style changes. An example of a managed state is focus. In contrast, the states in this specification are typically controlled by the author and are called unmanaged states. Some states are managed by the UA but the author can override them, such as posinset and setsize. The author should override those only if the DOM is not complete and thus the UA calculation would be incorrect. Both managed and unmanaged states are mapped to the platform accessibility APIs by the user agent.

Finally, an added value for ARIA is that user agents that support CSS attribute selectors ([CSS], Section 5.8) can allow the author to create UI changes based on the ARIA state information, dramatically reducing the amount of script used to create the equivalent functionality. In the following example, CSS selectors based on the value of the ARIA checked state are used to determine whether an image of a checked or an unchecked box is shown:

*[aria-checked=true]:before  {content:  url('checked.gif')}

*[aria-checked=false]:before {content:  url('unchecked.gif')}

2.3. Managing Focus

In any application there must always be an element with focus, as applications require users to have a place to provide user input. The element with focus must never be destroyed, hidden or scrolled off-screen. All interactive elements should be focusable. 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 they wish to interact with.

When using standard (X)HTML and basic WAI-ARIA widgets, application developers can simply manipulate the tab order or use script to create keyboard shortcuts to elements in the document. Use of more complex widgets requires the author to manage focus within them.

WAI-ARIA includes a number of "managing container" 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 the container is navigated to with the Tab key, focus goes directly to the last active descendant. 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 gridcells, 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 activedescendant property, 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 Best Practices ([ARIA-PRACTICES], section 3.2).

Containers that manage focus in this way are:

• combobox
• grid
• listbox
• menu
• menubar
• tree
• treegrid
• tablist
• toolbar

2.4. Features Managed by the User Agent

Look at implementors guide. There are things like focused, focusable, selected, selectable, checkable, etc. Certain roles also have to be treated specially.

2.5. Building Accessible Applications with WAI-ARIA

This section provides a brief introduction to the process of making applications accessible using ARIA. The choice and usage of roles can be complex and context dependent. It is beyond the scope of this document to explain implementations for all the possible ARIA use cases. ARIA Best Practices [ARIA-PRACTICES] provides detailed guidance on ARIA implementation methodology as well as references to sample code.

First steps to making an application accessible:

1. Each element or widget has full and correct semantics that fully describes its behavior (using element names or roles).
2. The relationships between elements and groups are known
3. States, properties, and container relationships are valid for each element's behavior and are accessible via the Document Object Model [DOM] and the platform accessibility API.
4. There is an element having the correct input focus.

ARIA provides authors with the means to make the different elements in a Web application semantically rich. User agents use the role semantics to understand how to handle each element. Roles convey missing information that the assistive technology needs to anticipate the behavior of the elements inside the application such as how to present the corresponding ARIA states and properties to the user. The user agent will use the accessibility semantics from the host language and ARIA accessibility semantics which may override those of the host language and present them to an assistive technology through the Document Object Model or the platform accessibility API. When supporting the platform accessibility API the user agent will create accessible objects containing the accessibility semantics for each visual element on your page. It will use the chosen API to notify the assistive of changes to the semantics as well.

The following steps are recommended as ARIA is applied to content:

1. Use native up when possible

   Use the semantic elements that are defined in the host markup language. For example, with XHTML it is better to use the native checkbox than to use a div element with role checkbox as these should already be accessible through your browser. There may also be cases where ARIA can augment an existing element in the host language. For example, a grid and gridcells can reuse the functionality of a table when overlaying it. ARIA roles, states, and properties are best used when the markup language does not support all the semantics required. When a role attribute is added to an element, the semantics and behavior of the element are overridden by the role behavior.

2. Apply the appropriate roles from ARIA

   Set roles to make sure elements behave predictably and correctly describe the behavior of each element within the application (unless elements behaviors are fully described by the native markup language). Roles for interactive elements should support all the states that the element could use. Once a role attribute is set it should not be changed as this will confuse an assistive technology. This does not preclude a document element being removed which has the role attribute set. Only states and properties may be changed for a given document element.

3. Preserve semantic structure

   Structural information is critical to providing context to people with disabilities. This is achieved through preserving DOM hierarchy within structural elements and widgets; forming logical groups within within user interface widgets such as treeitems in a group. Look for groups within a page, and mark them using the most appropriate role that best describes their usage. For example: a region of the page that contains a group of elements that are likely to change through an Ajax application could be tagged as a region. The preservation of semantic web structure involves your entire web page such as through the use of document landmarks to facilitate keyboard navigation for screen reader and mobility impaired users as well as page restructuring and simplification for users with cognitive and learning impairments.

4. Build relationships

   Look for relationships between elements, and mark them using the most appropriate property or attribute. For example: If container A contains search results, and container B contains the search controls, then mark each container as a region and set the controls property in region B to reference region A. See relationships in WAI-ARIA.

   Some relationships are determined automatically from the host language, such as by using the label tag in HTML.

5. Set and properties in response to events

   Once the role for an element has been set, select the appropriate states and properties for that role during the element's life cycle. This is often done in response to user input events. States are special properties for widgets that may change frequently during a widget's life cycle due to user interaction, while properties are more stable attributes of objects. User agents should notify assistive technology of state changes. Conversely, assistive technology notification of property changes depends on the method by which an assistive technology communicates with the user agent. For example, the multiline property is not something that changes frequently, whereas the checked state changes frequently in response to user input.

   When setting states and properties, set them until the behavior of the element is fully defined. Only use those supported for the chosen role or document element as defined in this specification.

6. Support full, usable keyboard navigation

   Usable keyboard navigation in a rich internet application is different from the tabbing paradigm in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant widgets and uses the arrow keys to navigate within the widget, such as a spreadsheet or menu. The changes that ARIA introduces in keyboard navigation makes this enhanced accessibility possible. For a more in-depth understanding of keyboard navigation in ARIA, see the ARIA Best Practices [ARIA-PRACTICES]

7. Synchronize the visual UI with accessibility states properties for supporting user agents

   This will allow the state of your UI to be perceivable to the user as well as the assistive technology. There are many ways to do this using script or by using CSS attribute selectors (in conforming user agents) For example, the author should have an associated selector that responds to a form element being required or a gridcell being selected. Refer to the ARIA Best Practices [ARIA-PRACTICES] for techniques for proper UI synchronization with the accessible state of the document.

2.6. Example: building a tree widget

Todo: make change at http://lists.w3.org/Archives/Member/w3c-wai-pf/2008JanMar/0189.html item 1 (example linked in BPG), using example at http://test.cita.uiuc.edu/aria/tree/tree1.php

A basic tree view allows the user to select different list items and expand and collapse embedded lists. Arrow keys are used to navigate through a tree, including left/right to collapse/expand sub trees. Double clicking with the mouse also toggles expansion.

Building this user interface element with script could leave assistive technology guessing about the role of each element. To make this feature accessible we need to:

• Inform assistive technology about the role of each element, so they know how to handle it;
• Inform assistive technology about the relationships between tree items;
• Give a clear keyboard focus that will not confuse users with disabilities;
• Expose the changing states (e.g., open and closed) of the the tree items.

We can do that by following the steps below:

1. Look at the native mark up language

   There is no tree element in HTML that supports our behavior including expansion. If such an element existed, we should use that to take advantage of existing support. Since it does not, we will need to use roles.

2. Finding the right roles

   As we did not find a tree element in the native mark up we need to add roles that do this by referencing roles from this taxonomy that support states that we need.

   Our tree will need roles that support embedded list behavior and expandable/collapsible embedded lists. The roles that support tree behavior for a tree are:

   • tree: A tree is the main container element for our tree. It is a form of a select where subtrees can be collapsed and expanded.
   • treeitem: A treeitem is an option item of a tree. This is an element within a tree which may be expanded or collapsed.

3. Look for groups and build relationships

   Tree relationships can be made simply via the DOM and logical structure of the page. A tree element will be the main container encompassing all other elements in the tree. Each selectable item in the tree will be a treeitem.

   When a treeitem contains an embedded list of treeitems they will be all embedded in a group. A group should be contained inside the tree item that is the parent item.

   Tree relationships are like list relationships in HTML. Group and tree elements act like list containers (ol and ul). A tree item acts like a list item (li) in HTML.

   Because treeitems and groups commonly both use div elements it is recommended to add a comment next to closing treeitems that contain embedded tree groups.

   <div role="tree">
    <div role="treeitem">Veggies</div>
    <div role="group">   <!-- veggies children ->
      <div role="treeitem">Green</div>
      <div role="group">  <!-- green children -->
        <div role="treeitem">Asparagus</div>
        <div role="treeitem">Kale</div>
        <div role="treeitem">Leafy</div>
        <div role="group">   <!-- leafy children -->
          <div role="treeitem">Lettuce</div>
          <div role="treeitem">Kale</div>
          <div role="treeitem">Spinach</div>
          <div role="treeitem">Chard</div>
        </div>   <!-- close leafy -->
        <div role="treeitem">Green beans</div> 
       </div>  <!-- close green -->
      <div role="treeitem">Legumes</div>
      <div role="treeitem">Yellow</div>
      <div role="group">   <!-- yellow children -->
        <div role="treeitem">Bell peppers</div>
        <div role="treeitem">Squash</div>
      </div>  <!-- close yellow --> 
     </div>  <!-- close veggies -->
   </div>  <-- close tree --> 
   

   Note Aaron says this can't be formatted the way a list would be done in XHTML (with the child lists inside the list items). This needs explanation, here or in best practices. He explains "I copied XUL which did DOM-based trees the same way for this reason. I didn't see a way to easily show/hide sections using CSS w/o also hiding the parent.
   Talking to Annevk it looks like I made this more difficult than necessary for ARIA, and unfortunately Mozilla doesn't like it if you use the nested <ul> approach.
   So we can fix this but not for Firefox 3.
   So maybe we should look at doing this with nested ul/li and use a CSS rule like:
   li[aria-expanded="false"] > ul { display: none; } "

   Sometimes a tree structure is not explicit via the DOM and logical structure of a page. In such cases the relationships must still be made explicit using the states and properties. In the following example, the owns property indicates that the item with id "yellowtreegroup" should be considered a child of the div element with the property, even though it is not a child in the DOM.

   <div role="treeitem" aria-owns="yellowtreegroup">Yellow<div>
   …
   <div id="yellowtreegroup" role="group">
   <div role="treeitem">Bell peppers</div>
   <div role="treeitem">Squash</div>
   …
   </div>

   Aaron says If the tree is not DOM-complete at all times, don't use either the structured or aria-owns methods. Instead use aria-level, aria-posinset and aria-setsize.

4. Use States, Properties in response to events

   Control the behavior of the element in response to user in put events such as from the keyboard and the mouse as shown here:

   <div tabindex="-1" role="treeitem" aria-expanded="true"
       onclick="return toggleExpansion(event)"
       onkeydown="return processArrowKeystoToggleExpansion(event);"
   >Yellow</div>

   Use device independent events with supporting JavaScript to handle user interaction:

   <div role="tree" tabindex="-1"
       onfocus="return treeItemFocus(event);"
       onclick="return treeItemEvent(event);"
       ondblclick="return treeItemEvent(event);"
       onkeydown="return treeItemEvent(event);">

   Create JavaScript support to control the event driven behavior of the application.

4.1. Relationships between concepts

The role taxonomy uses the following relationships to relate ARIA roles to each other and to concepts from other specifications, such as HTML and XForms.

4.2. Characteristics of Roles

Roles are defined and described by their characteristics. Characteristics define the structural function of a role, such as what a role is, concepts behind it, what instances of the role can or must contain. In the case of widgets this also includes how it interacts with the user agent based on mapping to HTML forms and XForms. States and properties from WAI-ARIA that are supported by the role are also indicated.

The Roles Taxonomy defines the following characteristics. These characteristics are implemented in RDF as properties of the OWL classes that describe the roles.

4.3. Global States and Properties

Some states and properties are applicable to all roles, and most are applicable to all elements regardless of role. In addition to explicitly expressed supported states and properties, the following global states and properties are supported by all roles as well. These include:

• atomic
• busy
• channel
• controls
• describedby
• disabled
• dropeffect
• flowto
• grab
• haspopup
• hidden
• invalid
• labelledby
• live
• owns
• relevant
• required
• tabindex

Global states and properties are applied to the role roletype, which is the base role, and therefore inherit into all roles. To facilitate reading, they are not explicitly identified as either supported or inherited states and properties in the specification. Instead, the inheritance is indicated by a link to this section.

4.4. Roles

To support the current user scenario, this specification defines roles that A, help define Widgets (For example, a tristate Checkbox) and B, help define page structure (for example, a section header).

Roles are categorized as follows:

1. Taxonomy Roles
2. User Input Controls
3. User Interface Elements
4. Document Structure
5. Specialized Regions

Below is an alphabetical list of ARIA roles to be used by rich internet application authors (excluding abstract roles which are not used directly). A detailed definition of the taxonomy supporting these ARIA roles follows.

alert

A message with important information.

alertdialog

A separate window (may be simulated) with an alert, where initial focus goes to the window or a control within it.

application

A software unit executing a set of tasks for its users.

article

Represents a section of a page consisting of a composition forming an independent part of a document, page, or site.

banner

A region that contains the prime heading or internal title of a page.

button

Allows for user-triggered actions.

checkbox

A control that has three possible values: "true", "false", or "mixed".

columnheader

A table cell containing header information for a column.

combobox

Combobox is a presentation of a select, where users can type to select an item.

complementary

Any section of the document that supports but is separable from the main content, but is meaningful on its own even when separated from it.

contentinfo

Meta information which applies to the first immediate ancestor whose role is not presentation.

definition

A definition of a term or concept.

description

Descriptive content for a page element.

dialog

A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response.

directory

A list of references to members of a single group.

document

Content that contains related information.

grid

A grid contains cells of tabular data arranged in rows and columns (e.g., a table).

gridcell

A cell in a grid.

group

A section of user interface objects which would not be included in a page summary or table of contents by an assistive technology.

heading

A heading for a section of the page.

img

A container for a collection of elements that form an image.

link

Interactive reference to a resource.

list

Group of non-interactive list items.

listbox

A widget that allows the user to select one or more items from a list of choices.

listitem

A single item in a list.

log

A region where new information is added and old information may disappear.

main

Main content in a document.

marquee

A marquee is used to scroll text across the page.

math

Content that represents a mathematical expression.

menu

Offers a list of choices to the user.

menubar

A container of menu items (items with role menuitem).

menuitem

An option in a group of choices contained in a menu.

menuitemcheckbox

Defines a menuitem which is checkable (tri-state).

menuitemradio

Indicates a menuitem which is part of a group of menuitemradio roles, only one of which can be checked at a time.

navigation

A collection of links suitable for use when navigating the document or related documents.

note

The content is parenthetic or ancillary to the main content of the resource.

option

A selectable item in a list represented by a select.

presentation

An element whose role is decorative, not meaningful, and does not need to be mapped to the accessibility API.

progressbar

Displays the execution status for tasks that take a long time to execute.

radio

An option in single-select list.

radiogroup

A group of radio controls.

region

Region is a large perceivable section on the web page.

row

A row of grid cells.

rowheader

A table cell containing header information for a row.

search

The search tool of a web document.

separator

A line or bar that separates and distinguishes sections of content.

slider

A user input where the user selects a value from within a given range.

spinbutton

A form of range that expects a user to select from amongst discrete choices.

status

Container for processing advisory information to give feedback to the user.

tab

A header for a tabpanel.

tablist

A list of tabs, which are references to tabpanels.

tabpanel

A container for the resources associated with a tab.

textbox

Inputs that allow free-form text as their value.

timer

A numerical counter which indicates an amount of elapsed time from a start point, or the time remaining until an end point.

toolbar

A collection of commonly used functions represented in compact visual form.

tooltip

A popup that displays a description for an element when a user passes over or rests on that element. Supplement to the normal tooltip processing of the user agent.

tree

A form of a list having groups inside groups, where sub trees can be collapsed and expanded.

treegrid

A grid whose rows can be expanded and collapsed in the same manner as for a tree.

treeitem

An option item of a tree. This is an element within a tree that may be expanded or collapsed.

5.1. Characteristics of States and Properties

The States and Properties Module supports the following characteristics:

5.2. Definitions for States and Properties

States and properties are categorized as follows:

1. Widget states
2. Live Regions
3. Drag and Drop
4. Focus
5. Relationships
6. User Interface Properties

Below is an alphabetical list of ARIA states and properties to be used by rich internet application authors. A detailed definition of the taxonomy supporting these ARIA states and properties follows.

States:

busy

Indicates whether a live region is finished updating.

checked

Indicates the value of a binary or tertiary control such as a checkbox or radio button.

disabled

Indicates that the widget is present, but the value cannot be set and it cannot be internally navigated.

expanded

Indicates whether an expandable/collapsible group of elements is currently expanded or collapsed.

grab

Shows an object's state in drag and drop.

hidden

Defines whether or not the object is visible to the user.

invalid

Indicates that the element's value set by the user is currently invalid, which discourages the form from being submitted.

pressed

Used for buttons that are toggleable to indicate their current pressed state.

selected

Sets whether the user has selected an item or not.

Properties:

activedescendant

Identifies the current active child of an element that has focus.

atomic

Indicates if the assistive technology should present all or part of the changed region to the user when the region is updated.

autocomplete

Indicates whether user input completion suggestions are provided.

channel

Specifies which channel should be used to present the updates for its associated live region.

controls

Defines the elements that are controlled by the current element.

describedby

Points to an element which describes the object.

dropeffect

Shows the effect on the target of a drag and drop operation when the dragged object is released.

flowto

Establishes the recommended reading order of content, overriding the general default to read in document order.

haspopup

Indicates that the element may launch a pop-up window such as a context menu or submenu.

labelledby

Points to the element which labels the current element.

level

The hierarchical level of an element within a structure.

live

Describes the types of updates the user agent, assistive technology, and user can expect from an alert or live region of Web content.

multiline

Indicates whether a text box accepts only a single line, or if it can accept multiline input.

multiselectable

Indicates that the user may select more than one item from the current list.

owns

Defines an object as a parent of another document element, when the child does not appear directly in the subtree of the owner.

posinset

Indicates an item's number or position within the current level of a tree or list.

readonly

Indicates that the widget is not editable.

relevant

Indicates the nature of change within a live region.

required

Indicates that user input is required on the control before a form may be submitted.

setsize

Refers to the number of items in the current level of a list or tree.

sort

Indicates if items in a table or grid are sorted in ascending or descending order.

tabindex

Indicates tab order of elements. Elements with negative values are able to receive focus but are not included in the basic tabbing navigation list or cycle.

valuemax

Maximum allowed value for a range type of widget.

valuemin

Minimum allowed value for a range type of widget.

valuenow

The current value of a widget.

valuetext

The human readable text equivalent of valuenow for a widget.