WAI-ARIA Best Practices

1 Introduction

This section is informative.

The WAI-ARIA Best Practices guide is intended to provide readers with an understanding of how to use WAI-ARIA to create an accessible Rich Internet Application. As explained in the ARIA Roadmap, accessibility deficiencies in today's markup render Rich Internet Applications (RIAs) unusable by people who use assistive technologies (AT) or who rely on keyboard navigation. The W3C Web Accessibility Initiative's (WAI) Protocols and Formats working group (PFWG) plans to address these deficiencies through several W3C standards efforts, with a focus on the ARIA specifications.

For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Best Practices is part of a set of resources that support the WAI-ARIA specification. The Best Practices describe recommended usage patterns for Web content developers, and the WAI-ARIA Primer [ARIA-PRIMER] provides a basic introduction to the concepts behind and reason for ARIA. The WAI-ARIA Suite fills gaps identified by the Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap) [ARIA-ROADMAP]. These documents serve as important places of clarification where topics appear to be unclear.

With the conceptual basis provided in the WAI-ARIA Primer, you should have a good understanding of how ARIA provides for interoperability with assistive technologies and support for a more usable, accessible experience. This guide begins by providing some general steps for building an accessible widget using ARIA, script, and CSS. It then extends your knowledge of ARIA with detailed guidance on how to make RIAs keyboard accessible. Next, the scope widens to include the full application, addressing necessary layout and structural semantics within the web page. These semantics are critical to enable assistive technologies to provide a usable experience when processing RIAs with rich documents on the same page. It includes guidance on dynamic document management; use of ARIA Form properties; ARIA Drag and Drop; and then the creation of ARIA-enabled alerts and dialogs. The appendix provides substantial reference information including code samples for developers of user agents, assistive technologies, and web pages.

2 General Steps for Building an Accessible Widget with ARIA

At this point you should have a basic understanding of how ARIA is used to support interoperability with assistive technologies. If you are not reusing an existing ARIA-enabled widget library and wish to create your own the following steps will guide you through the thought process for creating an accessible widget using ARIA.

Pick the widget type (role) from the ARIA taxonomy

ARIA provides a role taxonomy ([ARIA], Section 3.4) constituting the most common UI component types. Choose the role type from the provided table. If your desire was to create a toolbar set the role to toolbar:
```
<div role="toolbar">
```
From the role, get the list of supported states and properties
Once you have chosen the role of your widget, consult the an in-depth definition for the role in to find the supported states, properties, and other attributes. For example, the toolbar role definition includes:

parent role

In the taxonomy the widget you selected inherits states and properties from this role. In the case of a toolbar you will see that a toolbar is a subclass of a group. This makes sense given that a toolbar is a collection of commonly used functions.

related concept

This is really more informative to state what other concepts are similar to this role. These may exist in different host languages outside ARIA.

supported states and properties

These are unique states and properties that this widget supports and that were not inherited from its ancestors in the taxonomy. In the case of a toolbar, you may choose to set the property of multiselectable to true if you were to have more than one tool in the toolbar selected at a time. An example of this would be a collection of toggle buttons. This indicates to the assistive technology that the toolbar manages a collection of selectable tools.

inherited states and properties

These are all the states and properties which are inherited from the roles's ancestors and which you may use.

global states and properties

These are states and properties which apply to all host language components regardless of whether a role is set or not. You may use these as well.

Once you have chosen the states and properties that apply to your widget you should set those properties you will use to their initial values. Note: you do not need to use all the states and properties available for your role. In our case we shall use:
```
<div role="toolbar" multiselectable="false" tabindex="0" 
    activedescendant="button1">
```
Here, we have specified a toolbar that is not multiselectable. We have also decided that it will received focus in document order (tabindex="0") and that we will manage which child receives focus when the toolbar receives focus. At this time, we have chosen the first button to be active when the toolbar receives focus. Depending on the user agent, this may cause the user agent to send a focus change event to the first button.
Establish the widget structure in the markup (parent/child)

Assistive technologies are very dependent on the structure of widgets as well as general document structure. Structure provides context to the user. A toolbar is a collection of common functions made available to the user. There for all functions should be contained within the toolbar. This can be determined through relationships, such as by using the advanced owns property or simply by using the document object model structure created by the browser when parsing the host language. For our purposes we will define three image buttons for cut, copy, and paste.
```
<div role="toolbar" multiselectable="false" tabindex="0" activedescendant="button1">
  <img src="buttoncut"><img src="buttoncopy"><img src="buttonpaste">
</div>  
```
Repeat steps 1-3 for the children of the parent
We now need to assign the roles and states for each of the children. However, we shall save the detailed navigation for step 5.
```
<div role="toolbar" multiselectable="false" tabindex="0" activedescendant="button1">
  <img src="buttoncut" role="button" >
  <img src="buttoncopy" role="button">
  <img src="buttonpaste" role="button">
</div>
		
```
The process of setting roles and states may be a recursive procedure if the children themselves have children, such as in the case of an expandable/collapsible tree widget.

Establish keyboard navigation of the widget and plan for how it will be navigated to within the document

It is very important that that your widget be keyboard accessible. In fact, there should also be a keyboard equivalent for every mouse mouse operation. Where possible you should refer to the WAI-ARIA examples in this guide for tips on how to implement keyboard navigation for your widget. If you find that an example is not provided, you should follow standard desktop keyboard navigation.

For our toolbar, we have chosen to have the toolbar manage the focus for its children and through the use of the activedescendant property. We have also chose to have the toolbar receive focus based on the tab order by using tabindex. In order to use activedescendant, each descendant must have an assigned ID.

<head>
<script>

 function optionKeyEvent(event)
   {
   var tb = event.target;
   var buttonid; 
  
   DOM_VK_ENTER = 13;

 // Partial sample code for processing arrow keys

 if (event.type == "keydown") {
   if (event.altKey) {
   return true;  // Browser should use this, the menu view doesn't need alt-modified keys
   }
   // XXX Implement circular keyboard navigation within the toolbar buttons

   if (event.keyCode == DOM_VK_ENTER) {
     ExecuteButtonAction(getCurrentButtonID(); // This is an author defined function
   }
   else if (event.keyCode == event.DOM_VK_RIGHT) {
     // Change the active toolbar button to the one to the right (circular) by 
     var buttonid = getNextButtonID();   // This is an author defined function
     tb.setAttribute("aria-activedescendant", buttonid); 
   }
   else if (event.keyCode == event.DOM_VK_LEFT) {
      // Change the active toolbar button to the one to the left (circular) by 
      var buttonid = getPrevButtonID();  // This is an author defined function
      tb.setAttribute("aria-activedescendant", buttonid); 
   } 
   else {
      return return true;
   }
   return false;
   }
 }
else if (event.type == "keypress") {
  ...
}  
</script>

<div role="toolbar" multiselectable="false" tabindex="0" activedescendant="button1" id="tb1" 
     onkeydown="return optionKeyEvent(event);"
     onkeypress="return optionKeyEvent(event);">
   <img src="buttoncut" role="button" id="button1">      
   <img src="buttoncopy" role="button" id="button1">     
   <img src="buttonpaste" role="button" id="button1">     
</div>

The details of implementing keyboard navigation are described in Keyboard and Structural Navigation section of this document.

Note: You should also show the visual focus for each element that has focus.

Apply and and manage needed ARIA states in response to user input events

Similar to the processing of activedescendant in Step 5, as author you should set any additional ARIA states and properties on document elements.
Synchronize the visual UI with accessibility states and properties for supporting user agents
You should consider having your UI trigger, such as through the use of CSS selectors, off of changes to the modification to them. For example, the setting of the selected state may change the background of a selected treeitem in a tree. This may also be done with JavaScript.
The proper synchronization showing and hiding sections in a widget with the ARIA display state is also critical. Some platform accessibility APIs provide events for applications to notify the assistive technology when pop-ups such as menus, alerts, and dialogs come into view or go away. Rich Internet Applications can assist browsers which support these conventions by:
1. Creating an entire section and then insert it into the Document Object Model [DOM], as a subtree of the parent element activated to show the pop-up, and then removing the section from the inserted area when the pop-up goes away.
  
  OR
2. Using the following style sheet properties to show and hide document sections being used to represent the pop-up items, menus or dialogs:
  - display:block
  - display:none
  - visibility:visible
  - visibility:hidden
  By monitoring these behaviors a user agent may use this information to notify assistive technology that the pop-up has occurred by generating the appropriate accessibility API event.
Some assistive technologies may use the DOM directly to determine these when pop-up occurs. In this case, the first mechanism of writing a section to the DOM would work using the DOM events. However, if you are using CSS to show and hide sections of the DOM (2) it is essential that you set the corresponding ARIA hidden property to indicate that the section is visible or hidden and synchronize it with your CSS styling as shown here:
```
[aria-hidden=true] {visibility: hidden;}

...

<div role="button" aria-haspopup="true" aria-owns="mypopupmenu">
<div role="menu" aria-hidden="true" id="mypopupmenu">...</div>
```

Support basic accessibility, such as alternative text on images

When an image is used to represent information within a component, such as our image buttons, you need to set the alternative text on those images. This is then mapped by the user agent to the accessible name in the platform accessibility API. Using our example:

<div role="toolbar" multiselectable="false" tabindex="0" activedescendant="button1" id="tb1" 
     onkeydown="return optionKeyEvent(event);"      
     onkeypress="return optionKeyEvent(event);">    
   <img src="buttoncut" role="button" id="button1" alt="cut">
   <img src="buttoncopy" role="button" id="button1" alt="copy">
   <img src="buttonpaste" role="button" id="button1" alt="paste">      
</div>

Establish ARIA relationships between this widget and others
Once you have made the basic widget accessible you may then need to establish its relationship to other widgets. Examples of this are labelledby, controls, describedby and flowto. The details of using these relationships are described in the Relationships section of this document.

Other relationships which should be considered are more declarative and provide context to the widget within a set. For these, level, posinset, and setsize are provided.
Review widget to ensure that you have not hard coded sizes

The ability for applications to respond to system font settings is a requirement. Most user agents are designed to meet this requirement. This also means your web application running within your browser is impacted when the user agent changes the font sizes to meet the need. If you have hard coded your font size, such as setting the font size to a specific pixel size, an increase in system fonts will not be reflected in your web application. You must also not hard code the size of your widgets either. If you make your fonts scaleable and not the widgets they are in the text could flow outsized your widget.

So, follow these rules to allow your application to respond to system font settings:
- Establish a base set of font sizes and widget sizes based on em height
- Ensure that all fonts used are a function of this base em height
- Make sure all widgets are a function of the base em height
An em is a is the font unit of measure between the top and bottom of an upper case letter M. This is independent of the scale which the font is reproduced. Often, the user agents font adjustment to system settings, are such that they are defined using the font's internal metrical units (font units), which are specified as units of the total body or em height of the font, hence em units. Em can be used as a proportional unit of length in CSS to scale properties in relation to the default font size settings in a users' browser:
Test with User agent, Assistive Technology, and People with disabilities

To ensure you have set your ARIA semantics correctly, test your application with your user agent, an assistive technology, and a person with disability. Example assistive technologies are screen readers and screen magnifiers. Ensure that your user agent is designed to support ARIA and their your assistive technology is designed to support ARIA in the selected user agent.

3 Keyboard and Structural Navigation

3.1 Understanding Navigation and General Issues

3.1.1 ARIA Keyboard Bindings and Behaviors

Essential to accessible Web 2.0 widgets is keyboard support to provide full operation and functionality of a widget through keyboard-only events. Unlike traditional HTML form controls, Web 2.0 widgets have no inherit keyboard support. The developer must enable keyboard support for the widgets they create or use widget libraries with keyboard support. The best practices model for keyboard support for Web 2.0 widgets are graphical user interface (GUI) operating systems like Microsoft Windows®, Apple OSX®; and UNIX Desktops like GNOME and GTK. Two basic accessibility requirements for keyboard focus include:

Support users who cannot use pointing devices due to physical or visual impairment to access the full functionality of the Web application.
All major software and web accessibility guidelines for people with disabilities require keyboard-only operation of the interface for accessibility.
Communicate accessibility information to assistive technologies on the type of widget and its associated state and properties.

3.1.2 Keyboard Navigation between Widgets

The tabindex attribute enables focus to be moved via keyboard to HTML elements used to create Web 2.0 widgets.

Tab and Shift+Tab key move focus among widgets and standard HTML controls.
Widgets with tabindex=0 will be added to the tab sequence based on document order
Widgets with tabindex>0 will be added to the tab sequence based on the TABINDEX value
Widgets with tabindex<0 will not be added to the tab sequence but are enabled to receive keyboard focus.

Once a widget has keyboard focus, arrow keys, Spacebar, Enter key, or other keyboard commands can be used to navigate the options of the widget, change its state, or trigger an application function associated with the widget.

3.1.3 Keyboard Navigation within Widgets

Each element that receives keyboard focus needs to have a tabindex attribute set. The element with keyboard focus is essential because it communicates information about the widget to assistive technologies like screen readers and magnifiers through operating specific accessibility APIs like Microsoft Active Accessibility (MSAA), Apple Accessibility Programming Guidelines and ATK Accessibility Toolkit. The TAB key moves keyboard focus to the widget, and other keys operate the features of the widget, typically cursor keys, Enter key and Spacebar. The actual keys are up to the developer, but best practices recommend using the same key bindings that are used to control similar widgets in common GUI operating systems like Microsoft Windows®, Apple OSX® and UNIX Desktops like GNOME and GTK. JavaScript can use either the focus() method to move focus to the appropriate element in the widget, or it can use an ARIA property called "activedescendant" to indicate which element in the widget should have focus. The author must indicate through styling and/or markup which element in the widget has focus.

3.1.4 Example Keyboard Operation: Radio Group/Radio

See working Radio button examples from the University of Illinois.

Key Bindings for Radio Group Behavior - Example
Key	Description of Radio Group Behavior
Tab Key	If no radio buttons is checked, focus moves to the first radio button in the group, but the radio button remains unchecked. If one radio buttons is checked, focus moves to the checked radio button. If SHIFT+TAB is pressed, focus moves to the last radio button in the group, but the radio button is not checked
Space Bar	Checks the radio button with keyboard focus (this is a special case when using tab and no radio buttons have been marked as checked)
Down Arrow	Move the checked radio button to next radio button. If no button is checked, check the first radio button. If the last radio button is checked, check the first radio button
Up Arrow	Move the checked radio button to previous radio button. If no button is checked, check the last radio button. If the first radio button is checked, check the last radio button

In this Radio Group example, the tabindex of the radiogroup element initially has tabindex="0" (assuming none of the radio buttons is checked), the radio elements have tabindex="-1". As soon as one of the radio buttons is checked, the radio group element changes its value of tabindex="-1", the radio element that is checked changes its value to tabindex="0", and all other radio buttons have a tabindex ="-1".

3.1.5 Other Widget Best Practices

For specific keyboard navigation, see the individual widgets and structures.

3.1.6 Validation Issues

TABINDEX, ROLE, and ARIA states and properties attributes need to be added to elements used to create widgets within HTML 4.01 documents through scripting, if the resource is to validate, because the HTML 4.01 DTD only allows TABINDEX on anchors and form controls. See the | Embedding Accessibility Role and State Metadata in HTML Documents for more information.

3.2 Providing Keyboard Focus

One way to provide keyboard support in (X)HTML is with form and list elements that accept keyboard focus by default. With the Tab key, the user can navigate to these types of elements. However, building sophisticated widgets using these elements is not practical. Moreover, navigating with only the Tab key can be very tedious. The solution is to provide full keyboard support within the widgets using additional keystrokes such as the arrow keys to provide more intuitive navigation.

A tenet of keyboard accessibility is reliable, persistent indication of focus. The author is responsible, in the scripts, for maintaining visual and programmatic focus and observing accessible behavior rules. Screen readers and keyboard-only users rely on focus to operate rich Internet applications with the keyboard.

3.2.1 Tabindex

One requirement for supporting the keyboard is to allow focus to be set to any element. The tabindex attribute can be used to include additional elements in the tab order and to set programmatic focus to them. Originally implemented in Internet Explorer 5, the feature has been extended to Firefox and Mozilla. The following table outlines the use of the tabindex attribute:

Use of the Tabindex Attribute
Tabindex Attribute	Focusable with mouse or JavaScript via element.focus()	Tab Navigation
not present	Follows default behavior of element (only form controls and anchors can receive focus.)	Follows default behavior of element
zero - tabindex="0"	yes	In tab order relative to element's position in document
Positive - tabindex="X" (where X is a positive integer between 1 and 32768)	yes	Tabindex value directly specifies where this element is positioned in the tab order.
Negative - tabindex="-1"	yes	No, author must focus it with element.focus() as a result of arrow or other key press

Setting a tabindex value of -1 to an element allows the element to receive focus via JavaScript using the element.focus() method. This method is used to enable arrow key navigation to elements. Each element that can be navigated to via arrow keys must have a tabindex of -1 to enable it to receive focus. A keydown event handler can determine the next object to receive focus and call that element's focus() method. In addition, element's style may require an update via an onfocus event handler in order to show the focus, because browsers are inconsistent in displaying focus for items that receive focus programmatically.

3.2.2 activedescendant

Rather than setting a key event handler on each element within a larger component, the event handler can be set on the parent element with the activedescendant property used to indicate the active child. For example, the container element with the role of tree can provide an onkeydown event handler so that each individual tree item within the tree does not need to be focusable and to listen for the keydown event. The container object, in this case the tree, needs to maintain the point of regard and manage which individual child item should be perceived as active. The key handler on the parent captures the keystrokes and determines what item becomes active next and updates the activedescendant property with the ID of the appropriate, next active child element. The browser takes that ID information and generates the focus event to the assistive technology. Each individual elements does not have to be made focusable via a tabindex value of -1, but it must be styled using CSS to indicate the active status.

3.2.3 Author-Defined Keyboard Short-Cuts or Mnemonics

Author-defined keyboard short-cuts or mnemonics present a high risk for assistive technology users. Because they are device-, browser-, and AT-dependent, conflicts among key bindings is highly probable. The XHTML 2 Working Group is currently developing a new access element to address this issue.

3.3 Supporting Tooltips with the Keyboard

Tooltips are popup messages typically triggered by moving a mouse over a control or widget causing a small popup window to appear with additional information about the control. For accessibility, the user should be able to activate tooltips using the keyboard. When a form control or widget receives keyboard focus, the tooltip popup should display. When the form control or widget loses focus, the tooltip should disappear.

For an example of working tooltips, see the iCITA site.

3.4 Providing Logical Layout Semantics using Structural Roles

This section of the Best Practices document is intended to assist you in conveying a logical, usable, and accessible layout to an assistive technology or adaptive system designed to modify the visual layout to meet the users needs. The following is the list of roles, which may be used by authors, to convey structural information in ARIA:

To begin our discussion on the use of layout semantics through the use of structural role it is important to start by defining a few terms:

Role: A role is an indicator of type. An object's role is the class of objects of which it is a member. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type. Roles are element types and should not change with time or user actions. Changing the role on an element from its initial value will confuse an assistive technology, and, ultimately, the user. Platform-specific accessibility APIs, to which the roles are mapped by the browser, do not provide a vehicle to notify the assistive technology of a role type changing. If the old element type is replaced by a new one, the corresponding element and its subtree should be removed from the document, and a new one inserted containing the new role type.
Region: The term region defines a group of elements which, together, form a large perceivable section of a document instance, which the author intends to be included in a summary of page features, such as a "Table of Contents" or "Summary of Regions".

3.4.1 Regions and XHTML Role Landmarks

One of the deficiencies of (X)HTML for disabled users has been they usability of keyboard navigation. Users, dependent on a keyboard for navigation, have been forced to tab everywhere in the document as the only document elements which are keyboard accessible are form and anchor elements. This has forced developers to make most everything a link to make it a keyboard accessible and to get to each link you have to tab to it. With the advent of portals and other content aggregation means web pages are divided into visible regions and there has been no vehicle to get to them other than perhaps to do things such as:

Create a skip link at the top of the page to the main content
Make the head of each perceivable region (search bar, stock quote, TV Listing, etc.) an <H1> tag

There are three problems with this approach:

Both force the user interface to change to support accessibility
In the case of using <H1> to mark your regions, this is not consistent across web sites
The semantics are limited to main content and a section

ARIA provides two vehicles to mark sections of your document:

Follow these steps to assign to mark each logical section:

Identify the large perceivable regions of your web page

Make a note of each logical region of your document (think of it like a portal). Think about the user wanting to navigate to these logical "portlets" on your web page. Write down a description of what you believe each section to be.
Look at the standard xhtml role landmarks to see which one best fits each region of your page

If possible it is best to use these as landmarks. They will be common landmarks which your assistive technology will become very familiar with on every site. Furthermore, your browser may assign key sequences to move focus to these sections as they can set on every site. Furthermore, navigation to these landmarks is device independent. A personal digital assistant (PDA) could assign a device key to get to them in your document. These are the common xhtml landmarks:

banner

A banner is usually defined as the advertisement at the top of a web page. The banner content typically contains the site or company logo and other key advertisements for the site.

contentinfo

This is information about the content on the page. For example, footnotes, copyrights, links to privacy statements, etc. would belong here.

definition

The contents of the associated element represent a definition (e.g., of a term or concept). If there is a dfn element within the contents (as defined in XHTML Modularization [XHTMLMOD]), then that represents the term being defined.

main

This defines the main content of a document.

navigation

This is the navigation bar on a web document. This is typically a list of links to other pages on the site or other areas of the same document.

note

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

search

This is the search section of a web document. This is typically a form used to submit search requests about the site or a more general Internet wide search service.

secondary

This is any unique section of the document. In the case of a portal, this may include but not be limited to: show times; current weather; or stocks to watch.

seealso

Indicates that the element contains content that is related to the main content of the page.

Assign the appropriate landmark to each of your web page regions and choose a short title for each of these regions.
For the landmarks that just won't fit use the region or select region ARIA roles

If you are a rebel and just have to define your own region outside the common landmarks then you can. ARIA has some region roles which you may also use as landmarks:
- log
- status
- region (generic)
Assign the region role to those regions and choose a short title to go with it.
Set the landmarks in your web page

Typically each section will be something innocuous like a <div> or <iframe>. Set the role and title for each region. Since the xhtml role attribute module is part of the XHTML namespace, simply set the role value without any namespace prefix as shown here:
```
<div role="main" title="Top News Story">  <div role="secondary" title="weather">  
```
For ARIA regions here are some examples:
```
<div role="log" title="chat log">  <div role="region" title="Game Statistics">  
```
When you use the wairole namespace, remember to define the wairole namespace prefix in the header as described above.

3.4.2 Structural Roles used to facilitate assistive technology navigation

While ARIA is designed to address many disabilities, this section is best described in terms of screen reader use. In desktop applications, screen readers typically treat widgets as discrete entities, reading and interacting with each widget one at a time. The user moves the point of focus from widget to widget using tab/shift tab, mnemonics, or accelerators, keyboard commands which are usually provided by the application or the operating system. We refer to this mode of interaction as "application mode."

When viewing web content however, screen readers often gather information about all the widgets in an area and present them in a document-like view which the user navigates using keyboard commands provided and controlled by the screen reader. Think of this mode as a virtual environment that presents web content in a way that makes it convenient for adaptive technology users to navigate and read. This is sometimes called browse mode, or virtual mode. We refer to this as "document mode."

Because screen readers often provide document mode navigation support using single key mnemonics on the alpha-numeric keyboard, they may provide a third mode, called "forms mode," used to interact with form controls that are encountered in document mode. Behavior in forms mode is similar to that of application mode. The key feature of forms mode is that it can be toggled with document mode to make it easy to both interact with a specific widget, and read virtualized content of which the widget is a part. Since, as described above, a screen readers perception of an area as either a document or an application greatly influences how the user reads and interacts with it, ARIA provides content authors a way to indicate whether their pages should be viewed as applications or documents by assistive technologies.

To set document or application mode follow these steps:

Set the Application Role

After you have divided your web page into regions through the use of role landmarks and custom regions, you must make a decision: Is your web page an application or not? If it is, set the role of application on the body tag as follows:
```
<body role="application"> 
```
Special Considerations:
- If your page has only a few isolated widgets, like pop-up calendars located on a web page, it is not necessary to expressly set the role of application on the body. Screen readers, based on widget roles, should be able to provide access to these widgets without recognizing the entire page as an application.
- Also, browsers make use of a feature called the contenteditable attribute, which will be incorporated into HTML 5. Contenteditable allows an author to turn the browser section into a rich text editor, similar to a word processor. Any section which has contenteditable set to "true" is considered a widget.
- If the body element has been given the role of application, please follow step 2. Otherwise, the web page is considered a document, and no further action is required in this regard.
Set the Document Role

Look at the regions/landmarks you have defined and determine which ones should be browsed as a document or navigated as an application. For each region which should be browsed, embed a div element within it with the role of document as follows:
```
<div role="document"> 
```
Now, when a screen reader encounters this region, it will be rendered in document mode.
Use of the presentation role vs. CSS

An element whose role is defined as presentation does not need to be mapped to the accessibility API. The presentation role's intended use is to mark an element which is used to change the look of the page, such as a TABLE used to control layout, but which does not have all the functional, interactive, or structural relevance implied by the element type for which the presentation role is defined.

A user agent may remove all structural aspects of the element being repurposed. For example, a table marked as presentation would remove the table, td, th, tr and any other child elements of TABLE, while preserving the individual text elements within it. Because the user agent knows to ignore the structural aspects implied in a TABLE, no harm is done by using a table for layout.

The following is an example for using the ARIA presentation role to convey layout:
```
<table role="presentation">
  <tr>
    <td>see</td>
    <td>spot</td>
    <td>run</td>
  </tr>  
  <tr>  
    <td>over</td>
    <td>the</td>
    <td>lazy coder</td>
  </tr>
</table>
```

3.4.3 Implicit Nesting and Headings

This section discusses the use of the heading role and nesting levels.

3.4.3.1 Header Levels versus Nesting Levels

The heading role value signifies a heading for a section of the document instance. Use of the heading role indicates that a specific object serves as a header. The section of the document to which the heading pertains to should be marked with the labelledby property containing the value of the id for the header.. If you have a heading and there is no element containing the content that it heads, wrap the content in a <div> bearing this labelledby attribute. If headings are organized into a logical outline, the level property can be used to indicate the nesting level. Here is an example:

<p role="main" aria-labelledby="hdr1">

 <div role="header" id="hdr1">
    Top News Stories

 </div>

</p>

3.4.3.2 Owns Repairs Nesting

Assistive technology briefs users on the context where they are. When they arrive at a new page, a page summary may be given. When they move into a new context, some of the labeling from elements containing the new focus or reading location may be read out, to give context to the details to be read next.

The syntactic structure of a page provides the default nesting of contexts. If a paragraph is nested in a <div> or table cell, it is assumed that labels for the <div> or headers for the table cell are pertinent to what is in the paragraph. On the other hand, it is not possible to always flow the logical structure one-to-one into the parse structure. The owns relationship is provided to annotate logical nesting where the logical child is not a syntactic descendant of the logical parent.

A conspicuous use case for this capability is the construction of a treegrid structure, building on the basic structure of an HTML <table>. Here some rows are logically within the scope or nested under some other rows. The <table> syntax does not allow nesting of rows in rows. So in this case owns relationships are used flowing from the rows that identify general topics to the rows dealing with sub-topics of that topic.

3.4.4 Grouping, Regions, and Directories

3.4.4.1 Groups and their applicability

A group is a section of related user interface objects which would not be included in a page summary or table of contents by an assistive technology. Sections of user interface objects that should be included in a page summary or table of contents should be identified as a region. Unlike a group, A heading is used to label a section which forms a region. The region and its heading are normally perceivable in the context of the document.

Authors should use a role of group to form logical collections of items in a widget such as a:

a row in a grid;
a group of children in a tree widget forming a collection of siblings in a hierarchy; or
a group of items having the same container in a directory

Proper handling of group by assistive technologies, therefore, is determined by the context in which it is provided. Group members that are outside the DOM subtree of the group need to have explicit relationships assigned for them in order to participate in the group. Groups may also be nested.

If an author believes that a section is significant enough in terms of the entire document instance, then the author should assign the section a role of region or a standard XHTML Role landmark.

3.4.4.2 Regions vs. groups

The term region defines a group of elements that together form a large perceivable section of a document instance, which the author feels should be included in a summary of page features, such as a "Table of Contents" or "Summary of Regions."

When defining a region for a section of a document, authors should consider using standard document landmark roles defined by the XHTML Roles Module. This makes it possible for user agents and assistive technologies to treat roles as standard navigation landmarks. If the definition of these regions is inadequate, authors should use the ARIA region role and provide the appropriate title text. For more information on the use of region see Regions and XHTML Role landmarks.

3.4.4.3 Directories and their applicability

The ARIA role, directory, allows authors to mark static table of content sections of a document. Prior to ARIA, the user would need to guess if an area of a document actually pertained to the table of contents. Authors should mark these sections these areas within a document with a role of directory.

<div role="directory">
   <ul>
      <li>Global Warming Causes
          <ul>
             <li>CO2 Buildup</li>
             <li>Auto emissions<li>
             <li>Factory emissions</li>
             <li>Destruction of rainforests</li>
          </ul>

      </li>

      <li>Tailoring CO2 buildup</li>
          <ul>
             <li>Elimination of the incandescent light bulb</li>
             <li>Hydrogen fuel cells</li>
             <li>Solar energy</li>
             <li>Wind power</li>
          </ul>

      </li>  
   </ul>

</div>

3.4.5 Remaining structural roles

3.4.5.1 Tabular structure related roles supporting tabular widgets

There are a number of structural roles which are used to support tabular widgets grid and treegrid which indicate additional keyboard navigation as well as the ability to select rows and/or columns. Typically, you would apply these roles to an underlying table in the base markup as shown here:

<table role="grid">

However, in some instances that may not work for the developer, such as when the developer has need for a <div> or <span>, or additional semantics may be needed. To assist, the following roles are provided to support tabular widgets:

When constructing a grid or treegrid the author should use gridcell's for the actual cells:

<table role="grid">
   <tr>
      <td role= "columnheader">Apples</td><td role= "columnheader">Oranges</td>
   </tr>
   <tr>
      <td role="gridcell" aria-readonly="false">Macintosh</td><td role="gridcell">Valencia</td>
   </tr>
</table>

Gridcells are focusable within a grid unlike a table. They may also be editable as is shown in the above example.

Treegrid's may require expanding and collapsing rows which may not be performed using a <tr>. In these instances authors will use an HTML <div>. ARIA provides a role of row which may be assigned to the div to convey to the assistive technology that this is still a row.

3.4.5.2 Marking Description sections

A new feature of ARIA is the ability to mark a description in your document that can then be associated with a section, drawing, form element, picture, and so on. This is unlike longdesc which typically required the author to create a separate file to describe a picture when it was preferred to have the descriptive text in prose as well so that it was readily available to all users.

<img src="foo" alt="" aria-describedby="prose1">

<div role="description" id="prose1">
This prose in this div describes in detail the image foo.
</div>

This is the preferred vehicle for providing long descriptions for elements in your document.

4 Relationships

4.1 Labeling and Describing

Marked up content or widgets will often need additional context to make clear what the meaning or purpose is. It is also reasonable that some content media types will need additional descriptions in another format to give clarity to those who are unable to consume the origin format. These additional meta-content sections are linked together by tagging them as labels or descriptions. ARIA provides the labelledby and describedby attributes to signal the browser to feed these relationships into the accessibility layer. This layer is then used by screen readers and other accessibility technology (AT) to gain awareness of how disparate regions are actually contextually connected to each other. With this awareness the AT can then present a meaningful navigation model for discovery and presentation of these additional content sections. The user agent itself can also choose to present these insights in a meaningful way. Generally you should always add these attributes to any widgets on your site as they are often merely a construct of HTML and JavaScript which provides no obvious insight as to what the widget's behavior or interactivity is.

4.1.1 Labelled By

A labelledby section needs to indicate what the object it labels does. For example, you could have a button in a webmail client which will erase a selected message. This button could be constructed out of any kind of HTML but with with the ARIA roles, states and other attributes the user will know it is a button. The button itself should have a basic behavioral explanation, such as "erase mail" but the user might not be familiar with this feature or webmail in general, so providing additional behavioral labeling will reduce fear and make the page more user friendly. The markup could look like this

<div role="button" aria-labelledby="eraseButton" tabindex="0">Erase Message</div>

and elsewhere in the markup

<div id="eraseButton">Permanently erase the currently selected message titled "Nigerian Lottery"</div>

This would give the user and any running AT additional information about the expected behavior if the button widget is activated. In this particular case, the div content has been updated to reflect the current context to make it more obvious exactly what the effect of the action will be. The section doing the labeling might be referenced by multiple widgets or objects as these need only reference the same id, so contextual description may not always be viable. The labelledby attribute can have multiple ids specified as a space separated list much like applying multiple classes to a single DOM object. labelledby does not accept a className specification so all relationships are by specific and unique id only.

4.1.2 Described By

A describedby section provides further information about a given object or widget, which may not be intuitively obvious from the context, content or other attributes. For example, a fake window is a common widget used in web applications and is often constructed using a div absolute positioned in a layer above other content. To simulate common window behavior look and feel there is often an X box in the corner which, when activated, dismisses the window widget. One common way to make this X box is to simply make a link whose content is an X. This doesn't give a non-visual user much to go on and belies the real purpose of the X link. To help we add more descriptive text stored elsewhere in the page like this:

<a role="button" aria-describedby="winClose" href="#" onclick="fakewin.close()">X</a>

and then elsewhere in the HTML

<div id="winClose">Closing this window will discard any information 
  entered and return you back to the main page</div>

Like labelledby, describedby can accept multiple ids to point to other regions of the page using a space separated list. It is also limited to ids for defining these sets. In our contrived example we would also want a good labelledby section to fully explain what the window does and how closing will effect the task being worked on. If an object or widget lacks describedby the user agent or AT may try to extract information from the label or th tags, if present. The label and th tags have limited use in that they can only be applied to forms or tables, respectively.

ARIA also defines the description and tooltip roles to which describedby may reference to assign a description (which could span multiple document elements) and a author defined tooltip. The assistive technology can can tell from the type of object describing the document element what that the purpose of that element is. For example, a screen reader could announce the tooltip without the user having to waive the mouse over the element by following the describedby relationship to a document area with a tooltip role.

Here is a code snippet showing a set of the tooltip:

...    
  <div class="text">
    <label for="first">First Name:</label>
      <input type="text"               
          id="first"           
          name="first"            
          size="20"           
          onfocus="tooltipShow(tooltip1)"           
          onblur="tooltipHide(tooltip1)"
          onmouseover="tooltipShow(tooltip1)"           
          onmouseout="tooltipHide(tooltip1)"           
          aria-describedby="tp1"
      />
  <div id="tp1" class="tooltip" role="tooltip">Your first name is a optional</div>    
  </div>    
...

4.2 Owning and Controlling

4.3 Changing the Reading Flow

(X)HTML suffers from a number of disadvantages in keyboard navigation today. One such example is the restriction of navigation to the tabbing order. This is a common problem with presentations in office suites where the logical, perceivable, navigation order of a slide may not match the tabbing order. Sighted users may see a logical navigation process (such as visual steps in the process for assembling a lawn mower). This "flow" is not conveyed by the tab order. The user might tab from step 1 and land on step 4. Another problem is the construction of model-based authoring tools on a web page. In a model-based authoring tool, a visual object may provide a number of paths that the user can take, such as a multiplexor, which may have output that logically flows to a number of optional electronic components in a drawing. In Web 2.0, developers are actually creating drawings like this to perform tasks such as visually model a work flow. In this scenario, the user will want to decide which object they will navigate their screen reader or alternate input device to next.

For these reasons, ARIA provides a relationship property, called flowto, for the author to provide an alternative navigation order(s),enabling an assistive technology to exchange the normal navigation flow for one that is logical for people with disabilities. flowto establishes the recommended reading order of content, overriding the default of reading in document order.

Consider the first case of changing a basic reading flow to circumvent(X)HTML tabbing. A good example of this is a logical reading flow in a portal with landmarks. In the future, the user may wish to change the reading flow based on the order of priority with which they navigate a personalized web application like MySpace or MyYahoo. In the following example, the navigation would follow the order of "Top News Stories", "television listings", "stock quotes", and "messages from friends" by following (X)HTML document reading order. However, the author or end user may determine that the main content is most important, followed by "stock quotes", "messages from friends", and then "TV listings."

<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">  
...  
<div role="main" title="Top News Stories" id="main" aria-flowto="stock"></div>  
<div role="secondary" title="television listings" id="tv"></div>
<div role="secondary" title="stock quotes" id="stock" aria-flowto="messages"></div>
<div role="secondary" title="messages from friends id="messages" aria-flowto="tv"></div>

The second use case is such that the web developer may wish to circumvent the flow by branching to multiple paths in the web page, requiring the assistive technology to present a collection of options where the user could go next. This is important for workflows or business process management applications as shown in this Process Designer Tool. More of these applications are becoming web based, and a vehicle is required to tell the user how to get through the work flow. The flowto property takes multiple idrefs, allowing the author to define each object the user could flow to. To implement this technique do the following.

Make each objects in the work flow accessible

This will require assigning a title or ARIA label for each object and a unique HTML id. Also, if the html element is repurposed assign it an ARIA role.

<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">

...  
<img src="foo.jpg" id="331" title="What is the Invoice Value?">  
<img src="foo.jpg" id="333" title="Finance Manager Approval">  
<img src="foo.jpg" id="334" title="Sales Manager Approval">  
...

Assign the flowto properties

For each visual object that will flow to one or more other objects assign the flowto property the list of IDs to which it flows.

<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">  
...  
<img src="foo.jpg" id="331" title="What is the Invoice Value?" aria-flowto="333 334">  
<img src="foo.jpg" id="333" title="Finance Manager Approval">  
<img src="foo.jpg" id="334" title="Sales Manager Approval">  
...

Make sure visual objects are keyboard accessible

Use tabindex to set allow objects to receive focus. Actually setting focus to them may be performed by an assistive technology, such as an alternative input device. This example places each drawing object in document order with respect to the tab sequence.
```
<img src="foo.jpg" id="331" title="What is the Invoice Value?"
    aria-flowto="333 334" tabindex="0">
<img src="foo.jpg" id="333"  title="Finance Manager Approval" tabindex="0">
<img src="foo.jpg" id="334" title="Sales Manager Approval" tabindex="0">
...  
```
When an assistive technology encounters "What is the Invoice Value?," it will know to tell the user that they may choose to navigate either to the "Financial Manager Approval" or to the "Sales Manager Approval" object. The options may be provided through a menu for the to What is the Invoice Valueto object by the assistive technology. After a choice is made, then the AT can then move focus to the target object; or in the case of a screen reader, it may just move the user to that location in the screen reader's virtual buffer.

Note: ARIA does not specify backward flowto properties for the same reason that we do not have the reverse of relationships like labelledby. The author may incorrectly do the reversal, creating a whole set of new problems. Rather, the task of the reversal relationships may be handled by the user agent through its accessibility API mapping or in the assistive technology itself.

5 Document Management

5.1 Managing Content and Presentational Changes

General rules for managing content and displaying information

Don't change roles on an element
Tie CSS selectors to ARIA properties to reduce script (browser issue with refresh)
Tie CSS display property to ARIA hidden state (can also use visibility property but it affects layout)

If you are refreshing areas asynchronously, need to look at live regions, alert, status, log.

5.2 Implementing Live Regions

Live regions are parts of a web page that the web page author expects to change. Examples of live regions include tables with dynamically updated content (sports stats, stock information), logs where new information is being added (chat transcript logs), notification areas (status, alerts), etc.

Live regions enable assistive technologies, such as screen readers, to be informed of updates without losing the users' place in the content. Live region settings provide hints to assistive technologies about how to process updates. Note that the assistive technology is responsible for handling these updates and enabling users to override these hints.

With the following process, rich Internet application (RIA) developers can set live region settings that will provide a good user experience for most assistive technology users with little configuration on their part.

Identify the live regions

Live regions are any region on a page that receives dynamic updates. Note the regions of your page that will be live.
Decide the priority of each live region

When a live region changes, should the user be notified of the change? Notifications could include a sound for a screen reader user. (For simplicity, we will use the case of an audio notification in this discussion.) The shorter the interval between changes and the less important the information, the less likely that the user needs hears every change. A simple example of changes that should not be heard are changes to time; a sound for every second would be very annoying.

If the user should hear the change, should the change be announced immediately, as soon as possible, or only when the user is idle. Announcing a change immediately can be disorienting for users, so that should be done sparingly. Most updates should probably only be announced when the user is idle.

After you have decided the priority for each live region, then decide the live property value:
- Never spoken, then live="off"
- Spoken when user is idle, then live="polite"
- Spoken as soon as possible, then live="assertive"
- Spoken immediately, then live="rude"
Decide how much context is needed for each update
When part of a live region changes, how much context is needed to understand the change. Does the user need to hear the entire live region or just the change by itself?

If the user needs to hear the entire live region, then mark the entire live region with atomic="true".
Decide what types of changes are relevant for each live region

Three possible types of changes are: additions, removals, and text. Additions are new nodes added to the DOM; removals are nodes removed from the DOM; and text are changes solely to the textual content. Should the user hear all types of changes or only certain types?

By default, the user will hear additions and text type changes. If you wish to explicitly define the types of changes, you need to set relevant="THE_TYPES_OF_CHANGES". If more than one type of change is relevant, the types are separated by a space. For example, to define additions and removals as relevant but not text, set relevant="additions removals".
Decide if multiple output channels make sense

For most applications, a single output channel is sufficient. However, for complex applications with many updates happening simultaneously, multiple output channels may be advisable.

If you need to use multiple channels, then you need to separate the live regions on your page and decide which ones should go into which channel. To specify a channel for a live region, you set channel="THE_CHANNEL". By default, channel="main"; you can specify a higher priority channel by using channel="notify".

One of the most important concepts behind live regions is politeness. Politeness indicates how much priority a live region has. The following politeness settings are possible: live="off", live="polite", live="assertive", and live="rude".

live="off": This is the default. Any updates made to this region should not be announced to the user. live="off" would be a sensible setting for things that update very frequently such as timers that change every second.
live="polite": Any updates made to this region should only be announced if the user is not currently doing anything. live="polite" should be used in most situations involving live regions that present new information to users, such as updating news headlines.
live="assertive": Any updates made to this region are important enough to be announced to the user as soon as possible, but it is not necessary to immediately interrupt the user. live="assertive" should be used if there is information that a user should know about right away, for example, warning messages in a form that does validation on the fly.
live="rude": Any updates made to this region are extremely important. In fact, the updates are so important that the user must be interrupted immediately. live="rude" should be used sparingly and only with great consideration as it can be very annoying to users.

When a live region is updated, the update can often be announced on its own and still make sense. For example, if a news headline is added, it would make sense to simply announce the headline. However, sometimes the entire live region must be read in order to give the user enough context to make sense of the update. For example, it would not make sense to only give the current value of a stock without saying the name of the stock. The atomic setting gives assistive technologies a hint about which of these cases an update falls into.

atomic="false": This is the default. It means that when there is a change in the region, that change can be presented on its own; the AT should not present the entire region. atomic="false" is generally a good idea as it presents users with only changes and does not cause them to hear repetitive information that has not changed. However, web developers should take care that the changed information, when presented by itself, can still be understood and contextualized by the user.
atomic="true": If atomic is set to "true", it means that the region must be presented as a whole; when there is a change, the AT should present the entire region, not just the change. atomic="true" can make it harder for users to understand changes as the changed areas are not presented independently. atomic="true" can also be annoying as it can force users to listen to repetitive information that has not changed. However, atomic="true" is necessary in cases where the change, when presented by itself, cannot be understood and contextualized by the user.

Not all updates to a live region are relevant. For example, if the oldest headline in a list of headlines is removed and a new headline is added, the removal of the oldest headline is probably not important enough to announce to the user. However, in a chat application, when a user leaves the chat and their username is removed from the list of users, that removal may be important enough to announce. The relevant setting gives a hint about what types of changes are relevant and should be announced. Any change which is not relevant will be treated as if the region had live="off" and will not be announced. Multiple types of changes can be listed as relevant; the types are separated by a space. The default is relevant="additions text".

relevant="additions": relevant="additions" states that the insertion of nodes to the live region should be considered relevant.
relevant="removals": relevant="removals" states that the removal of nodes to the live region should be considered relevant.
relevant="text": relevant="text" states that changes to the textual content of nodes that already exist in the live region should be considered relevant. Textual content includes text equivalents, such as the alt attribute of images.

Some notifications should be spoken before regular messages without causing the regular messages to be dropped. An example of such a notification is a chat message that is directed at the user. In such a case, that message should be spoken before the other chat messages, but the other chat messages should still be spoken and not just dropped. In addition, some AT users have both speech synthesis and Braille - they may prefer notifications to be delivered to the Braille display while regular messages are spoken by the synthesizer.channel={main/notify}gives web developers a way to provide a hint about which updates should be routed to which hardware channel, and in the case that only one channel is available, how the updates should be interleaved. The user agent defines the mapping between main/notify channels to the hardware channels available on the user's system.

channel="main": This is the default. Messages in the main channel can only cancel out other messages in the main channel.
channel="notify": The notify channel is slightly higher priority than the main channel. If there are two messages of equal politeness waiting in both the notify and main channels and there is only one output channel, the message in the notify channel will be processed first. However, if the politeness values are different, then the message that is less polite will be processed first, regardless of which channel it is in. Messages in the notify channel can only cancel out other messages in the notify channel.

Example 1

The user is on an AT that supports only a single hardware channel.
Given: <div id="liveRegionA" aria-live="polite" aria-channel="main"> </div> <div id="liveRegionB" aria-live="polite" aria-channel="notify"> </div>
Both live regions get updates that are "polite" simultaneously. liveRegionB should be spoken first since it is on the notify channel.

Example 2

The user is on an AT that supports only a single hardware channel.
Given: <div id="liveRegionA" aria-live="assertive" aria-channel="main"> </div> <div id="liveRegionB" aria-live="polite" aria-channel="notify"> </div>
Both live regions get updates simultaneously. liveRegionA should be spoken first, because its message has a higher priority than liveRegionB.

5.3 Choosing between alert, status, log, and live regions

ARIA contains a number of standard roles which are by default considered "live" sections of your web page. It is important to know when to use these and when to create a custom live region on your known. Here are some rules of thumb:

alert - You should use the alert role for a one-time notification which shows for a period of time and goes away and is intended to alert the user that something has happened. The assistive technology should be notified, by the user agent, that an alert has occurred providing your operating system supports this type of event notification.

status - You should use the status role when you want to mark an area which is updated periodically and provides general status of your web application. Changes in status are not typically announced automatically by an assistive technology. However, it is possible to configure some assistive technologies, such as a scriptable screen reader, to watch for changes in the status bar and announce them. ARIA provides a property called templateid which allows the author to provide a unique id for an assistive technology to write custom script to handle customization such as with a status bar. Using the status role is also important in that the user could always check the status section for changes in status on different web pages. Many applications provide status widgets and they are often found, visibly, at the bottom of the application and contain a variety of widgets within it to convey status.

log - You should use log if you have a live aria where new information is added and old information is removed, like a scrolling chat log of text. Unlike other regions, there is implied semantics to indicate the arrival of new items and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. If the have a chat text entry area you should indicate that it also controls the aria log aria like so:
<div contenteditable="true" role="log" id="chatlog">
</div>
<label id="gettext">Send Text</label>
<div aria-controls="chatlog" 
     role="textbox" 
     contenteditable="true" 
     aria-readonly="false" 
     aria-labelledby="gettext">
</div>
   
live region - If you have some other live area use case, ARIA allows you to mark an area using the live attribute. This accompanied by the collection of attributes which support the live property allow you to create your own custom live area on your web page. For more details regarding live regions refer to the live region section of the this guide.

6 Form Properties

Until the introduction of ARIA's invalid state and required property, only presentational strategies have been available to web content authors to indicate that certain form fields and controls are required or invalid. In applications, the state of controls currently unavailable is indicated with a "grayed out" appearance. In web-based forms, fields required may be marked by an asterisk. Forms submitted with required data missing or improperly specified may be redisplayed with the unacceptable elements highlighted in red. The assistive technology user is poorly served by such imprecise methods, and all users confront inconsistent indicators for consistent situations.

The ARIA invalid state and required property provide:

A programmatic required indicator that all user agents, including especially assistive technologies, can represent to users in a consistent and modality appropriate manner.
A programmatic invalid role that can be used to indicate which data fields have incorrect data. This enables all user agents, including both mainstream browsers and assistive technology applications, to indicate this eternally common circumstance to users consistently, in a user-appropriate modality.
A programmatic mechanism, the invalid role, to indicate currently unavailable controls in Web 2.0 applications (which a user agent may choose to display as "grayed out").

7 Drag-and-Drop Support

Drag-and-drop operations are a common feature of Rich Internet Applications (RIAs). Drag-and-drop features have traditionally challenged people with functional disabilities. These problems arise from the difficulty of manipulating the mouse, finding targets capable of receiving the object being dragged, and actually moving the object to the drop target. Screen readers and alternate input systems assist the user to some degree by allowing the user to simulate a click, drag, and release operation. It is then up to the user to find a target that, hopefully, will receive the object being dragged. Additionally, the user may not be aware if the desired drop operation is supported or what source objects can be selected for dragging. The end result can be a very unproductive and frustrating experience.

ARIA introduces two new Drag and Drop properties that enable web application authors to facilitate with the drag and drop process, called grab and dropeffect. The property grab is applied to the source(s) being dragged, while aaa:dropeffect is applied to the target. Use of these properties--combined with best practices for enabling the user to select the appropriate drag operation and for assigning appropriate keyboard operations for dragging and dropping--will vastly improve the accessibility of drag and drop functionality. The following steps will guide you through the process.

Identify draggable objects

Set the initial grab state of all draggable interface objects. The default state for all objects is assumed to be false, meaning that they are not draggable. For objects that may be dragged, set the grab state to "supported". Note: it is very important that objects, capable of being dragged, have a determinable role. HTML tags, such as <div> and <span>, provide no semantics unlike <select>.

This step clearly marks elements that can be "grabbed" for drag-and-drop operation. Assistive technologies, such as screen readers or alternate input devices, can help the user move focus directly to the grab-supporting objects without having to navigate through all the elements and guess which could be ready to initiate a drag operation. Although not necessary, authors or intermediaries could use CSS to highlight those elements that may be grabbed.

All grabbable objects must be be navigable using the keyboard.
Allow the user to initiate the appropriate drag operation using the keyboard

ARIA provides three drag operation types:
- copy: A duplicate of the source object will be dropped onto the target.
- move: The source object will be removed from its original location and dropped onto the target.
- reference: A reference or short cut to the dragged object will be created in the target object.
To select a drag operation, the author must provide a keyboard accessible way of selecting one or more elements for drag. After the last object is selected for drag (if a single one object is used, it may simply be the last object with focus), the author should provide an ARIA-enabled pop-up menu from which the user can choose a supported operations from the list. A suggested way to do this is to use the Ctrl+Shift+F10 key sequence on the grab object. After the user has selected an action from the pop-up menu, the menu should close, with focus returning to the last object selected for grab. If the user does not choose an action and instead presses the Escape key (ESC), the application should dismiss the menu, returning focus to the last object selected for grab and from which the pop-up menu was launched.

Note: In implementations where only single operations are provided, the W3C ARIA Style Guide group is considering defining hot keys to initiate the appropriate drag operation.

All objects being grabbed must have their corresponding "aaa:grab" property set to "true." This will enable ATs to have a reference to the "grabbed" source object(s).
Mark the drop targets

Now that you know the drag operation, you must decide which target elements may receive the drop and mark those for the AT. You mark them by setting their dropeffect value to "copy", "move", or "reference." Like grab, drop targets must have a determinable role. CSS can also be used to highlight the targets to show sighted users which objects can receive a drop of the grabbed source(s). Any object without a "aaa:dropeffect" will have an assumed "aaa:dropeffect" value of "none." Any object with a "aaa:dropeffect" value of "none" is ignored by ATs in the drop operation.
Configure your script for AT drag-and-drop operations

You must now configure your script to handle mouse movements as if the user had depressed the mouse key and begun a drag. The AT will move the mouse to accepting drop targets based on its own keyboard navigation scheme defined for a drag. Drag operations usually show the source object(S) being moved, such as through the use of a bitmap representation drawn to follow the mouse cursor position, as the user moves the mouse while keeping the mouse button depressed. You need to perform the same operation with the exception that you ignore the mouse key's pressed state. AT will either move the mouse cursor automatically in response to their designated keyboard commands or through user tabbing to targeted elements. At some point, the user will have the mouse cursor over the desired drop target. You should assume that the user's pressing hitting the Enter key will cause the selected drop operation to occur on the drop target. This completes the drop operation.

If at any time during the drag process, the user pressed the Escape key to cancel drag operations, all dropeffect properties should be set to "none", keyboard focus should return to the last grabbed source object, and all "aaa:grab" properties should be set to "supported."
Clean-up after drag/drop

Once the drop has occurred, you should clean up the DOM as you would do for any drag/drop operation. You must then set focus to the appropriate DOM element and its role should also be determinable.
Other considerations

Should the author wish to let the user decide which drop operation is chosen at the target, the author may use a single key sequence at the source to activate a grab and then set the drop effects that are possible on the accepting targets:

Example:
```
<div role="treeitem" aria-dropeffect="copy move"> 
```
This allows the AT to surface to the user the drop effects that are available. Once the user navigates to the target, execute the drop. The author must provide the ability for the user to launch an ARIA-enabled pop-up menu to select the appropriate drop operation which is determined upon user selection. At this point, the author must perform the appropriate clean-up operations discussed in Step 5.

8 Use of Alerts and Dialogs

An alert is some information that tells the user about an unexpected, undesirable, or risky condition. The alert and alertdialog values of role should be used to mark elements delivering information of this nature.

If the user only needs to be notified of the condition and if you do not want to require an explicit action or acknowledgement of the alert from the user, the use the alert role and leave the focus unchanged. If, however, the user does need to acknowledge the condition or select a next step to address the issue, then launch a new window and mark it with the alertdialog role. Also save the previous focus so that the user can, when possible, return to the originating window and context after dismissing the alert dialog window.

An alert may be a popup region or it may be information presented in a way that does not disturb the layout. A typical example of the latter is when space is reserved in a form for an statement about the user input. The error explanation is only filled in or exposed if the user has input invalid data. But the alert is performed in the context of the form control and without disrupting the visual context established by the overall layout. Even in this inline error explanation case, the explanation of the error should be assigned an 'alert' role.

9 Implementation Guidance

For these widgets and structures, this document describes the keyboard and mouse interaction, styling considerations, ARIA roles and properties.

9.1 Widgets

Widgets in rich web applications are individual entities or controls. They are typically contained in larger entities.

Button
Menu
MenuButton
ComboButton
Checkbox
RadioButton

Characteristics:
Description:	button widgets allow for user-triggered actions, and they are most often used for discrete, atomic actions. Buttons support the optional state pressed. Buttons with this state present are toggle buttons. When pressed is "true" the button is depressed, when pressed is "false" it is not depressed.
Keyboard Interaction:	With focus on the button, pressing Spacebar or Enter keys executes the action for that button. If the button activation closes the containing entity or launches another entity, then focus moves to the newly opened entity. If the button activation does not close or dismiss the containing entity, then focus remains on the button. An example might be an Apply or Recalculate button.
Mouse Interaction:	Clicking on the button executes the action for the button. If focus is on another element when a button is clicked with a mouse, the focus moves to the clicked button. If focus is on another element and the mouse is moved over a button, a visual indicator is provided to show that the button may be clicked, but focus does not yet move. If focus is on another element and the mouse is moved over a button then moved away, the visual indicator goes away and focus is unchanged.
Styling:	When the button is in a pressed state -- either briefly when Enter or Spacebar are pressed or when the primary mouse button has been pressed but not released, then the visual appearance is altered to differentiate the pressed from an unpressed state.
ARIA Roles, States, and Properties:	The button receives a role of button. The button description receives a role of role="wairole:description" and the describedby property. When the action associated with a button is unavailable, the button displays in a disabled state.
Example:	XHTML button

Characteristics:
Description:	A menu is a control offering the user a list of choices. A menu is often a list of links to important sections of a document or a site. Menus contain menuitems, and they are typically collected on a menubar.
Keyboard Interaction:	First item in menu bar should be in the tab order (tabindex=0). If a menu bar item has focus, then: Pressing Enter, Spacebar, or the up or down arrow keys opens the menu and places focus on the first menu item in the opened menu or child menu bar. If no menu is open, pressing left or right arrow keys moves focus to the adjacent menu bar items. When a menu is open and focus is on a menu item in that open menu, then Pressing Enter or Spacebar invokes that menu action (which may be to open a submenu). Pressing up or down arrow keys cycles focus through the items in that menu. If the menu item with focus has a submenu, pressing Enter, Spacebar, or the right arrow key opens the submenu and puts focus on the first submenu item. Pressing Escape closes the open menu or submenu and returns focus to the parent menu item. When a submenu is open and focus is on a menu item in that submenu: The up or down arrow keys cycle through the submenu items (behaves the same as open menu). Pressing Escape or the left arrow key closes the submenu and returns focus to the parent menu item. Disabled menu items receive focus but have no action when enter or left/right arrow is pressed. Tabbing out of the menu component closes any open menus. With focus on a menu item and a sub menu opened via mouse behavior, pressing down arrow moves focus to the first item in the sub menu. With focus on a menu item and a sub menu opened via mouse behavior, pressing up arrow moves focus to the last item in the sub menu. With focus on a submenu item, the user must use arrows or the Escape key to progressively close submenus and move up to the parent item(s).
Mouse Interaction:	Primary mouse click on a closed menu opens the menu; a second mouse click on the menu item closes the menu. Primary mouse click on a menu item invokes that menu action (which may be to open a submenu). A primary mouse click away from an open menu closes the menu.
Styling:
ARIA Roles, States, and Properties:	Has the role menu, with required child elements of menuitems. Has the parent roles widget and list.
Example:	XHTML Spreadsheet

Characteristics:
Description:	This might also be called a drop-down button. Pressing the button causes a drop-down menu to display. The user can then select an item from the menu.
Keyboard Interaction:	With focus on the button pressing space or enter will toggle the display of the drop-down menu. Focus remains on the button. With focus on the button and no drop down menu displayed, pressing down arrow will open the drop-down menu and move focus into the menu and onto the first menu item. With focus on the button and the drop-down menu open, pressing down arrow will move focus into the menu onto the first menu item. With focus on the drop-down menu, the up and down arrow keys move focus within the menu items, "wrapping" at the top and bottom. With focus on the drop-down menu, pressing escape closes the menu and returns focus to the button. With focus on the button pressing the tab key will take the user to the next tab focusable item on the page. With focus on the drop-down menu, pressing the tab key will take the user to the next tab focusable item on the page. Note that this may be difficult to achieve on a web page.
Mouse Interaction:	Clicking on the button toggles opening/closing the associated menu. Focus is set on the button. Clicking on a item in the opened drop-down menu executes the action for that menu item and closes the menu. Focus returns to the button. Mouse out of an opened menu closes the menu and returns focus to the button. Mouse over of an opened menu changes the visual indicator to indicate that it is the current choice. Should mouse over actually set focus? At a minimum the button object needs to know what the current menu item is so the mouse and keyboard can interact.
Styling:
ARIA Roles, States, and Properties:	Option 1: The button receives a role of button with an owns property, if necessary. The drop-down menu has a role of menu. May have a hasparent property depending upon whether or not implementation creates children within the hierarchy of the parent button or not. Each menu item has a role of menuitem. May have a hasparent property depending upon whether or not implementation creates children within the hierarchy of the parent menu. Option 2: The button receives a role of menu with an owns property depending upon whether or not the drop-down menu is created as a direct child element of the button in the DOM hierarchy.
Example:	XHTML Spreadsheet

Characteristics:
Description:	The Combo Box control has a static text field label explicitly associated with the control. Optionally the label has a mnemonic to aide navigation.
Keyboard Interaction:	Tab moves focus to the drop-down button. Left arrow moves focus from the button into the text field. Enter posts the list. When menu is posted, up arrow and down arrow keys move highlight and selection up or down within the list. Enter or spacebar closes the list, maintaining latest selection (highlighted item). Escape dismisses the list and reverts to the prior selection.
Mouse Interaction:	RMB click in text area moves focus into text area and displays insertion cursor. RMB click on down-arrow button toggles post / unposting of the list. RMB on list item selects the item. RMB away from control also unposts list.
Styling:
ARIA Roles, States, and Properties:	A combo box uses the WAI-ARIA roles: combobox for box itself textbox for the editable portion of the box listitem for the items displayed in the combo box when it is opened Combo boxes use the ARIA properties disabled, readonly, and expanded.
Example:	Editable Combo Box supported in Firefox

Characteristics:
Description:	A checkbox is an input option that represents a setting or value with an on, off, or mixed choice. A check mark within the checkbox indicates that the setting is selected or checked. Checkboxes in a group are non-exclusive options; more than one checkbox in a group can be checked at any given time.
Keyboard Interaction:	When focus is on a checkbox, the Spacebar key toggles the selection, checking or unchecking the box.
Mouse Interaction:	Clicking on a checkbox with the primary mouse button toggles its selection.
Styling:	Checkboxes are typically represented as squares with a check mark inside when checked. If the checkbox is in an undetermined state, its appearance will resemble a disabled state.
ARIA Roles, States, and Properties:	A two-state checkbox uses the role checkbox with the state checked, where checked can have the value true or false. A checkbox that also supports a mixed state also uses the role checkbox, but the state checked has the value mixed. They may have the properties describedby and labelledby; see ARIA Relationships ([WAI-ARIA], Section 4.2.5).
Example:	Checkbox with title for accessible name

Characteristics:
Description:	A radio button is one of a group of controls representing mutually-exclusive choices. A radio button is typically represented as a round control to distinguish from the square checkbox control. It supports the events: Set selection Fills in circular control of radio button with current focus, clearing any prior selection in the group. May be referred to as checked. Clear selection Indirect. Occurs when selection is explicitly set in other radio button in group.
Keyboard Interaction:	Focus can move to a radio group via: The Tab key An Access Key or mnemonic targeting the label Activation of the label (through Assistive Technology mechanism) The Tab key moves focus between radio button groups and other widgets. When focus is on the group and when no radio button is selected: Tab key press moves focus to the first radio button in the group, but does not select the radio button. Shift+Tab key press moves focus to the last radio button in the group, but does not select the radio button. When focus moves to the group in which a radio button is selected, pressing Tab and Shift+Tab keys move focus to the radio button that is checked. Up Arrow and Down Arrow keys move focus and selection. Up Arrow key press moves focus and selection forward through the radio buttons in the group. If the first radio button has focus, then focus and selection move to the last radio button in the group. Down Arrow key press moves focus and selection backward through the radio buttons in the group. If the last radio button has focus, then focus and selection move to the first radio button in the group. * Space Bar key press checks the radio button that currently has focus. When re-entering the group, focus returns to the point of previous focus (the item with selection set). Pressing the Tab key exits the group and moves focus to the next form control. Pressing the Shift+Tab keys exits the group and moves focus to the previous form control.
Mouse Interaction:	A primary mouse button click on an unselected item selects that radio button and clears any other selected radio button in the group.
Styling:
ARIA Roles, States, and Properties:	The radio button control uses the role radio. The group of radio controls uses the role radiogroup. It uses the state checked and the properties labelledby and activedescendant.
Example:	Sample radio buttons. Please note that not all examples work in all browser and version combinations. For example, note the compatibility statement.

9.2 Structures

Structures are objects that contain and organize widgets.

TabPanel
TreeView
Multi-ColumnTreeGrid

Characteristics:
Description:	A tabbed interface component is a container for resources associated with a tab. It is a set of layered pages where only one page is displayed at a time. The general look is similar to a file folder with a "tab" that contains the title of the folder. The tabs are arranged along one of the edges of the contents but most commonly are found at the top of the page. The user navigates and makes the contents of each page visible by interacting with the title "tab" of the page. Sometimes referred to as a tab container or tab panel. Terms for understanding Tab Panels include: tabbed interface component a set of tabs and associated tab panels tab panel contents area that is associated with a tab tab the label/title area of the tab panel. This is where you click to activate a tab panel tablist the set of tabs When the user activates a tab, the contents of that tab is made visible. The tab is considered "active". The tab remains active until another tab is activated. The active tab is placed into the tab order. Only the active tab should be in the tab order. A default tab is specified that is active when the tabbed interface component is initialized. A collection of tabs and their associated tab panels is a complex widget, because it performs show/hide actions as well as moving the user's point of regard around within the content.
Keyboard Interaction:	Tab - only the active tab is in the tab order. The user reaches the tabbed panel component by pressing the tab key until the active tab title receives focus. left arrow - with focus on a tab, pressing the left arrow will move focus to the previous tab in the tab list and activate that tab. Pressing the left arrow when the focus is on the first tab in the tab list will move focus and activate the last tab in the list. Right arrow - with focus on a tab, pressing the right arrow will move focus to the next tab in the tab list and activate that tab. Pressing the right arrow when the focus is on the last tab in the tab list will move focus to and activate the first tab in the list. Up arrow - behaves the same as left arrow in order to support vertical tabs Down arrow - behaves the same as right arrow in order to support vertical tabs Ctrl-Up arrow - with focus anywhere within the tab panel, pressing ctrl-up arrow will move focus to the tab for that panel. This is not standard behavior - is this something we want to implement? Is it necessary if we provide a mechanism to change the active tab? Similar to ctrl-pageup/pagedown in Firefox to switch tabs? Alt-Del - When deletion is allowed, with focus anywhere within the tab panel, pressing alt-del will delete the current tab and tab panel from the tabbed interface control. If additional tabs remain in the tabbed interface, focus goes to the next tab in the tab list. An alternative to providing a keystroke to close a tab is to provide a context menu that is associated with the tab title. When focus is on the tab, pressing shift-F10 or pressing the right mouse button will open a context menu with the close choice Ctrl-PageUp - When focus is inside of a tab panel, pressing ctrl-pageup moves focus to the tab of the previous tab in the tab list and activates that tab. When focus is in the first tab panel in the tab list, pressing ctrl-pageup will move focus to the last tab in the tab list and activate that tab. Ctrl-PageDown - When focus is inside of a tab panel, pressing ctrl-pagedown moves focus to the tab of the next tab in the tab list and activates that tab. When focus is in the last tab panel in the tab list, pressing ctrl-pageup will move focus to the first tab in the tab list and activate that tab. Regarding Ctrl-PageUp/PageDown. This is currently implemented in Firefox to move between browser tabs. Firefox also supports ctrl-tab and ctrl-shift-tab to move between tabs. Internet Explorer 7 also uses Ctrl-Tab and Ctrl-Shift-Tab. There may be advantages to using Ctrl-PageUp/PageDown as the keys to change tabs since it is a recognizable keystroke to at least Firefox users and is also supported by the Windows operating system to move between panels in a tabbed dialog. The problem is that if the user is within a tabbed interface control on a Web page, they can not easily switch browser tabs without first moving focus outside of the tabbed interface control. This may be acceptable. The other issue is if the entire Web page is a tabbed interface control - in that case the user could not ever switch browser tabs unless the control on the Web page ignored the ctlr-pageup/pagedown keypress (and thus letting the browser access it) when the first or last tab was reached.
Mouse Interaction:	Clicking on the tab title activates the tab and sets focus to the tab title.
Styling:	The active tab is visually differentiated from the other tabs. This style should be visible in high contrast mode. Focus on the tab is usually indicated as focus on the title text/element of the tab. Setting focus to the tab activates that tab.
ARIA Roles, States, and Properties:	The tabbed interface component uses the role tabpanel. The tabbed panel contains tabs and their panels. An element with role tab is used as a grouping label, providing a link for selecting the tabcontent to be rendered to the user. The currently selected tab has the state selected=true. A tablist is the container role for a set of elements with the role attribute set to tab.
Example:

Characteristics:
Description:	A tree view is a component to navigate hierarchical lists. It is made up of one or more top level nodes. A node may have children or it may be an end node. Nodes with children can be expanded or collapsed - when expanded its child nodes are visible. When collapsed the children are not visible. There is generally some sort of visual indication whether a node has children and can be expanded. Any number of nodes can be expanded at a time and child nodes may contain children. A tree node is commonly used to navigate the directories and files on a file system. The directory nodes can be expanded and collapsed to reveal its contained subdirectories and files. Terms for understanding tree views include: node An item in a tree. parent node Node with children. It can be opened / expanded or closed / collapsed open node Expanded node with children; first-level children are visible. closed node Closed node with children; the children are not visible. end node Node with no children General behavior for tree views follows: On first load of the tree component, the top level node is in the tab order. One and only one node of the tree component is in the tab order of the page at any time. The last visited node in the tree control is retained in the tab order when the user navigates away from the tree control. Nodes can be focused and/or selected. There must be visual distinction between focused and selected nodes. Arrowing to an item with the keyboard or clicking on an item with the mouse will focus and select the node. Any previous selections are cleared
Keyboard Interaction:	Up and down arrow keys move between visible nodes Left arrow key on an expanded node closes the node Left arrow key on a closed or end node moves focus to the node's parent Right arrow key expands a closed node, moves to the first child of an open node, or does nothing on an end node. Enter key causes on-double-click action on end nodes. Open issue: are there ever parent nodes that have an action other than expand or collapse? Typing a letter key moves focus to the next instance of a visible node whose title begins with that letter. Home key moves to the top node in the tree view End key moves to the last visible node in the tree view Ctrl-Arrow to an item with the keyboard focuses the item (but does not select it). Previous selections are maintained. Ctrl-Arrow-Space - Selects non-contiguous nodes Ctrl-Spacebar with focus on an item toggles the selection of the item Shift-UpArrow - Extends selection up one node Shift-DownArrow - Extends selection down one node Shift-Home - Extends selection up to the top-most node Shift-PageDown - Extends selection down to the last node *(asterisk) on keypad - Expands all nodes
Mouse Interaction:	Click on a node sets focus and selects the node Ctrl-click on a node focuses and selects the node. Previous selections are maintained. Double click on an end node causes any associated action to be invoked. Open issue: are there ever parent nodes that have an action other than expand or collapse? Click on a closed node opens the node. Click on expand / collapse icon associated with a parent node toggles the expand/collapse of the node Note: The user should be able to switch between using the mouse and using the keyboard to interact with the tree component.
Styling:	Parent nodes generally have some visual icon to indicate the ability to expand or collapse the node. The convention is that a plus (+) icon is displayed when the parent node is collapsed, the user clicks on this icon to expand the node. A minus icon is displayed when the parent node is expanded, the user clicks on this icon to collapse the node. The expand and collapse behavior can also be invoked via the right and left arrow keys when focus is on the node as described in the Keyboard Behavior section above. A selected node should be indicated via a visual styling such as color difference and/or a distinct border. The browser will generally provide visual identification of focused nodes.
ARIA Roles, States, and Properties:	A tree view uses the ARIA role tree, where tree is a main container element. A tree can itself contain subtrees that may be collapsed and expanded; these have the role treeitem. A collection of treeitems to be expanded and collapsed are enclosed in a group. See the XHTML example in the WAI-ARIA [WAI-ARIA] specification.
Example:

Characteristics:
Description:
Keyboard Interaction:
Mouse Interaction:
Styling:
ARIA Roles, States, and Properties:
Example:	This example contains a Grid with an expandable, all column-spanning row forming having a sub row below as its content. ARIA roles and states have been applied to all grid cells.

10 Reusable Component Libraries

11 Testing

This page contains links to resources containing test files, sample widgets, etc. Please add other known resources here. The plan is to expand this to index all known test cases, categorized.

11.1 Test case details

The following table details test cases.

Columns:

Concept: ARIA concept Sample (widget, application, region layout, etc.)
ARIA Features: ARIA roles, states, properties being demonstrated for the concept
Description: Detailed description of the example
Reference: Link to sample

TEST CASE DETAILS
Concept	ARIA Features	Description	Reference
Widget	Widget	{Description}	Link
checkbox	Uses role="checkbox" and checked state	Accessible checkbox created without the input element.	XHTML version HTML version
slider	Uses role="slider" and ARIA states: valuenow, valuemax, valuemin	Accessible slider widget	Graphical XHTML slider Basic XHTML slider
progress bar	Uses role="progressbar" and ARIA states: valuenow, valuemax, valuemin	This is an accessible XHTML progress bar	XHTML progress bar
alert	Uses role="alert"	This is an accessible alert created using a div. The visibility style is changed from "hidden" to "visible" to hide and show it.	XHTML alert HTML alert
tree	Uses role="tree", role="treeitem", role="group" to group subtrees, expanded state	This is an example of a tree widget role. Each item in the tree has a role of "treeitem" and subtrees are grouped using the "group" role. The expanded state is set on tree items to indicate if its subtree is expanded. This example relies on the static DOM structure to allow the user agent to convey "level" semantics to the assistive technology.	XHTML tree HTML tree
tree controlling a region	role="secondary" and controls property	Uses a tree widget that uses Ajax to acquire a picture and render it in a region. The widget, having a role of tree, controls the "secondary" region. Select assistive technologies should allow the user to follow the controls property.	Simple HTML Ajax example of a tree widget controlling a region
button and description	role="button" role="description" and the describedby property	Provides an accessible pushbutton without using an input element. This examples sets up two description areas and uses describedby to associate the button and the fieldset with the description areas. Pushing the button uses javascript to launch an alert	XHTML button
grid, gridcell, and columheader	roles: grid, gridcell, columnheader; ARIA properties: readonly, selected, tabindex	Provides an accessible spreadsheet, using the grid role, which you can tab to the grid. Arrow keys are then used to navigate the gridcells within the grid.	XHTML spreadsheet
menu, menubar, menuitem	roles: menubar, menu, menuitem, ARIA properties: tabindex	Provides an accessible horizontal menu and uses the DOM hierarchy to provide the menu structure to the assistive technology. This example uses tabindex to manage focus within the menu.	XHTML menu

11.2 Test Result Matrix

The following definition list details test cases.

Concept: ARIA concept (for example, widget, application, region, layout, etc.)
ARIA Features: WAI-ARIA [ARIA] roles, states, and properties being demonstrated for the concept
Description: Detailed description of the example
Reference: Link to example
Test Results: Link to test results for each linked example

Concept: checkbox

ARIA Features: Uses role="checkbox" and checked state

Description: Accessible checkbox created without the input element.

Reference 1: XHTML checkbox example

Reference 2: HTML checkbox example

Test Results:

Reference 1 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 2 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: slider

ARIA Features: Uses role="slider" and ARIA states: valuenow, valuemax, valuemin

Description: Accessible slider widget

Reference 3: Graphical XHTML slider

Reference 4: Basic XHTML slider

Test Results:

Reference 3 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 4 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: progressbar

ARIA Features: Uses role="progressbar" and ARIA states: valuenow, valuemax, valuemin

Description: This is an accessible XHTML progress bar

Reference 5: XHTML progress bar

Test Results:

Reference 5 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: alert

ARIA Features: Uses role="alert"

Description: This is an accessible alert created using a div. The visibility style is changed from "hidden" to "visible" to hide and show it.

Reference 6: XHTML alert

Reference 7: HTML alert

Test Results:

Reference 6 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 7 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: tree

ARIA Features: Uses role="tree", role="treeitem", role="group" to group subtrees, expanded state

Description: This is an example of a tree widget role. Each item in the tree has a role of "treeitem" and subtrees are grouped using the "group" role. The expanded state is set on tree items to indicate if its subtree is expanded. This example relies on the static DOM structure to allow the user agent to convey "level" semantics to the assistive technology.

Reference 8: XHTML tree

Reference 9: HTML tree

Test Results:

Reference 8 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 9 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: tree controlling a region

ARIA Features: role="secondary" and controls property

Description: Uses a tree widget that uses Ajax to acquire a picture and render it in a region. The widget, having a role of tree, controls the "secondary" region. Select assistive technologies should allow the user to follow the controls property.

Reference 10: Simple HTML Ajax example of a tree widget controlling a region

Test Results:

Reference 10 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: button and description

ARIA Features: role="button" role="description" and the describedby property

Description: Provides an accessible pushbutton without using an input element. This examples sets up two description areas and uses describedby to associate the button and the fieldset with the description areas. Pushing the button uses javascript to launch an alert

Reference 11: XHTML button example

Test Results:

Reference 11 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: grid, gridcell, and columnheader

ARIA Features: roles: grid, gridcell, columnheader; ARIA properties: readonly, selected, tabindex

Description: Provides an accessible spreadsheet, using the grid role, which you can tab to the grid. Arrow keys are then used to navigate the gridcells within the grid.

Reference 12: XHTML spreadsheet example

Test Results:

Reference 12 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]

Concept: menu, menubar, menuitem

ARIA Features: roles: menubar, menu, menuitem, ARIA properties: tabindex

Description: Provides an accessible horizontal menu and uses the DOM hierarchy to provide the menu structure to the assistive technology. This example uses tabindex to manage focus within the menu.

Reference 13: XHTML menu

Test Results:

Reference 13 tested with JAWS 8.00.2173/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 13 tested with NVDA ( build)/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 13 tested with Orca *.*/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 13 tested with Window-Eyes *.*/Minefield Build 3.0a9pre [2007-10-23 build]
Reference 13 tested with FireVox ()/Firefox 2.* [build ]
Reference 13 tested with ZoomText (*.*)/Minefield Build 3.0a9pre [2007-10-23 build]

This is a placeholder anchor for the references to be added.

12 Appendices

12.1 Roles, States, and Properties Mapped to Accessibility APIs

This section is informative.

Mapped properties (Please note: This is a common subset of all mapping options)

ARIA	MSAA	IAccessible2	ATK
disabled	MSAA:STATE_SYSTEM_UNAVAILABLE		ATK:ATK_STATE_DISABLED
checked	MSAA: STATE_SYSTEM_CHECKED		ATK: ATK_STATE_CHECKED
expanded	If the hidden property is set to true : MSAA:STATE_SYSTEM_COLLAPSED If the hidden property is set to false: MSAA:STATE_SYSTEM_EXPANDED		If the hidden property is set to true : ATK: ATK_STATE_EXPANDABLE If the hidden property is set to false: ATK:ATK_STATE_EXPANDED
haspopup	This state should be mapped to true on Windows systems when an event handler has a role of pop-up menu. MSAA: haspopup		ATK: not necessary in ATK because it has multiple actions with description
invalid	MSAA: no mapping In the case of MSAA the user agent should provide a specialized API to return its value. Alternatively, if the user agent provides a specialized API for XForms [XForms] it may provide invalid(), outOfRange(), or empty() (returns true when required but not available). This information is computed from the instance data associated with the form element.	IA2_STATE_INVALID	ATK:ATK_STATE_INVALID
multiselectable	MSAA:STATE_SYSTEM_EXTSELECTABLE		ATK:ATK_STATE_MULTISELECTABLE
pressed	MSAA: STATE_SYSTEM_PRESSED is true when checked.		ATK: ATK_STATE_PRESSED is true when checked
readonly	MSAA:STATE_SYSTEM_READONLY		ATK:ATK_STATE_READONLY=inverse of readonly
required	MSAA: There is no mapping. User agent must make available through the DOM [DOM] or a specialized API. Note: While optional could be combined with required this is kept to be consistent with CSS3 pseudo classes and XForms [XForms].		ATK: There is no mapping.
selected	MSAA:STATE_SYSTEM_SELECTED		ATK:ATK_STATE_SELECTED
unknown	MSAA:mixed		ATK:indeterminate
value	MSAA: should return the value for getValue().		ATK: should return this as part of the AccessibleValue structure.

(As yet) unmapped properties are:

valuemax valuemin invalid describedby labelledby tabindex flowto controls

12.2 ToDo List

This page holds information about issues that we've determined need clarification, but a home for the clarification has not yet been determined.

Menus can contain menubars, and menubars can contain menus. Explain how this works, and which one would one use as the outermost container? Also relationship of toolbars to menubars.
If instances of a role must appear as children or descendants of instances of another role (e.g., listitems must be in a list), descendants of that role inherit the same rules. The rules must be carefully constructed, and it is not the case that the container restrictions are mutual. E.g., a role may be required to have certain descendants, but those descendants can appear in multiple types of parents. Or a role may be required to appear in a particular parent, but that parent is not restricted to have only that role as a descendant.
Cover the association of tabs and tabpanels by labelledby and controls, and check against what the Style Guide group is assuming is the behavior.
Explain trees very thoroughly, including general case, and the special case of "sliced trees" in which level and setsize must be used.
Describe various sorting algorithms, related to the sort property. Combination of ARIA properties and existing components.

12.3 User Agent Implementation Considerations

12.3.1 Managing Showing and Hiding document sections

12.3.2 Notification of changes to sections

12.3.3 ARIA to Accessibility API Events

12.3.4 Role Mappings

12.3.5 Mapping to platform accessibility APIs

User agents should map ARIA role and property semantics to the closest appropriate matches in their supported accessibility API. When it is not possible to find an exact match for a given role or property, API extensions should be utilized to expose the complete information.

12.4 References

This section is informative.

[ARIA]: Accessible Rich Internet Applications (WAI-ARIA) Version 1.0. L. Seeman, M. Cooper, R. Schwerdtfeger, L. Pappas, Editors, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA is available at http://www.w3.org/TR/2008/WD-wai-aria-20080204/. Latest version of WAI-ARIA available at http://www.w3.org/TR/wai-aria/.
[ARIA-PRIMER]: WAI-ARIA Primer. L. Pappas, R. Schwerdtfeger, M. Cooper, Editors, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA Primer is available at http://www.w3.org/TR/2008/WD-wai-aria-primer-20080204/. Latest version of WAI-ARIA Primer available at http://www.w3.org/TR/wai-aria-primer/.
[ARIA-ROADMAP]: Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap), R. Schwerdtfeger, Editor, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA Roadmap is available at http://www.w3.org/TR/2008/WD-wai-aria-roadmap-20080204/. Latest version of WAI-ARIA Roadmap available at http://www.w3.org/TR/wai-aria-roadmap/.
[DOM]: Document Object Model (DOM) Level 2 Core Specification, L. Wood, G. Nicol, A. Le Hors, J. Robie, S. Byrne, P. Le Hégaret, M. Champion, Editors, W3C Recommendation, 13 November 2000, http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/. Latest version of DOM Core available at http://www.w3.org/TR/DOM-Level-2-Core/.
[XFORMS]: XForms 1.0 (Third Edition), J. Boyer, Editor, W3C Recommendation, 29 October 2007, http://www.w3.org/TR/2007/REC-xforms-20071029/. Latest version of XForms available at http://www.w3.org/TR/xforms/.
[XHTMLMOD]: XHTML™ Modularization 1.1, M. Altheim, F. Boumphrey, S. McCarron, S. Schnitzenbaumer, S. Dooley, T. Wugofski, Editors, W3C Working Draft (work in progress), 5 July 2006, http://www.w3.org/TR/2006/WD-xhtml-modularization-20060705/. Latest version of XHTML Modularization available at http://www.w3.org/TR/xhtml-modularization/.

12.5 Acknowledgments

This section is informative.

The following contributed to the development of this document.

12.5.1 Participants active in the PFWG at the time of publication

Chris Blouch (AOL)
Charles Chen (Google)
Michael Cooper (W3C/MIT)
Dimitar Denev (FIT)
Donald Evans (AOL)
Kentarou Fukuda (IBM)
Alfred S. Gilman (W3C Invited Expert)
Jon Gunderson (UIUC)
Kenny Johar (Vision Australia)
Diego La Monica (IWA/HWG)
Aaron Leventhal (IBM)
Thomas Logan (Invited Expert, BayFirst Solutions)
Matt May (Adobe)
Charles McCathieNevile (Opera)
Lisa Pappas (Invited Expert, SAS)
Dave Pawson (RNIB)
David Poehlman (Invited Expert, State of MD)
Gregory Rosmaita (Invited Expert, The Linux Foundation)
Janina Sajka (Invited Expert, The Linux Foundation)
Stefan Schnabel (SAP)
Richard Schwerdtfeger (IBM)
Lisa Seeman (UB Access)
Marc Silbey (Microsoft)
Mike Squillace (IBM)
Gottfried Zimmermann (Access Technologies Group)

12.5.2 Other previously active PFWG participants and other contributors to the Accessible Rich Internet Applications specification

Special thanks to Aaron Leventhal for effort and insight as he implemented a working prototype of accessibility API bindings.

Jim Allan (TSBVI), Simon Bates, Judy Brewer (W3C/MIT), Christian Cohrs, Becky Gibson (IBM), Andres Gonzalez (Adobe), Georgios Grigoriadis (SAP AG), Jeff Grimes (Oracle), Barbara Hartel, Sean Hayes (Microsoft), John Hrvatin (Microsoft), Earl Johnson (Sun), Masahiko Kaneko (Microsoft), Jael Kurz, Alex Li (SAP AG), William Loughborough, Linda Mao (Microsoft), Anders Markussen (Opera), Dave Pawson (RNIB), T.V. Raman (Google), Vitaly Sourikov, Ryan Williams (Oracle), Tom Wlodkowski.

12.5.3 Enabling funders

This publication has been funded in part with Federal funds from the U.S. Department of Education under contract number ED05CO0039. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.

WAI-ARIA Best Practices

W3C Working Draft 4 February 2008

Abstract

Status of This Document

Table of Contents

1 Introduction

2 General Steps for Building an Accessible Widget with ARIA

3 Keyboard and Structural Navigation

3.1 Understanding Navigation and General Issues

3.1.1 ARIA Keyboard Bindings and Behaviors

3.1.2 Keyboard Navigation between Widgets

3.1.3 Keyboard Navigation within Widgets

3.1.4 Example Keyboard Operation: Radio Group/Radio

3.1.5 Other Widget Best Practices

3.1.6 Validation Issues

3.2 Providing Keyboard Focus

3.2.1 Tabindex

3.2.2 activedescendant

3.2.3 Author-Defined Keyboard Short-Cuts or Mnemonics

3.3 Supporting Tooltips with the Keyboard

3.4 Providing Logical Layout Semantics using Structural Roles

3.4.1 Regions and XHTML Role Landmarks

3.4.2 Structural Roles used to facilitate assistive technology navigation

3.4.3 Implicit Nesting and Headings

3.4.3.1 Header Levels versus Nesting Levels

3.4.3.2 Owns Repairs Nesting

3.4.4 Grouping, Regions, and Directories

3.4.4.1 Groups and their applicability

3.4.4.2 Regions vs. groups

3.4.4.3 Directories and their applicability

3.4.5 Remaining structural roles

3.4.5.1 Tabular structure related roles supporting tabular widgets

3.4.5.2 Marking Description sections

4 Relationships

4.1 Labeling and Describing

4.1.1 Labelled By

4.1.2 Described By

4.2 Owning and Controlling

4.3 Changing the Reading Flow

5 Document Management

5.1 Managing Content and Presentational Changes

5.2 Implementing Live Regions

5.3 Choosing between alert, status, log, and live regions

6 Form Properties

7 Drag-and-Drop Support

8 Use of Alerts and Dialogs

9 Implementation Guidance

9.1 Widgets

Widget: Button

Widget: Menu

Widget: Menu Button

Widget: Combo Button

Checkbox

Widget: Radio Button

9.2 Structures

Widget: Tab Panel

Widget: Tree View

Widget: Multi-Column Tree Grid

10 Reusable Component Libraries

11 Testing

11.1 Test case details

11.2 Test Result Matrix

12 Appendices

12.1 Roles, States, and Properties Mapped to Accessibility APIs

12.2 ToDo List

12.3 User Agent Implementation Considerations

12.3.1 Managing Showing and Hiding document sections

12.3.2 Notification of changes to sections

12.3.3 ARIA to Accessibility API Events

12.3.4 Role Mappings

12.3.5 Mapping to platform accessibility APIs

12.4 References

12.5 Acknowledgments

12.5.1 Participants active in the PFWG at the time of publication

12.5.2 Other previously active PFWG participants and other contributors to the Accessible Rich Internet Applications specification

12.5.3 Enabling funders