[contents]

W3C

WAI-ARIA 1.0 Authoring Practices

An author's guide to understanding and implementing Accessible Rich Internet Applications

W3C Editors' Draft 8 April 2014

This version:
http://www.w3.org/WAI/PF/aria-practices/
Previous editors' draft:
http://www.w3.org/WAI/PF/aria-practices/20091214/
Latest public version:
http://www.w3.org/TR/wai-aria-practices/
Editors:
Joseph Scheuhammer, Invited Expert
Michael Cooper, W3C
Previous Editors:
Lisa Pappas, Society for Technical Communication
Richard Schwerdtfeger, IBM

Abstract

This document provides readers with an understanding of how to use WAI-ARIA [ARIA] to create accessible rich internet applications. It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties. This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers. This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is an internal Editor's Draft of the Protocols and Formats Working Group. It is not stable and may change at any time. Implementers should not use this for anything other than experimental implementations. This document is available to W3C Members and should not be distributed to anyone who does not have W3C Member access.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

The disclosure obligations of the Participants of this group are described in the charter.

Table of Contents

  1. Abstract
  2. Status of This Document
  3. 1. Introduction
  4. 2. General Steps for Building an Accessible Widget with WAI-ARIA
  5. 3. Keyboard and Structural Navigation
    1. 3.1. Providing Keyboard Navigation for Widgets
      1. 3.1.1. WAI-ARIA Keyboard Bindings and Behaviors
      2. 3.1.2. Keyboard Navigation between Widgets
      3. 3.1.3. Keyboard Navigation within Widgets
      4. 3.1.4. Keyboard Shortcuts for Widgets
      5. 3.1.5. Example Keyboard Operation: Radio Group/Radio
      6. 3.1.6. Other Widget Authoring Practices
    2. 3.2. Providing Keyboard Focus
      1. 3.2.1. Using Tabindex to Manage Focus among Widgets
      2. 3.2.2. Using activedescendant to Manage Focus for Widget Children
      3. 3.2.3. Managing Visual Focus with tabindex Alone
      4. 3.2.4. Managing Focus with Scroll
      5. 3.2.5. Managing the Perception of a Dual Focus
      6. 3.2.6. Author-Defined Keyboard Short-Cuts or Mnemonics
      7. 3.2.7. Providing Navigable Structure within Web Pages
    3. 3.3. Making a Dialog Modal
      1. 3.3.1. Trapping Focus
  6. 4. Relationships
    1. 4.1. Labeling and Describing
      1. 4.1.1. Labeling
      2. 4.1.2. Describing
    2. 4.2. Owning and Controlling
      1. 4.2.1. The Owns Relationship
      2. 4.2.2.  Using Owns with Reusable Content
      3. 4.2.3. The Controls Relationship
    3. 4.3. Changing the Reading Flow
    4. 4.4. Popups and drop-downs
  7. 5. Managing Dynamic Changes
    1. 5.1. Managing Content and Presentational Changes
    2. 5.2. Implementing Live Regions
      1. 5.2.1. Live Region Properties and How to Use Them
    3. 5.3. Choosing Between Special Case Live Regions
  8. 6. Presentation Role
    1. 6.1. Rationale
    2. 6.2. Inheritance of Presentation by Parent Element's Children
    3. 6.3. Overriding Presentation
  9. 7. Form Properties
  10. 8. Math
  11. 9. Drag-and-Drop Support
  12. 10. States and Properties, and Assistive Technologies
  13. 11. Design Patterns
  14. 12. Reusable Component Libraries
  15. 13. Appendices
    1. 13.1. References
      1. 13.1.1. Normative References
      2. 13.1.2. Informative References
    2. 13.2. Acknowledgments
      1. 13.2.1. Participants active in the PFWG at the time of publication
      2. 13.2.2. Other ARIA contributors, commenters, and previously active PFWG participants
      3. 13.2.3. Enabling funders

1. Introduction

This section is informative.

The WAI-ARIA Authoring 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 WAI-ARIA Primer, accessibility deficiencies in today's markup render rich internet applications 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 WAI-ARIA specifications.

For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Authoring Practices Guide is part of a set of resources that support the WAI-ARIA specification. The 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 WAI-ARIA. The WAI-ARIA suite fills gaps identified by the Roadmap for Accessible Rich Internet Applications (WAI-WAI-ARIA Roadmap) [ARIA-ROADMAP]. These documents serve as important places of clarification where topics appear to be unclear.

Note: Most of the JavaScript examples are written to be understandable by all readers, including novice and intermediate JavaScripters. For example, most modern rich web applications use DOM Level 2 event listener assignment now, but some source code examples in this document use DOM Level 1 assignment (e.g. el.onclick = foo; or <el onclick="foo()">) because it is easier for all readers to understand. Expert JavaScripters are encouraged to use modern JavaScript best practices when developing accessible rich internet applications.

With the conceptual basis provided in the WAI-ARIA Primer, you should have a good understanding of how WAI-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 WAI-ARIA, script, and CSS. It then extends your knowledge of WAI-ARIA with detailed guidance on how to make rich internet applications 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 rich internet applications with rich documents on the same page. It includes guidance on dynamic document management; use of WAI-ARIA Form properties; WAI-ARIA Drag and Drop; and then the creation of WAI-ARIA-enabled alerts and dialogs. The appendix provides substantial reference information including code samples for developers of user agents, assistive technologies, and Web pages.

WAI-ARIA markup is currently not included in (X)HTML. The W3C WAI PF working group will be creating DTDs for XHTML 1.0 and HTML 4.01 for those wishing to validate their markup with WAI-ARIA embedded into these host languages.

2. General Steps for Building an Accessible Widget with WAI-ARIA

At this point you should have a basic understanding of how WAI-ARIA is used to support interoperability with assistive technologies. If you are not reusing a WAI-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 WAI-ARIA.

  1. Pick the widget type (role) from the WAI-ARIA taxonomy

    WAI-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">
  2. From the role, get the list of supported states and properties

    Once you have chosen the role of your widget, consult the WAI-ARIA specification [ARIA] for an in-depth definition for the role to find the supported states, properties, and other attributes. For example, the toolbar role definition includes:

    superclass 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 WAI-ARIA. The keyboard model for the control should emulate that of the related concept control.
    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 there are no such states or properties. However, in the case of a listbox, you may choose to set the property of aria-multiselectable to true if you were to have more than one item in the listitem selected at a time. This indicates to the assistive technology that the listbox manages a collection of selectable options.
    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 must set those properties you will use to set 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" id="customToolbar" tabindex="0" aria-activedescendant="button1"
          onkeydown="return optionKeyEvent(event);"
          onkeypress="return optionKeyEvent(event);"
          onblur="hideFocus();"
          onfocus="showFocus();"
          > 
          <img src="img/btn1.gif" title="Home" alt="Home" role="button" id="button1"
               onclick="updateText('Home was invoked');">
          <img src="img/btn2.gif" title="Refresh" alt="Refresh" role="button" id="button2"
               onclick="updateText('Refresh was invoked');">
          <img src="img/btn3.gif" title="Help" alt="Help" role="button" id="button3"
               onclick="updateText('Help was invoked');"> 
    </div>  
    

    By setting tabindex=0 on the toolbar, the toolbar will receive focus in the document order. It is necessary then to use script and the aria-activedescendant property to manage virtual focus among the buttons. The details are given in step five, below.

    Important: When embedding WAI-ARIA markup in (X) HTML, all WAI-ARIA states and properties must be preceded with the characters aria- with the exception of the role and tabindex attributes. Otherwise, the user agent will not map the WAI-ARIA information, resulting in it not being recognized by assistive technologies.

    When embedding WAI-ARIA into other host languages, tabindex does not carry over. The WAI-ARIA tabindex extensions are specific to (X)HTML to repair deficiencies in keyboard support.

  3. 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. Therefore, all functions you would like in the toolbar must be contained within it. This can be determined by using the Document Object Model [DOM] tree structure created by the browser when parsing the host language. By using the parent child relationship of the DOM, an assistive technology can determine all the related toolbar widgets associated with the toolbar. The toolbar widgets would be DOM children of the "toolbar" container. For our purposes we will define three image buttons for cut, copy, and paste.

    <div role="toolbar" tabindex="0" aria-activedescendant="button1">
      <img src="buttoncut.png" alt="cut" id="button1">
      <img src="buttoncopy.png" alt="copy" id="button2">
      <img src="buttonpaste.png" alt="paste" id="button3">
    </div>  
  4. 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" tabindex="0" aria-activedescendant="button1">
      <img src="buttoncut.png" alt="cut" role="button" id="button1">
      <img src="buttoncopy.png" alt="copy" role="button" id="button2">
      <img src="buttonpaste.png" alt="paste" role="button" id="button3">
    </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.

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

    It is very important that your widget be keyboard accessible. In fact, there must be a keyboard equivalent for every 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 keyboard bindings for UI components such as those used for the Java Foundation Classes for Windows 95/NT.

    For our toolbar, we have chosen to have the toolbar manage the focus for its children and through the use of the aria-activedescendant property. We have also chosen to have the toolbar receive focus based on the tab order by using tabindex. In order to use aria-activedescendant, each focusable 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 true;
             }
             return false;
          }
          else if (event.type == "keypress") {
            …
          }
        }  
    </script>
    
    <div role="toolbar" tabindex="0" aria-activedescendant="button1" id="tb1" 
      onkeydown="return optionKeyEvent(event);"
      onkeypress="return optionKeyEvent(event);">
      <img src="buttoncut.png" alt="cut" role="button" id="button1">
      <img src="buttoncopy.png" alt="copy" role="button" id="button2">
      <img src="buttonpaste.png" alt="paste" role="button" id="button3">
    </div>

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

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

  6. Apply and manage needed WAI-ARIA states in response to user input events

    Similar to the processing of aria-activedescendant in Step 5, as author you must set any additional WAI-ARIA states and properties on document elements.

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

    You should consider binding user interface changes directly to changes in WAI-ARIA states and properties, such as through the use of CSS attribute selectors. For example, the setting of the aria-selected (state) state may change the background of a selected treeitem in a tree. This may also be done with JavaScript.

    .treeitem[role="treeitem"][aria-selected="true"] {color: white; background-color: #222222;}
    
    .treeitem[role="treeitem"][aria-selected="false"] {color: white; background-color: beige;}        

    Authors should be aware that CSS attribute selectors are not supported in some browsers, such as Internet Explorer 6. A consistent way to apply styling to reflect WAI-ARIA semantics would be to assign an element a class name based on the WAI-ARIA attribute being set using script as shown here:

    function setSelectedOption(menuItem)
         {
            if (menuItem.getAttribute("role") != "menuitem") {
               return;
            }
            var menu = getMenu(menuItem);
            var oldMenuItem = getSelectedOption(menu);
            
            // Set class so that we show selection appearance
            oldMenuItem.className="unselected";
            menu.setAttribute("aria-activedescendant", menuItem.id);
            menuItem.className= "selected";
          }
  8. Showing and Hiding Sections in a Widget

    The proper synchronization of showing and hiding sections in a widget with the WAI-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 as demonstrated here.

    	  // create new table row with table cell and div
    	  var newTr = document.createElement('TR');
    	  var newTd = document.createElement('TD');
    	  var newDiv = document.createElement('DIV');
    	  newTr.appendChild(newTd);
    	  newTd.appendChild(newDiv);
    	  
    	  
    	  //insert this new table row before the Node selected
    	  var container = theNode.parentNode;
    	  container.insertBefore(newTr, theNode);
    	  
    	  //remove theNode selected
    	  container.removeChild(theNode);"

    However, if you are using CSS to show and hide sections of the DOM (2) it is essential that you set the corresponding WAI-ARIA aria-hidden (state) 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>
  9. Support basic accessibility, such as alternative text on images

    When an image is used to represent information within a component, such as 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" tabindex="0" aria-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="button2" alt="copy">
       <img src="buttonpaste" role="button" id="button3" alt="paste">      
    </div>
  10. Establish WAI-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 aria-labelledby, aria-controls, aria-describedby and aria-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, aria-level, aria-posinset, and aria-setsize are provided. If you structure your Document Object Model appropriately so that the user agent can determine this information from it using the DOM hierarchy directly, you do not need to set these properties. There are, however, situations in rich internet applications where all the elements in a container are not in the DOM at one time, such as when you can only render the ten of fifty items in a subtree. In this case the user agent cannot determine the number of tree items (aria-setsize) for the position in the set (aria-posinset), and potentially the tree depth (aria-level) from the DOM. In these situations you will need to provide these WAI-ARIA properties.

  11. 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 in pixels an increase in system fonts will not be reflected in your Web application. You must also not hard code the size of your widgets in pixels either. If the fonts are scalable, but the widget they are encapsulated in is not, then the text could flow outside your widget.

    Follow these rules to allow your application to respond to system font settings:

    • Establish a base set of font sizes used in widgets based on percentage of the container element font size.
    • Use CSS width, borders, margin, padding, background, and positioning properties to specify the graphical rendering of widgets and their sub-components, use percentage units or em units to specify widths of widget components (An em is a the font unit of measure between the top and bottom of an upper case letter M.). Border widths, padding, and margins can use PX units.
    • Use scripting for run time CSS positioning of widget sub-components in relation to other sub components.
    • Make sure all widgets use consistent height and width units of measure.

    Percentages are the most reliable way to consistently specify proportional text sizes in widgets. The use of percentages and em should be used for specifying widths of a widget and the widget sub components. The use of percentages for text size and percentages and em units for widths support browser zoom capabilities to make widgets larger or smaller. Pixels can be used for specifying line widths, padding and margins.

    Important: Most browsers today have a zoom feature which allow the user to magnify the entire Web page. Most legislation today requires that your application respond to system font and color settings and therefore you will want to consider the fact the system settings could adversely affect your Web page should you decide to hard code pixel sizes.

  12. Compensate for Background Images when in High Contrast Mode

    Authors use background images when styling their widgets, including situations where the background image is not merely decorative, but informative. An example is a horizontal progress bar that it is filled by gradually revealing more of a background image. This is accomplished by initially setting the width of the element to zero, and then incrementing its width in accordance with the degree of progress.

    High contrast mode is an operating system display modification that makes the screen easier to see for low vision users. Some operating systems (e.g., Windows), do not display background images when in high contrast mode. Consequently, the progress bar described above appears empty regardless of the progress. It is recommended that authors not use background images as the sole method to convey important information, and to compensate with alternative or additional style rules.

    In the case of the progress bar example, a technique that works when in high contrast mode is to style the element with a border. Since the width of the element is updated as progress increases, its border gradually expands horizontally forming an ever wider unfilled rectangle. This provides alternative visual feedback as to the extent of the progress.

    Another technique is to replace a background image with text. Consider a dialog that uses a background image for its close box. To compensate for the missing close box when in high contrast mode, a lower case 'x' is used instead. The compensation technique used depends on the context, particularly the purpose of the background image.

    There are two general approaches with respect to detecting high contrast mode. They are (1) executing a script to determine if the system is in high contrast mode, or (2) providing a preference to use alternative styles. The advantage of automatic detection is that some operating systems simply apply a different color palette when in high contrast mode and do not turn off background images. In that case, authors need not compensate for missing background images. However, detection of high contrast mode by script is relatively expensive compared to a preference that users can set, and, presumably, users can see whether background images are displayed in high contrast mode on their system. It is up to individual authors to decide which method they find acceptable for their particular situation.

    The following code fragment outlines how to detect high contrast mode.

    /* Define styles for the high contrast test element */
    #hiContrastTestEl {
        border: 1px solid;
        border-color:red green;
        position: absolute;
        height: 5px;
        top: -999px;
        background-image: url('resources/blank.gif');
    }
    …
    // An onload event handler that inserts the high contrast test element and
    // then tests its computed styles.
    function detectHiContrast() {
        var div = document.createElement('div');
        div.setAttribute ('id', 'hiContrastTestEl');
        // … append <div#hiContrastTestEl> to the <body> element …
        var cs = window.getComputedStyle(div);
        var bki = cs.backgroundImage;
        var hiContrast = false;
        
        // The CSS sets the top and right borders of the test element to red and
        // green, respectively.  In high contrast mode either the borders are
        // the same colour, or there is no legitimate url to the background image.
        hiContrast =    (cs.borderTopColor == cs.borderRightColor) ||
                        (bki != null && (bki == 'none' || bki == 'url (invalid-url:)'));
        
        if (hiContrast) {
            // apply hi contrast styles to compensate for missing background images.
        }
        // … remove the test element from the document …
    }
  13. Test with User agent, Assistive Technology, and People with disabilities

    To ensure you have set your WAI-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 WAI-ARIA and their your assistive technology is designed to support WAI-ARIA in the selected user agent.

    Finding people with disabilities to do testing may be difficult but many companies employ people with disabilities, including your customers, and you should reach out to them to ask for help. Other places to look are advocacy groups like the National Federation of the Blind or your local schools for the blind, reading and learning centers, and so on. The people you reach out to may someday need to use what you produce.

3. Keyboard and Structural Navigation

Providing an effective navigation experience to the user is critical for usability. This section starts with guidance on how to provide effective keyboard navigation for widgets in a Rich Internet Application environment. This includes a discussion on how to manage keyboard focus and the specifics on providing keyboard navigation for tooltips. This is is followed by a broader discussion on how to convey structural semantics for the entire Web page. These semantics help an assistive technology provide additional navigation, increase user productivity, and render the page in an alternative formats. This rendering may be in different forms, including but not limited to speech, page restructuring, and alternative input solutions.

3.1. Providing Keyboard Navigation for Widgets

3.1.1. WAI-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, typically, have no inherent keyboard support. The developer must enable keyboard support for the widgets they create or use widget libraries with keyboard support. The model for keyboard support for Web 2.0 widgets are graphical user interface (GUI) operating systems like Microsoft Windows, Mac OS X; and other desktop operating systems like GNOME and GTK. 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.

For example, if a screen reader user hears a tree announced, they know that pressing the right arrow key will expand a node. Similarly, when they hear a grid announced, they know they can use their screen reader's table reading commands.

3.1.2. Keyboard Navigation between Widgets

The tabindex attribute enables focus to be moved via keyboard to HTML elements. For standard HTML 4.01, tabindex was limited to form and anchor elements. For WAI-ARIA, the tabindex attribute is now applicable to all renderable HTML elements with additional functionality designed to help the author produce keyboard accessible 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, Space, 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 to its current active descendant element and itself if an active descendant does not exist. 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), the Apple AX APIs, and the 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 Space. 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, Mac OS X and other desktop operating systems like GNOME and GTK.

Authors can use either the JavaScript focus() method to move focus to the appropriate element in the widget, or they can use a WAI-ARIA property called aria-activedescendant on the actual widget container to indicate which descendant element in the widget has focus. Use the following procedure when focus is completely dependent on the use of tabindex to provide focus in a widget:

  • Set tabindex="0" on the current active descendant in the container widget while setting tabindex="-1" on all the other descendant elements of the widget.
  • As the user navigates (e.g., arrows) away from an item, set tabindex="-1" on the old item, and tabindex="0" on the new.
  • Use the JavaScript focus() method to put focus on the new item, whose tabindex="0".

This procedure creates a roving tabindex. If the user TAB navigates away and then TABs back to the widget, the same last active descendant becomes active again. This relieves the author from having to compute and set the focus to the last active descendant.

Conversely, if you use the WAI-ARI aria-activedescendant property:

  • Set tabindex="0" on the element which is the composite widget, and set its aria-activedescendant property to the id of the descendant element you wish to be active,
  • As the user navigates (e.g., arrows) away from an item in the widget, refresh the aria-activedescendant property on the containing widget to the id of the new active descendant element.

In this scenario, the browser manages focus changes; however, the author manages changes to the aria-activedescendant property. For greater detail, see Using Tabindex to Manage Focus Among Widgets. In both scenarios authors indicate which element in the widget has focus or is active through styling and/or markup.

3.1.4. Keyboard Shortcuts for Widgets

It is useful to provide keyboard access to widgets, to focus a widget directly and to activate the features within the widget. These may be "mnemonics" that use a letter from the label of the control, as well as other special keys that perform familiar operations on the system. When providing non-standard key commands, document them so the user knows how to use them.

When localizing the user interface, it may be necessary to localize keyboard mnemonics as well in order to keep them apparent. Be sure not to introduce key conflicts when doing this, and ensure that the correct key commands remain apparent to the user.

3.1.5. Example Keyboard Operation: Radio Group/Radio

See working Radio button examples from the University of Illinois.

Key Bindings for Radio Group Behavior - Example
KeyDescription of Radio Group Behavior
Tab Key If no radio button is checked, focus moves to the first radio button in the group, but the radio button remains unchecked. If one radio button 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 remains unchecked.
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 ArrowIf no button is checked, check the first radio button. If the last radio button is checked, check the first radio button. Otherwise, move the check from the current radio button to the next radio button.
Up ArrowIf no button is checked, check the last radio button. If the first radio button is checked, check the last radio button. Otherwise, move the check from the current radio button to the previous radio button.

In this Radio Group example, the tabindex of the first and last radio button elements has a tabindex="0" (assuming none of the radio buttons is checked), the remaining radio elements have tabindex="-1". As soon as the first or the last radio button receives focus it changes the tabindex value of the other radio button to -1. If none of the radio buttons is selected the and the keyboard focus leaves the group the first and the last radio buttons have their tabindex values set to 0.

3.1.6. Other Widget Authoring Practices

The Common Widget Design Patterns section of this document contains best practices, such as keyboard navigation, for creating common widgets found on the Web. This section contains miscellaneous authoring practices that you should also consider.

3.1.6.1. Maintain a valid format for aria-valuenow

It is essential that application vendors maintain a valid format for aria-valuenow, and aria-valuenow should accurately represent the value of the widget.The value must be within range of aria-valuemin and aria-valuemin, where the value of aria-valuemin is less than or equal to the value of aria-valuemax, throughout the life cycle of your widget. If aria-valuemin is not less than or equal to the value of aria-valuemax, or if the aria-valuemax is indeterminate, this creates an error condition that will be handled by the assistive technology, resulting in undesirable results. Should an alternative text equivalent be needed to properly represent the aria-valuenow, such as a day of the week, then you should accompany the aria-valuenow with an appropriate aria-valuetext equivalent such as in this example:

<div role="slider" aria-valuenow="1" 
	aria-valuemin="1" aria-valuemax="7"
	aria-valuetext="Sunday">

Here the values 1 through 7 represent the days of the week and aria-valuenow of 1 is equivalent to the first day of the week or Sunday. When aria-valuetext is made available aria-valuenow should also be treated as an index which is 1 based.

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, when building sophisticated widgets, it's necessary to be able to control keyboard navigation exactly. Authors may require or prefer to use host language elements that do not have built-in keyboard navigation features. For example, the author may wish to provide keyboard navigation without altering the tab order. Navigating within large composite widgets such as tree views, menubars, and spreadsheets can be very tedious and is inconsistent with what users are familiar with in their desktop counterparts. The solution is to provide full keyboard support using the arrow keys to provide more intuitive navigation within the widget, while allowing Tab and Shift+Tab to move focus out of the widget to the next place in the tab order.

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. Using Tabindex to Manage Focus among Widgets

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 Opera, Gecko-based user agents such as Firefox, and WebKit-based user agents such as Safari. The following table outlines the use of the tabindex attribute:

Use of the Tabindex Attribute
Tabindex AttributeFocusable 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"

yesIn tab order relative to element's position in document

Positive - tabindex="X" (where X is a positive integer between 1 and 32768)

yesTabindex value directly specifies where this element is positioned in the tab order.

Negative - tabindex="-1"

yesNo, 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 enables 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. Here are just a few additional tips to help you with managing keyboard focus:

  • Use focus and blur events (or event delegation) to monitor changes to the current focus - focus and blur events can now be used with every element. Modern browsers now support an activeElement property on the document object to get the focused element. Don't assume that all focus changes will come via key and mouse events, because assistive technologies such as screen readers can set the focus to any focusable element, and that needs to be handled elegantly by the JavaScript widget. Techniques such as "event delegation" (for example, intercepting events on a list rather than on every listitem) can greatly increase web application performance and code maintainability, and authors are encouraged to use JavaScript best practices whenever possible.

    Note: The activeElement property is now standard in HTML 5.

  • Follow keydowns to move focus - A keydown event handler can determine the next object to receive focus and call that element's focus() method.

  • Use onkeydown to trap key events, not onkeypress - Key press events do not fire for all keys and they vary across browsers.

  • Dynamically change focusability using the tabIndex property - You may want to update tabindex values if a custom control becomes disabled or enabled. Disabled controls should not be in the tab order. However, you can typically arrow to them if they're part of grouped navigation widget. When an element receives focus, it should change the tabindex value to 0 to make an element the default element of the widget. This is important if the user leaves the widget and returns to the widget again so focus is on the last element of the widget the user was on. If other elements of a widget can receive keyboard focus, only one element of the widget should have a tabindex value of 0.

  • Use element.focus() to set focus - Do not use createEvent(), initEvent() and dispatchEvent() to send focus to an element, because these functions do not change the focus. DOM focus events are informational only, generated by the user agent after an element has acquired focus, but not used themselves to set focus.

  • The use of :focus pseudo-class selectors to style the keyboard focus is not supported in many versions of Internet Explorer. Authors should use the :active pseudo-class (which older versions of IE treat like :focus) in conjunction with the :focus pseudo-class. Example: a:focus, a:active { text-decoration: underline; }

    If the related CSS pseudo-classes are not appropriate or not supported in all browsers, authors can use JavaScript techniques to indicate an appropriate focus alternative, such as using focus and blur events to toggle a classname on an element.

  • Always draw the focus for tabindex="-1" items and elements that receive focus programmatically when supporting versions of Internet Explorer older than 8 - Choose between changing the background color via something like this.style.backgroundColor = "gray"; or add a dotted border via this.style.border = "1px dotted invert". In the dotted border case, you will need to make sure those elements have an invisible 1px border to start with, so that the element doesn't grow when the border style is applied (borders take up space, and IE doesn't implement CSS outlines).

  • Prevent used key events from performing browser functions - If a key such as an arrow key is used, prevent the browser from using the key to do something (such as scrolling) by using code like the following:

    <span tabindex="-1" onkeypress="return  handleKeyPress();"> 

    If handleKeyDown() returns false, the event will be consumed, preventing the browser from performing any action based on the keystroke. In addition to the return value the browser must call the event methods that will prevent the default action, for IE this is setting the event property "returnValue=false", and for other browsers supporting the W3C event model this means calling the "preventDefault" method of the event object.

  • <span tabindex="-1" onkeydown="return handleKeyDown();">   

    If handleKeyDown() returns false, the event will be consumed, preventing the browser from performing any action based on the keystroke.

  • Use key event handlers to enable activation of the element - For every mouse event handler, a keyboard event handler is required. For example, if you have an onclick="doSomething()" you may also need onkeydown="return event.keyCode != 13 || doSomething();" in order to allow the Enter key to activate that element.

    Note: There are user agent-specific considerations for key event handling.

  • Consider using a "roving" tabindex for complex widgets if you are not using the aria-activedescendant property.

3.2.2. Using activedescendant to Manage Focus for Widget Children

In addition to tabindex, WAI-ARIA provides the aria-activedescendant property for managing the focus of child elements within a widget. Widgets like grid and tree typically manage their children. The root element of the widget should have a tabindex value greater than or equal to "0" to ensure that the widget is in the document tabbing order. Rather than setting a key event handler on each element within a larger component, the event handler can be set on the parent element such as the tree. It is then the job of the parent element to manage the focus of the children.

The parent may use the aria-activedescendant property 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 must be perceived as active.

Important: For a given container widget where activedescendant must cause focus events to be fired to ATs, the actual focus must be on the container widget itself. In HTML this is done by putting tabindex="0" on the container widget.

The key handler on the parent captures the keystrokes and determines what item becomes active next and updates the aria-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 element 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.

As active status is moved to the next descendant, ensure that it is scrolled into view using scrollIntoView(). See section Managing Focus with Scroll below for more information.

3.2.3. Managing Visual Focus with tabindex Alone

An alternative to using activedescendant is to have the parent element, in response to the same keyboard input, move focus to its children by first removing tabindex from children that do not have focus, which removes them from the tab order. This would be followed by setting the tabindex to "-1" on the element that is to receive focus and then using script to set focus on the element to receive focus. As with aria-activedescendant, this omits managed children from the tabbing order. It enables browsers that do not yet support aria-activedescendant to maintain keyboard navigation, and it provides notification to many assistive technologies like screen magnifiers to move visual focus without relying on other WAI-ARIA properties. Today, this technique will work in most user agents, but in the long run aria-activedescendant will require less work by the developer.

Although not always ideal based on the widget you are creating, one benefit of using tabindex to manage focus on an element is that the user agent will scroll the element into view when focus is set to the it. This is not the case for aria-activedescendant. When setting or updating the aria-activedescendant property, e.g. aria-activedescendant="cell23", authors must ensure that the element with id="cell23" is in view. In either case, consider positioning your widget in the visible area of your browser to maximize usability. This can be achieved using available JavaScript scrolling functions.

3.2.4. Managing Focus with Scroll

In some browsers, a JavaScript call to scrollIntoView() on this element should suffice, but in browsers where this is unreliable, authors should explicitly set the scrollTop and scrollLeft properties of the "cell23" element and its ancestors to scroll the element into view. scrollTop and scrollLeft adjust the node positions by the amounts(pixels) needed to scroll a node into view.  Scrolling values are adjusted by the amounts(pixels) needed to scroll a node into view. This is done by comparing the sizes of the nodes using available measurements such as scroll+offset+clientWidth/Height/Left/Top. It's important to note that you have to adjust a node so that it's viewable within the context of its parent node.  Then you have to move up the DOM tree and make each parent node visible.

For example, create a custom scrollIntoView() method that is called at various times, including coincidence with the setting of the aria-activedescendant property. The method takes a DOM node argument, say "n". Here is the high level algorithm:

  1. If n is already in view, stop; otherwise, continue.
  2. adjust n.scrollTop and n.scrollLeft such that it is in view.
  3. adjust scrollTop and scrollLeft for the ancestor nodes of n such that that the region of the ancestors which n consumes is visible.

This is a minimum-position-change algorithm.

Understanding how the DOM scrollIntoView works across browsers is important. Browsers (including Firefox3) force the node either to the top or the bottom of the screen (as defined by the single Boolean parameter) even if its already in view. This is problematic when you only need to scroll horizontally to see the element. It is also problematic when the node is partially off the bottom of the screen and the parameter is (true) which forces the node all the way to the top, and vice versa with the top going to the bottom on (false). IE forces the node to the left of the client area (or right in right-to-left mode) even if it's horizontally in view already.

The scrollTop and scrollLeft functions create some challenges. scrollTop is always accurate but misleading with respect to inner (nested) scrollbars. scrollLeft cannot be relied on in right-to-left languages because it is sometimes negative and sometimes positive especially with respect to inner (nested) scrollbars. Different browsers handle right-to-left completely differently.

3.2.5. Managing the Perception of a Dual Focus

Often applications give the perception of having a dual focus. Two examples of this are multi-selection list boxes and selected tabs, within a tablist, when focus is in a tabpanel. In the case of a muti-selection list box a developer may gray selected items as they move focus to list box items to toggle their selected state. In the case of a tabpanel the user selects a tab but then navigates to a focused item in the corresponding tabpanel the tab appears to also have focus. In reality, only one element may have focus in an application. In these scenarios authors should ensure keyboard focus is set on the current element that visibly receives keyboard user input while ensuring other "highlighted" elements have an aria-selected state of "true" until de-selected. When the de-selection occurs, such as when a multi-select item is de-selected or a user moves to a new tab and de-select the old tab, the author should ensure that the visible selection of the de-selected item is removed.

3.2.6. 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 are highly probable. Therefore, if you needed to use accesskey, you should be aware that it will behave differently in
different browsers. It also may not work with small devices so it is still advisable to ensure that all features are accessible with the basic keys like Tab/Shift+Tab, arrow, Enter, Space and Escape.

The XHTML 2 Working Group is currently developing a new Access Module to address this issue and we hope to have it or a feature like it in future versions of (X)HTML. Refer to Section 9: Implementation Guidance.

3.2.6.1. Supporting Tooltips with the Keyboard

A tooltip is a 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. To provide simple text tooltips, the HTML title attribute should more than suffice because the user agent will render it for tooltips. When creating a tooltip, it is essential that the user be able to activate it using the keyboard. When a form control or widget receives keyboard focus, the tooltip must display. When the form control or widget loses focus, the tooltip must disappear. Browsers do not currently support this functionality.

The following code snippet from the iCITA site shows the use of a onfocus="tooltipShow();" function to display the tooltip when focus is placed on an element.

<html lang="en-us"">  
<head>    
   <title>inline: Tooltip Example 1</title>      
   <link rel="stylesheet" href="css/tooltip1_inline.css"  type="text/css">    
   <script type="text/javascript" src="js/tooltip1_inline.js"></script>    
   <script type="text/javascript" src="../js/widgets_inline.js"></script>
   <script type="text/javascript" src="../js/globals.js"></script>          
   <link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon">    
   <link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon"> 
</head><body onload="initApp()">

   <div id="container">

   <h1>Tooltip Example 1</h1>
     <h2>Create Account</h2>
   <div class="text">
   <label for="first">First Name:</label> 

   <input type="text"  id="first" name="first" size="20" 
          onmouseover="tooltipShow(event, this, 'tp1');"     
          onfocus="tooltipShow(event, this,  'tp1');" 
          aria-describedby="tp1"  		 
          aria-required="false"/>

   <div id="tp1" role="tooltip" aria-hidden="true">Your first name is optional. </div>    
   </div>
3.2.6.2. When Keyboard Handlers Shortcuts Steal the Keys

Similar to the tip specified in Using Tabindex to Manage Focus on Widgets, a web application should cancel (or swallow) the keyboard event in the keyboard handler to prevent the key from being used outside the web application. For example if the user presses Control+PageDown in a tab panel in a web application, this keyboard event should not also go to the user agent, which would cycle the active browser tab, confusing the user.

3.2.7. Providing Navigable Structure within Web Pages

This section takes a broader look at the Web page. It 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.

One of the deficiencies of (X)HTML for disabled users has been the usability of keyboard navigation. Users dependent on a keyboard for navigation have been forced to tab everywhere in the document, as the only keyboard accessible document elements are form and anchor elements. This has forced developers to make most everything a link to make it 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 number of 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
  • Neither convey the need for the rich internet application developer to control keyboard navigation to an assistive technology

This remainder of this section provides the author with a playbook for using WAI-ARIA to add semantically rich navigation structure in a Web page so that an assistive technology may provide an effective user experience and avoid these shortcomings.

3.2.7.1. Steps for Defining a Logical Navigational Structure

Due to the complexity of today's web content, it is imperative that all content reside in a navigation landmark. Sight and mobility impaired users must be able to quickly access a list of landmarks for a web page, to be used as a table of contents. This allows the user to quickly navigate to important sections of the page without "endless" TAB navigation. If this is not done, then content will be orphaned and missed by the user. In fact many of today's accessibility test tools have built-in rules to flag this issue as a compliance error. This section defines how to create these navigable regions of the page:

  1. Identify the logical structure of your page

    Break up your page into perceivable block areas which contain semantically associated information called "regions". You can further break down each region into logical regions as needed. This is a common process undertaken by portal developers who break the page into perceivable regions called portlets. Think about the user wanting to navigate to these logical block areas on your Web page. Write down a description of what you believe each region to be.

    Depending on your Web application you may then need to break it into sub regions depending on the complexity of your Web application. This is a recursive process. A user will look at these perceivable areas like pealing an onion. You might have an outermost collection of perceivable regions or block areas and upon entering each region you may have a collection of regions within it.

  2. Implement the logical structure in markup

    Implementing the block structure in markup often involves wrapping elements contained with a "region" such as a <div> or <iframe> with visible borders so that each region or block is perceivable to the user.

  3. Label each region

    Once you have broken up each region you need to label it. The start of each region must have a perceivable header and it should be used to label the region. For details on how to do this see section 3.4.3.1 Header Levels vs. nesting level to create a header to label each region. If you're finding it difficult to come up with a label for the region, make sure at least to use one of the standard roles defined in the following step. The drawback of not providing a label is that users will not know the purpose of the region. By definition, regions would be included in a summary of a page. If an assistive technology were to summarize it would be unable to provide information about the section without a label.

  4. Assign landmark roles to each region

    Now that you labeled your regions, you need to assign them semantic navigation landmarks. Landmarks are a vast improvement over the rudimentary "skip to main content" technique employed prior to WAI-ARIA. If possible it is best to use these as landmarks. Skip to main content links may impact the placement of web application elements. This may be a consideration for developers that want to try to keep their web application in a specific visible area. Consequently, layout adjustments may need to be made to support skip to main content links. Also, skip to main content links are limited in that they only address only one main content area. WAI-ARIA provides a collection of landmarks which are applied to each of the regions you identified in step 2.

    The presence of common, semantic, navigation landmarks allows each site to support the same standard and allows your assistive technology to provide a consistent navigation experience - an important feature for screen readers and alternate input solutions. For users with cognitive and learning disabilities the landmark information could be used to expand and collapse these regions of your page to aid in simplifying the user experience by allowing the user to manage the amount of information processed at any one time.

    WAI-ARIA landmark roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. For this reason, it is recommended that authors apply landmarks to DIV and SPAN containers.

    There are also mainstream benefits of providing navigation landmarks. Your browser may assign key sequences to move focus to these sections as they can be set on every site. Navigation to these landmarks is device independent. A personal digital assistant (PDA) could assign a device key to get to them in your document. The common landmarks in WAI-ARIA include:

    application
    Represents a region of the page representing a unique software unit executing a set of tasks for its users. It is an area where assistive technologies should also return browse navigation keys back over to the web application in this region.

    If the entire web page has a role of application then it should not be treated as a navigational landmark by an assistive technology.

    banner
    A region that contains the prime heading or internal title of a page.
    complementary
    Any section of the document that supports but is separable from the main content, but is meaningful on its own even when separated from it.
    contentinfo
    Meta information which applies to the first immediate ancestor whose role is not presentation.
    form
    A region of the document that represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing.
    main
    Main content in a document.
    navigation
    A collection of links suitable for use when navigating the document or related documents.
    search
    The search tool of a Web document.

    To set a landmark in your page:

    <div role="navigation" title="Table of Contents"></div> 
    <div role="main" title="Game Statistics"></div>
  5. For application landmarks with static prose

    If you have a regional landmark of type application and static descriptive text is available, then on the application landmark, include an aria-describedby reference to associate the application and the static text as shown here:

    <div role="applicaton" aria-labelledby="calendar" aria-describedby="info">
    <h1 id="calendar">Calendar<h1>
    <p id="info">
    This calendar shows the game schedule for the Boston Red Sox.
    </p>
    <div role="grid"></div>
  6. For landmarks unsuited to specialized region WAI-ARIA roles

    You can create custom regional landmarks by using a generic region. While it is not essential to label these specialized regions with a header, you should provide a title to ensure that the region name is accessible to all users, just as you would the standard regional landmarks. See Header levels versus Nesting levels for directions on how to label the region.

    <div role="main"> … <div role="region" title="weather">  
    

    Note: the region role is generic and should only be used when a more specific role is not applicable.

  7. Indicate to the assistive technology who controls the keyboard navigation

    Today's screen readers for the blind have been designed to give the user a "browsing" experience meaning the screen reader consumes a number of keys to aid in the browsing experience. For example, the "up" and "down" arrow keys are used to read the next and previous line of text on your Web page. Accessible rich internet applications will use these keys in an application to navigate within "widgets" like a Tree View.

    Assistive technologies must be able to identify widgets which implement WAI-ARIA and allow them use of the keyboard. However, if you have used numerous widgets to form an application you must set the role on the encompassing region to application. Should you have regions which should be browsed as documents within the application region you should mark those regions with a document role as needed. See section 3.4.2 Structural Roles used to facilitate assistive technology navigation.

3.2.7.2. Structural Roles that Facilitate Navigation with Assistive Technologies
While WAI-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 browse mode."

Because many screen readers 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 reader's perception of an area as either a document or an application greatly influences how the user reads and interacts with it, WAI-ARIA provides content authors a way to indicate whether their pages must be viewed as applications or documents by assistive technologies.

To set document or application mode follow these steps:

  1. 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 the majority of the content is application-like the default interaction mode should be set to application, with document regions embedded within the application if applicable. Otherwise the default interaction mode is document-like and therefore should not be overridden by the use of a global role of application. In this case the application role can be placed on discrete regions within the document if applicable.

    If it is, set the role of application on the body tag as follows:

    <body role="application"> 

    When using application, all static text must be associated with widgets, groups or panes via using the aria-labelledby and aria-describedby properties, otherwise it will not be read by the screen reader when the user navigates to the related widget or group.

    Special Considerations:

    • If you have selected to have a role of application on the body tag, it is recommended that a widget have focus after the page is first loaded. There may be an instance when an application itself needs to receive focus, such as an application consisting solely of a scrollable editable text area.
    • If when your page loads and you should have focus on a widget this is a strong indicator that your Web page should have role of application.
    • 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, must 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 3. Otherwise, the Web page is considered a document, and no further action is required in this regard.
  2. Dialogs and alert dialogs - special case application roles

    WAI-ARIA provides dialog and alertdialog roles that are to be treated as special case application roles. Like application, screen readers will leave the main job of keyboard navigation up the dialog.

    When using dialog, all static text must be associated with widgets, groups or panes using the aria-labelledby and aria-describedby properties, otherwise it will not be read by the screen reader when the user navigates to the related widget or group. Unlike an application, your Web page is unlikely to start out as either of these two roles but rather the author is most likely to dynamically create dialogs or alertdialog sections within the Web page.

    Unlike dialog, descriptive text of the alert does not need to be associated via a relationship, as the contents of alert dialogs will be read automatically by the screen reader when the dialog opens.

  3. Set the document role

The default mode for a screen reader to be processing an HTML Web page is document browse mode. This is equivalent to having a role of document on the HTML <body> tag. If you have already specified a role of application on the body tag there may be times in which you tell the screen reader to switch into "document browse mode" and start stealing the necessary keys to browse a document section of your Web page. These keys are the typical keys used by WAI-ARIA widgets and to provide this level of navigation the keys must be stolen from your browser.

To mark areas of your page to tell the assistive technology when to switch into document browse mode, look at the regions/landmarks you have defined and determine which ones must be browsed as a document or navigated as an application. For each region which must be browsed in document browse mode, 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 change its interaction model to that of document browsing mode.

3.2.7.3. Implicit Nesting and Headings

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

3.2.7.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 region of the document to which the heading pertains to should be marked with the aria-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 aria-labelledby attribute. If headings are organized into a logical outline, the aria-level property can be used to indicate the nesting level. Here is an example with and without ARIA. Note that the preferred way is using native semantics without ARIA, but the approach with ARIA is shown first to demonstrate use of the heading role:

Using ARIA:
<div role="main" aria-labelledby="page_title">
  <p id="page_title" role="heading" aria-level="1">Top News Stories</p>
   … main page contents here …
</div>

Using native markup:
<div role="main" aria-labelledby="page_title">
  <h1 id="page_title">Top News Stories</h1>
   … main page contents here …
</div>
3.2.7.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 rendered by the assistive technology, 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 aria-owns relationship is provided to annotate logical nesting where the logical child is not a syntactic descendant of the logical parent. In a Rich Internet Application, updates may be made to the document without updating the logical syntactic structure, yet elements may appear to be added to the document structure. From a DOM and accessibility hierarchy perspective aria-owns is a fallback mechanism to using the tree hierarchy provided in the DOM. An example of where aria-owns is needed is a treeitem, where children in a folder subtree are added to a visible subtree but not reflected in the actual document subtree of the folder. The aria-owns relationship can be used to associate the folder with the new "adopted" child. For more details on the use of aria-owns see section 4.2 Owning and Controlling. The aria-owns relationship is used to indicate to a user agent that a menu is an adopting parent of a sub menu. Another use for aria-owns is a hierarchical diagram where the child nodes of the diagram are not be adequately represented using the DOM structure.

3.2.7.4. Directories, Groups, and Regions

There are several WAI-ARIA roles used to indicate a collection of user interface objects, and each has a distinct purpose:

directory
Contains a static table of contents
group
Small set of related user interface objects that would not be included in a page summary or table of contents by an assistive technology
region
Section of related user interface objects that should be included in a page summary or table of contents.

The use of each is described below.

3.2.7.4.1. Directories and Their Applicability

The WAI-ARIA role, directory, allows authors to mark static table of content sections of a document. Prior to WAI-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 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
          <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.2.7.4.2. Groups and Their Applicability

Authors should use a role of group to form logical collections of items with related functionality in a widget. A group should not be considered a major perceivable section on a page. A group neither has a heading nor appears in the "Table of Contents." A group may delineate a set of treeitems having the same level in the tree or it may be used to group a set of related checkboxes in a form. Other examples include:

  • a row in a grid (a row is a specialized group representing 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 a 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 must assign the section a role of region or one of the designated standard landmarks. The designated landmark roles are listed in the section Regions and XHTML Role landmarks.

3.2.7.4.3. Regions and Their Use

When defining a region for a section of a document, authors must consider using standard document landmark roles defined in the XHTML Vocabulary. 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 must use the WAI-ARIA region role and provide the appropriate title text.

For more information on the use of region see Regions and XHTML Role landmarks.

 

3.2.7.5. Remaining Structural Roles
3.2.7.5.1. Tabular Structure-Related Roles Supporting Tabular Widgets

A number of structural roles support the tabular widgets, grid and treegrid. These structural roles 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, that may not work for the developer in all instances, such as when the developer has need for a <div> or <span> or when additional semantics are needed. To assist, the following roles are provided to support tabular widgets:

When constructing a gridor treegrid the author must use gridcells for the actual cells:

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

Unlike table cells within a table, authors should ensure a grid's gridcells are focusable through the use of tabindex (in HTML), or aria-activedescendant on the grid.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>. WAI-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. If you decide to not use the native HTML <table> elements and choose more flexible elements, such as <div> and <span>s, with applied WAI-ARIA roles in this section, you should structurally lay out your elements in line with what you would expect from HTML. All of your rowheaders should be in a row and your gridcells should be children of each subsequent row in the same format as HTML for <td>s and <th>s within <tr>s.

3.2.7.5.2. Marking Descriptive Sections

A new feature of WAI-ARIA is the ability to associate descriptive text with a section, drawing, form element, picture, and so on using the aria-describedby property. The use case for aria-describedby is to reference the local id of the long description. The most common use case for longdesc is for the author to create a separate file to describe a picture. It is prefereable to have the descriptive text in prose as well so that it is readily available to all users. This is useful for authors who do not want to create a separate document that contains the description, and for cognitively impaired users who can be confused by context changes when having to go to another page for the description. Yet, like longdesc, descriptive text is treated separately from the short name provided by the title or alt attributes in HTML.

The aria-describedby property allows for the text of hidden elements to be used for accessible descriptions. Some screen reader vendors have used non-standard attributes to provide hidden help text for form elements. In order to standardize this feature, hidden text is exposed in the description property of Accessibility API objects when referenced by aria-describedby.

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

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

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

When the author does not desire the entire descriptive text to be located on the main page, aria-describedby can also be used to point to a link to another page.

<div id="figuretitle">Figure 1-1: Entity Relationship Diagram showing EMP and DEPT</div>
  <img src="foo" aria-labelledby="figuretitle" aria-describedby="link1">
  <a href="descriptionLocation.html" id="link1">Description of Figure 1-1: Entity Relationship Diagram showing EMP and DEPT</a>
</div>

It is not good practice to use the above pattern when the describing element—the <a> tag with @id='link1'—is hidden, since there is no way for a user to navigate to and activate the link. Use the technique only when the description is not hidden.

3.2.7.6. Miscellaneous XHTML Section Roles

In order to synchronize with the XHTML Role Attribute module, WAI-ARIA includes two XHTML roles which are neither landmarks nor widgets of any kind. These roles were incorporated to replace standard elements found in host languages. These roles are definition and note. If either role has a corresponding element in the host language, it is recommended that authors use the corresponding element in the host language.

The definition role indicates a definition statement in your document. For HTML developers implementing lists of definitions, we recommend you using the DL, DT, and DD elements rather than marking an arbitrary element with a role of definition. An arbitrary element would be appropriate for inline definitions used in conjunction with the DFN element.

Example of an inline definition with an explicit labelledby relationship:

<p>The doctor explained it had been a <dfn id="placebo">placebo</dfn>, <span role="definition" aria-labelledby="placebo">  
an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
</p>

Example of an inline definition with an implicit labelledby relationship determined by nesting:

<p>The doctor explained it had been a <span role="definition">
<dfn>placebo</dfn>, an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
</p>

Note: In the case where host language semantics do not allow for implicit nesting of definitions terms inside definition roles, authors should explicitly use the aria-labelledby attribute, even when the definition term is nested in the definition as shown here:

<p>The doctor explained it had been a <span role="definition" aria-labelledby="placebo">
<dfn id="placebo">placebo</dfn>, an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
</p>

The following is an example using a definition list:

<dl>
 <dt id="anathema">anthema</dt>
 <dd role="definition" aria-labelledby="anathema">a ban or curse solemnly pronounced by ecclesiastical authority and accompanied by  
excommunication</dd>
 <dd role="definition" aria-labelledby="anathema">a vigorous denunciation : cursor</dd>
<dt id="homily">homily</dt>
<dd role="definition" aria-labelledby="homily">a usually short sermon</dd>  

<dd role="definition" aria-labelledby="homily">a lecture or discourse on or of a moral theme</dd>

</dl>

The note role defines a parenthetic or ancillary remark to the main content of the resource. It also allows assistive technologies to skip over this section of the document unless more information is requested about the main content.

<div role="main" aria-labelledby="foo">
   <h1 id="foo">Wild fires spread across the San Diego Hills</h1>
   Strong winds expand fires ignited by high temperatures …
</div>

<div role="note">
   This article was last updated July 30, 2008 at 6:05PM. 
</div>

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. WAI-ARIA provides the aria-labelledby and aria-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. Labeling

When using one element to label another use the aria-labelledby by attribute. A label should provide the user with the essence of what the object does. For example, you could have a dialog box erected from HTML <div> and you need to assocate a label for the dialog. With a WAI-ARIA role of dialog, you can indicate its widget type and define a label using an HTML header and then associate that label with the dialog using the aria-labelledby relationship.
	<div role="dialog" aria-labelledby="dialogheader">
	<h2 id="dialogheader">Choose a File</h2>
	… Dialog contents
	</div>
	

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.

The aria-labelledby property can be used to label all visual objects, however it should be noted that (X)HTML provides a @for attribute on the label element which is used to label form controls. Use this attribute where possible and valid. Because the aria-labelledby attribute accepts multiple IDREFs, it is recommended that authors use aria-labelledby for labeling elements that require more than one label string.

Some elements receive their label for embedded text content, but that is the exception.

Often user agents will operate with images turned off for network performance reasons. In these situations, alt text is provided in the place of the image. When the host language provides alternative text capability it is recommended that authors use the alternative text to support these situations and not use separate labeling as a replacement.

4.1.2. Describing

4.1.2.1. Using aria-describedby

When one element describes another, use the aria-describedby attribute. An aria-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:

<button aria-label="Close" aria-describedby="descriptionClose" 
    onclick="myDialog.close();">X</button>
and then elsewhere in the HTML
<div id="descriptionClose">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.
4.1.2.2. Using a tooltip as a description

WAI-ARIA also defines the tooltip role to which aria-describedby may reference an author defined tooltip. The assistive technology can tell from the type of object describing the document element what the purpose of that element is. For example, a screen reader could announce the tooltip without the user having to wave the mouse over the element by following the describedby relationship to a document area with a tooltip role. The aria-describedby property is also useful for describing groups.

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 optional</div>    
  </div>
4.1.2.3. Descriptions on external pages

The aria-describedby property is not designed to reference descriptions on an external resource—since it is an IDREF, it must reference an element in the same DOM document. This is different from the HTML longdesc attribute, which accepts any URI. In general, the preferred pattern for WAI-ARIA applications is to include all relevant resources in the same DOM, But if you wish to reference an external resource with aria-describedby, you can reference a link that in turn references the external resource. This requires the user to follow two steps, first following the aria-describedby arc, then following the link, but does address the use case. The following example demonstrates this:

<p>
   <img
       src="images/histogram.png"
       alt="Histogram of Blackberry tree heights"
       width="40%"
       aria-describedby="longdesc1"
   />
</p>

<p>
    <a id="longdesc1" href="blackberry-description.html" target="_description">Data for Blackberry Histogram</a>
</p>

It is not good practice to use the above pattern when the describing element—the <a> tag with @id='longdesc1'—is hidden, since there is no way for a user to navigate to and activate the link. Use the technique only when the description is not hidden.

4.2. Owning and Controlling

Two relationships expand the logical structure of a WAI-ARIA Web application. These are aria-owns and aria-controls .  The aria-owns relationship completes the parent/child relationship when it cannot be completely determined from the DOM created from the parsing of the markup. The aria-controls relationship defines a cause-and-effect relationship so that assistive technologies may navigate to content effected by and changes to the content where the user is operating.

4.2.1. The Owns Relationship

In addition to WAI-ARIA role and state information, for a document element, an assistive technology needs to convey its context. In the case of a treeitem, it is important to know the parent (container), which may provide a folder depth and the number of siblings in the folder. This containment hierarchy can often be determined by the DOM tree, as it provides parent, siblings, and children for a given document element. That said, the DOM hierarchy is rigid and acyclical in that each node may only have one parent. In some situations, a child is reused by multiple parents or a child is separated from its sibilings or parent in the DOM tree. One example is when a radio button appears in a table but it is not a DOM child of the radiogroup, due to the authors use of a table for formatting and the placement of the radio buttons placing them outside the radiogroup container. To solve this problem WAI-ARIA provides the aria-owns property.

The aria-owns property is set on a document element, and its values are the unique IDs of all the adopted children. These elements may appear anywhere in the DOM, yet they are treated as siblings of each owning parent. This example illustrates a radiogroup that first uses the DOM hierarchy to convey context and then aria-owns:

First, consider the preferred method for using the W3C DOM to describe the relationship between radiogroup and radio roles for HTML:

<div id="radio_label">My radio label</div>
<ul role="radiogroup" aria-labelledby="radio_label">
<li role="radio">Item #1</li>
<li role="radio">Item #2</li>
<li role="radio">Item #3</li>
</ul>

In this example, the elements with role="radio" are child nodes of the parent role="radiogroup" element node.

Now, consider an alternative method using the aria-owns property to describe the parent-child role relationship between radiogroup and radio roles for HTML:

<table>
<tr>
<td role="radiogroup" aria-owns="myradio1 myradio2 myradio3" rowspan="3" >
My Radio Label
</td>
<td id="myradio1" role="radio">Item #1</td>
</tr>
<tr>
<td id="myradio2" role="radio">Item #2</td>
</tr>
<tr>
<td id="myradio3" role="radio">Item #3</td>
</tr>
</table>

The aria-owns property should be used sparingly, since it increases the computational load on assistive technology to provide alternative renderings. Also, when accessing the DOM and enumerating children of a DOM node, an AT should then enumerate the adopted children using the aria-owns property. At that instance of walking the DOM, the parent of the adopted children is the adopted parent and not the DOM parent. This will avoid recursion problems.

Each child, adopted or natural, should have the appropriate aria-posinset and aria-setsize properties set consistent with their rendering, if these cannot be determined from the DOM from a direct parsing of the host language. Places where direct parsing does not allow the user agent to determine aria-posinset and aria-setsize are long lists where only the currently visible items are loaded (via Ajax). If the children are re-sorted then the aria-posinset and aria-setsize values should be updated consistent with their visual rendering. Rather than setting size only on a container, content authors should specify aria-setsize on each member of a set to avoid performance issues.  If this property is not set, the user agent must compute and set the property on supporting roles.

Platform accessibility API mappings must invert this relationship for assistive technologies, so that they may determine the owning parent from a child and couple it with aria-posinset and aria-setsize information to provide context information to the user.

4.2.2.  Using Owns with Reusable Content

If you are re-using content across different, transient sections of content by restyling it to render it in association with a different object, you need to maintain the aria-owns property as well to match the current use and apparent ancestry of the reused sub-section. A good example of this is a context help menu that resides at the end of the document. When the user wishes to launch the context help menu in association with different visual elements, styling is used to render the menu in context with that object. Prior to rendering the visual submenu you should ensure the object to which you have requested help assigns its aria-owns property value to the submenu ID. When the menu closes you can remove the aria-owns property.

4.2.3. The Controls Relationship

In rich internet applications document elements may control the behavior on another part of Web page outside themselves. The aria-controls attribute indicates cause-and-effect relationships between document elements.

An example might be a group of radio buttons that "control" contents of a listbox in another part of the page. Here, you would want the radio group to assign a aria-controls relationship to the listbox which will be updating without a page reload. The user, through their assistive technology, can then navigate to the listbox by following the aria-controls relationship when a different radio is selected, to see how the contents changed in the listbox. The ability to update parts of a page without a page reload is a common practice of applications making use of Ajax. Without the aria-controls attribute, a user would be unable to effectively use these types of Web pages as assistive technologies often will not make the user aware of what is happening outside the context of the element the user is currently operating.

With the aria-controls attribute the user may use the assistive technology to follow the relationship to the object it is controlling. It is extremely important for an assistive technology to present changes in the document in response to user input. Therefore, an assistive technology immediately presents changes to a live region when the controlling widget is the one which has user keyboard focus. For example, if a tree view controls a help document pane, each time
the tree item changes the new tree item and then the new help contents should also be read. In the case of a screen reader, the amount of information read in the target live region is dependent on how the live region is configured.

The aria-controls attribute takes one or more ids which refer to the document element. If this relationship is not implied by the host language semantics, then the controlling element must be given a controls attribute with the IDs of the other elements where the changes will show up listed in the attribute value.

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.

Although it is recommended that Tab order follow the reading flow, there may be instances where this is not possible. For these reasons, WAI-ARIA provides a relationship property, called aria-flowto. This allows the author to provide an assistive technology with alternative navigation flows through the document that best represents the author's intent and which is more logical for people with disabilities. aria-flowto establishes the recommended reading order of content, so that the an assistive may overriding the default of reading in document order to its user. aria-flowto does not change the keyboard navigation order of the browser.

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. 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." The end user can change the order if the web page or assistive technology provides an interface for such personalization.

<html><div role="main" title="Top News Stories" id="main" aria-flowto="stock"></div>  
<div role="complementary" title="television listings" id="tv"></div>
<div role="complementary" title="stock quotes" id="stock" aria-flowto="messages"></div>
<div role="complementary" 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 work flows or business process management applications. 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.

4.4. Popups and drop-downs

In order for menus, menubars, and menuitems to indicate that it opens a menu, set its aria-haspopup property to "true." The type of menu being launched (submenu, context help, etc.) is not explicitly indicated with WAI-ARIA but is based on the operational characteristics (keyboard and mouse commands).

Combo boxes, or drop down lists, work differently. Controls with the role combobox must contain a list of items that can be opened, usually as a drop-down. Because this is intrinsic to the functionality of a combo box, it does not need to be explicitly indicated with aria-haspopup.

The following html fragment shows the use of aria-haspopup with a menubar, its menus, and submenus. All of the menuitems associated with the menubar have aria-haspopup set to 'true'. Also, the "Zoom" menuitem of the "View" menu has an aria-haspopup property as it leads to a submenu.

<div role="menubar">
  <!--
    File menu: File menuitem has an aria-haspopup attribute set to 'true'.
    That popup div follows immediately below.
  -->
  <div role="menuitem" aria-haspopup="true" id="fileMenu">File</div>
  <div role="menu" aria-labelledby="fileMenu">
    <div role="menuitem">Open</div>
    <div role="menuitem">Save</div>
    <div role="menuitem">Save as …</div></div>
  <!--
    View menu:
  -->  
  <div role="menuitem" aria-haspopup="true" id="viewMenu">View</div>
  <div role="menu" aria-labelledby="viewMenu">
    <div role="menuitem">Normal</div>
    <div role="menuitem">Outline</div>
    <!--
      The View's Zoom menuitem has aria-haspopup='true' as it leads to a
      submenu.
    -->
    <div role="menuitem" aria-haspopup="true" id="zoomSubMenu">Zoom</div>
    <div role="menu" aria-labelledby="zoomSubMenu">
      <div role="menuitem">50%</div>
      <div role="menuitem">75%</div>
      <div role="menuitem">100%</div>
      <div role="menuitem">150%</div>
      <div role="menuitem">200%</div>
    </div>
  </div>
</div>

5. Managing Dynamic Changes

5.1. Managing Content and Presentational Changes

General rules for managing content and displaying information

If you are refreshing areas asynchronously, then you need to designate live regions. The following sections explain how to implement live regions and when to use roles that are considered "live" sections by default, including alert, status, or log.

5.2. Implementing Live Regions

Live regions are parts of a Web page that the 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.

The section on Live Region Properties and how to use them gives the details of how to apply live region properties. This process will help rich internet application (RIA) developers to set live region settings that will provide a good user experience for most assistive technology users with little configuration on their part. When applying these live region properties, it is recommended that you conduct user testing. If the AT supports scripting of the response to live regions you may wish to customize the response, such as through a screen reader script for your Web page.

  1. Identify the live regions

    Live regions are any region on a page that receives dynamic updates through client-side scripting. Note the regions of your page that will be live.

  2. See if any of the special case live regions meet your needs

    WAI-ARIA provides a number of special case live region roles whose live region properties are pre-defined and which you may use. If one of these live region roles meet your needs just apply the specific role to the region of the Web page.

  3. 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 to hear 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:

  4. 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 aria-atomic="true".

  5. Decide what types of changes are relevant for each live region

    Three possible types of changes are: additions, removals, and text. Additions means new nodes are added to the DOM; removals means nodes are removed from the DOM; and text means changes are 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".

5.2.1. Live Region Properties and How to Use Them

One of the most important concepts behind live regions is politeness. Politeness indicates how much priority a live region has. The following politeness values are available for aria-live: off, polite, and assertive.

aria-live="off"
This is the default. Any updates made to this region must not be announced to the user. live="off" would be a sensible setting for things that update very frequently such as GPS coordinates of a moving vehicle.
aria-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.
aria-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" must be used if there is information that a user must know about right away, for example, warning messages in a form that does validation on the fly.

There are times to suppress AT presentation changes while a region is updating. For that you can use the aria-busy (state) property.

aria-busy (state)="true"

To suppress presentation of changes until a region is finished updating or until a number of rapid-fire changes are finished, set aria-busy (state)="true" and then clear the attribute when the region is finished. While it is busy, the AT will track and collate the changes. It will finally speak the changes once the region is no longer busy.

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.

aria-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.
aria-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. Note that when aria-atomic="true", the AT will attempt to speak the atomic region only once when multiple changes occur in the same region and it hasn't been spoken yet.
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" and this is the most common use case. If the default is applicable to your application, you do not need to provide the relevant property explicitly.
aria-relevant="additions"
Insertion of nodes to the live region should be considered relevant.
aria-relevant="removals"
Removal of nodes to the live region should be considered relevant. Often, removals are not relevant because nodes are removed to make space for new information - e.g. a log implemented as a table where items are taken off the top. However, in the case of something like a buddy list, it is relevant if a buddy is removed. It doesn't require the screen reader to speak the removal, but it notifies the screen reader that it could be useful to do so. Use of aria-relevant="removals" or aria-relevant="all" should be used sparingly. Notification of an assistive technology when content is removed may cause an unwarranted number of changes to be notified to the user.
aria-relevant="text"
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.

This example shows two live regions. If both regions update simultaneously, liveRegionA should be spoken first because its message has a higher priority than liveRegionB.

<div id="liveRegionA" aria-live="assertive">         
</div>         
<div id="liveRegionB" aria-live="polite>         
</div>

5.3. Choosing Between Special Case Live Regions

You may wish to use a special live region role instead of applying live region properties. WAI-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 must 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, if your operating system supports this type of event notification. When choosing to use alert you should use the alertdialog role instead if something inside the alert is to receive focus. Both alert and alertdialog appear to pop-up to the user to get their attention.

status - You must 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. 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. The use of status does not guarantee how the AT will respond to changes in the status. The author can still put live="off" or live="assertive" to influence the ATs treatment of the status.

timer - You must use a timer role when you want to mark an area which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The text encapsulated within the timer indicates the current time measurement, and are updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point.

marquee- You must use a marquee role when you need to mark an area with scrolling text such as a stock ticker. The latest text of the scrolled area must be available in the DOM. A marquee behaves like a live region, with an assumed default aria-live property value of "polite."

log - You must use log if you have a live area where new information is added, like a scrolling chat log of text. Unlike other regions, implied semantics 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 you 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-labelledby="gettext">
</div

live region - If you have some other live area use case, WAI-ARIA allows you to mark an area using the aria-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 this guide.

Live region roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. It is recommended that authors apply live regions to DIV and SPAN containers. For example:

<!-- Live region 'log' role used with TABLE element:  the 'log' role is not consistently mapped to platform AAPI. -->
<!-- Do not use. -->
<table role="log" … ></table>

<!-- Wrap the TABLE element in a DIV with role 'log' instead: -->
<div role="log" … >
  <table … ></table>
</div>

6. Presentation Role

This section describes the presentation role, including the conditions under which it is inherited by an element's children.

6.1. Rationale

Authors devote a good deal of effort to the appearance of their web pages, and this is especially true in the case of scripted web applications. To this end authors employ various elements purely for visual presentation. For example, <img> elements are used for spacing and decoration; and <table>s are used to create a column based layout. Elements used strictly for presentation are semantically neutral and irrelevant in terms of accessibility. It is necessary to mark such elements as presentational so that they do not appear in the accessible tree created by the user agent. For example, a current technique used with spacer images is to provide blank alt text to indicate that the image is not meaningful. User agents will not publish any information about images with blank alt text to the platform accessibility API.

There are elements other than <img> and <table> that are used solely for visual presentation. Any element is a potential candidate for presentation, and, if so used, these elements also need to be marked as semantically neutral.

Note: It is important to separate content and presentation. CSS 3 has introduced new table layout functionality to allow a user agent to layout content using CSS. There are many advantages to using this feature of CSS such as browser style sheet caching and improved adaptability to mobile devices with limited screen real estate. There are, however, cases where presentational markup cannot be avoided. In such instances, authors are counseled to consult WCAG 2.0 for more detailed guidance.

WAI-ARIA introduces the presentation role as a general device for marking elements as presentational. The presentation role overrides the element's native implicit role, and informs the user agent to not publish the element to the accessiblity API. In fact, the preferred way to mark <img> elements as decorative is to use a role="presentation" attribute instead of (or in addition to) an empty alt attribute. Here is a code fragment sample:

<!-- [role="presentation"] informs the user agent that the spacer images are for layout only. --><h2>Other Histories of Architecture</h1>
<p>
  <a href="www.somewhere.com">Ancient Roman Architecture</a>
  <img src="spacer.png" role="presentation">
  <a href="somewhere.else.com">19th Century Italian Architecture</a>
  <img src="spacer.png" role="presentation">
  <a href="www.elsewhere.com">Modern Buildings more than 100 Years Old</a>
</p>

<h2>Modern Building Design</h1>

The resulting accessible tree is shown below. Note that none of the spacer <img> elements are present:

6.2. Inheritance of Presentation by Parent Element's Children

In general, the presentation role is not inherited by an element's children. The exceptions are elements whose role entails that the element has required owned children. Examples include the <table> element and list role, and these exceptions are discussed further below. For all other elements, only the element marked presentational is eliminated from the accessible tree. Note, however, that its contents are published; in particular, the element's textual content is published, but any attributes of the element that may form a text-equivalent are not. For example, a header element with a presentation role would not appear in the accessible tree, but its text does. An image with a role of presentation is not exposed in the accessible tree, nor is the contents of its alt attribute. This is shown in the following code fragment:

<!-- 1. [role="presentation"] negates the implicit 'heading' role semantics but does not affect the contents. -->
  
<h1 role="presentation">Presentation role overrides Header role</h1>
<h1>Another header</h1>
  
<!-- 2. [role="presentation"] hides the image from the accessibility API and does not publish the alt attribute contents. -->
  
<img role="presentation" alt="This text will not appear in the Accessibility API" src="…">
  

The first header element is absent from the accessible tree for the above example, but its text appears. The second header element is present as a heading. The img element is not exposed at all:

Be aware that the markup <img role="presentation" alt="non-empty alt text"…> is in fact contradictory: Declaring a role of presentation says that the image is for layout, is decorative and meaningless, whereas the non-empty alt text implies that the image is meaningful. It is recommended that authors instead use empty alt text (alt="") where they use role="presentation".

Earlier it was noted that the presentation role is not generally inherited by an element's children. The exception are roles that have required owned elements. Examples include the <table> element, and the list and tree roles. A list is required to have listitem children; a tree, treeitem children. The <table> element's child components are <tbody>, <thead>, <tfoot>, <th>, <tr>, <td>, and <caption>. These component elements would not appear in the markup without the enclosing <table> root element. Thus, when a table is used for layout, it follows that all of its component elements are present in the markup for layout as well. Since annotating all the required child elements with role="presentation" is error prone and difficult to maintain, it is sufficient to mark the table root element as presentational. The presentation role propagates to all the table component elements. However, as before, the contents of the table elements do appear in the accessible tree. Here is an example:

<!-- Layout table marked with [role="presentation"]. -->

<table role="presentation">
  <tbody>
    <tr> <td>Some text</td> <td><p>Paragraph</p></td> </tr>
    <tr> <td><a href="www.somewhere.com">Link text</a></td> <td><img src="meaningful.jpg" alt="meaningful image"></td> </tr>
  </tbody>
</table>

All table specific elements (table, tr, td, etc.) are eliminated from the tree by inheriting the presentation role, but other elements and textual content in the table cells are exposed:

The same logic applies to other roles that have required owned children, such as a list. If the list's root element is declared presentational using role="presentation", all of its listitem elements inherit the presentation role, and none of the list item elements appear in the accessible tree. However, the contents of each list item, that is, other elements and textual content, are included in the tree.

6.3. Overriding Presentation

The presentation role is overridden in some circumstances. Recall that the presentation role informs user agents that certain elements are semantically neutral, and are irrelevant for accessibility. If, however, there is an aspect of an element that makes it meaningful, it is no longer neutral, and cannot simultaneously be presentational. The User Agent Implementation Guide describes the cases where this occurs:

These situations entail that the given element is semantically relevant and will appear in the accessible tree. Marking the element with a role="presentation" is an error, and user agents will ignore the presentation role in these cases. Authors are advised to not mark an element with a role of presentation when it has any of the above properties; rather, to use a role that reflects the element's purpose.

7. Form Properties

This section identifies authoring practices for elements used as form elements.

Use aria-invalid and aria-required To Improve Access to Forms

Until the introduction of WAI-ARIA's aria-invalid state and aria-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, these states are only available through styling or varying markup, which is inconsistent, and therefore is inconclusive. 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 WAI-ARIA invalid state and required property provide:

Alert the User When Maximum Length Value Is Reached

When a text input field that has a maximum length value (or the host markup language's equivalent) receives focus, the value defined for "maximum length" should be communicated to the user. When text entry reaches that maximum length (or the markup language's equivalent), an alert (expressed in accordance with user preferences and capabilities) should inform the user that the maximum length for a given field has been reached. Such an alert can be expressed programmatically or, using as an aural icon, by using a WAI-ARIA alert; the user agent may alert the user through a system beep and by triggering the operating systems' "show sounds" facility. When maximum length (or the markup language's equivalent) is reached, the user must then be able to move to another form field in a manner consistent with tab-navigation for that document.

Automatic Focus Changes

Having a user agent automatically change focus in a form in response to user input can be advantageous in situations where that change saves the user keystrokes or on-screen keyboard interaction in order to manually move the focus from one field to another. However, as with form auto-completion, this type of text input event must be firmly under user control because this may not have been the user's intention and some users with disabilities may become disoriented such as those with sight impairments. Consider these cases:

Form Auto-submit

Use caution when using automatic submission of a form without explicit user command or in response to a user-defined setting that permits such behavior, as expressed by the Priority 1 UAAG 1.0 Checkpoints 7.1, 7.2 and 11.1. Unless the user has specifically chosen to set the user agent to allow auto-submission, authors are advised not to set onChange or onFocus events either to trigger submission of a form or to provide an auto-submission event upon completion of all or all required fields of a form or input field.

8. Math

Editors' note: This section was added as part of disposition of comment 4, but is very incomplete. The section needs to be reordered, so that instructions on how to use the math role properly appear before considerations of legacy content and negative examples (such as the use of generic HTML to approximate a visual representation of a mathmatical expression). It needs more introductory text about how to use math. The examples need better introductions, and the positive examples should preceded the negative examples, which need to be explained more fully.

There exists significant amounts of legacy content that uses images and/or textual approximations to represent mathematical expressions. Examples of this include the use of ASCII art and/or the misuse of HTML tags -- in particular, SUB and SUP -- to achieve a visual approximation of a mathematical expression, one which is void of the structure needed to render mathematical expressions inherently meaningful.

Use of generic HTML to approximate a visual rendering of a mathematical expression:

<i>a</i><i>x</i><sup>2</sup> + <i>b</i><i>x</i> + <i>c</i> = 0

Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

<div role="math" aria-label="a times x squared plus b times x plus c equals 0">
  <math xmlns='http://www.w3.org/1998/Math/MathML'>
    <mrow>
      <mrow>
         <mrow>
            <mi>a</mi>
            <mo>&#x2062; <!-- invisible times --></mo>
            <msup>
              <mi>x</mi>
              <mn>2</mn>
            </msup>
         </mrow>
         <mo>+</mo>
         <mrow>
            <mi>b</mi>
            <mo>&#x2062; <!-- invisible times --></mo>
            <mi>x</mi>
         </mrow>
         <mo>+</mo>
         <mi>c</mi>
      </mrow>
      <mo>=</mo>
      <mn>0</mn>
    </mrow>
  </math>
</div>

Similarly:

<i>f</i>(<i>x</i>) = <i>x</i><sup>2</sup> + <i>x</i> - 2

Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

<div role="math">
  <math xmlns='http://www.w3.org/1998/Math/MathML'>
    <mrow>
      <mrow>
         <mi>f</mi>
         <mo>&#x2061;</mo>
         <mrow>
            <mo>(</mo>
            <mrow>
               <mi>x</mi>
            </mrow>
            <mo>)</mo>
         </mrow>
      </mrow>
      <mo>=</mo>
      <mrow>
         <msup>
           <mi>x</mi>
           <mn>2</mn>
         </msup>
         <mo>+</mo>
         <mi>x</mi>
         <mo>&#x2212;</mo>
         <mn>2</mn>
      </mrow>
    </mrow>
  </math>
</div>

9. 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(s) 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.

WAI-ARIA introduces two new Drag and Drop properties that aide Web application authors with the drag and drop process, called aria-grabbed and aria-dropeffect. The property aria-grabbed (state) is applied to the source(s) being dragged, while aria-dropeffect is applied to the target(s). Use of these properties--combined with best practices for enabling the user to select the appropriate drag operations 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.

  1. Identify draggable objects

    Set the initial aria-grabbed (state) state of all draggable interface objects. Roles that typically support drag and drop operations are listitem and treeitem. The default state for all objects is assumed to be undefined, meaning that they are not draggable. For objects that may be dragged, set the aria-grabbed (state) state to "false". This will allow assistive technologies to indicate which objects are draggable and potentially facilitate in choosing the objects to grab.

    Objects that can be dragged need to have a determinable role. HTML tags such as <div> and <span> provide no semantics, unlike <select>, and would require you to set the WAI-ARIA role attribute.

    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 to 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. At this point, qualified drop targets cannot be determined as they are determined based on the objects being dragged--which have not yet been selected.

    All grabbable objects must be navigable using the keyboard.

  2. Allow the user to initiate the appropriate drag operation using the keyboard

    The author must provide a keyboard accessible way of selecting one or more elements to drag. It is recommended that the space bar be used for selection. It is further recommended that Shift+Space be used to select multiple objects and define a contiguous set; and that control+space be used to define a noncontiguous set. As each object is selected, its aria-grabbed (state) property must be set to "true", giving the ATs references as to what has been grabbed. It is recommended that Control+M be supported to indicate that all objects have been selected for drag.

    Note: Selection of the objects to be dragged may differ depending on their type. For example, a list of emails might be selected one at a time or many at a time in contiguous or non-contiguous manner using the Space key as indicated above. However, text in a document might better be selected by positioning the cursor at the beginning of a word and holding down the Control key while using the right and left arrow keys to mark the letters you wish to move.

  3. Mark the drop targets

    When the user has completed selecting source objects to drag, you must indicate which targets may receive them by setting the aria-dropeffect properties on those targets. This will indicate to the assistive technology that all objects have been grabbed as well as what targets are capable of receiving the drop.

    When using a mouse, users click, hold the mouse button, and drag the mouse when moving the selected objects, and, by implication, are no longer selecting them. With respect to keyboard users, the previous section, Item 2, "Allow the user to initiate the appropriate drag operation using the keyboard", recommends using Control+M to indicate the end of the selection phase.

    * 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.
    * link:
    A reference or short cut to the dragged object will be created in the target object.
    * execute:
    A function supported by the drop target is executed, using the drag source as an input.
    * popup:
    The author must provide a popup menu or dialog to allow the user to choose one of the drag operations (copy, move, reference) and any other drag functionality, such as drag cancel.
    * none:
    no drop operation is supported. This is the default for all objects.

    Example:

    <div role="treeitem" aria-dropeffect="copy move popup">
    

    CSS may 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 an aria-dropeffect property set will have an assumed aria-dropeffect value of "none." Any object with an aria-dropeffect value of "none" is ignored by ATs in the drop operation.

  4. Implement keyboard functionality to assist the user and AT with executing the drop.

    After all objects have been grabbed, the author should provide standard keyboard accessible navigation (such as through tabbing) to enable the user to navigate to the desired drop target. To achieve this, you may optionally support Shift+F10 to invoke a single select list of possible drop targets from which the user may choose a single drop target that, when selected, would move focus to that drop target. Otherwise, you must provide a keyboard accessible way (through tabbing and arrowing) to allow the user to navigate to the drop target. The user's point of regard should be clearly visible during this navigation.

    When the user arrives at the drop target the author should provide a keyboard accessible way to drop the selected object(s) onto the target. Control+M should be used to provide the most intuitive type of drop, either copy, move, or a shortcut. In the case of only one drop operation available, the Control+M should be used to drop the selected object(s) onto the target.

    If drop target supports additional drop operations, then the author should provide a WAI-ARIA-enabled pop-up menu from which the user can choose supported operations from the list. A recommended way to invoke this menu is to use the Shift+Control+M key sequence when focus is on the drop target. Furthermore, the aria-dropeffect property should include "popup" in its list of values to indicate that a keyboard accessible menu is provided. After the user has selected an action from the pop-up menu, the menu must close, with focus returning to the drop target. If the user does not choose an action and instead presses the Escape key, the application must dismiss the menu, returning focus to the drop target.

  5. Cancelling a drag operation

    Users can cancel the entire drag operation at any time, with one exception, by pressing the Escape key. The one exception is when the drop operations pop-up menu is displayed (see previous step four above). In this case, Escape simply dismisses the pop-up, and a second Escape keystroke is needed to cancel the drag operation. When the drag operation is so cancelled, all aria-dropeffect properties are set to "none", all grabbable objects' aria-grabbed (state) properties are set to "false", and keyboard focus returns to the last grabbed source object.

  6. Clean-up after drag/drop

    Once the drop has occurred, you should clean up the DOM as you would do for drag-and-drop operation. This should include setting:

    • All aria-dropeffect properties to "none" or remove them altogether.
    • All aria-grabbed of draggable objects to "false".
    • All objects that are not grabbable must either omit the aria-grabbed property or have an aria-grabbed property set to "undefined."
    • Focus on the appropriate DOM element, and its role must also be determinable.

    Other methods of performing the same operation as drag-and-drop may be the best way to meet the accessibility requirements. As an example, when moving a mail message from the inbox to another folder, a list of those folders could be presented in a select list as an alternative to drag-and-drop.

  7. Document non-recommended keyboard navigation

    If the author must use alternatives to the keyboard navigation recommended here, it should be documented on the page.

10. States and Properties, and Assistive Technologies

Assistive Technologies (AT) access WAI-ARIA state and properties via a platform accessibility API. An example of such an API is Linux's AT-SPI. The user agent is responsible for publishing WAI-ARIA roles, states, and properties and relevant changes via the accessibility API. For more information, see the User Agent Implementation Guide.

With respect to desktop applications, the interaction between the platform accessibility API and an AT is bidirectional. The application sends information to the AT using the accessibility API, and the AT can request a change in the accessible state of an application through the same accessibility API. However, with respect to ARIA 1.0, the flow of information is one way only from WAI-ARIA to the accessibility API. There is no provision, currently, to go the other way. An AT cannot use an accessibility API to alter any WAI-ARIA information in the DOM.

The reason is that there is no consistent cross-browser implementation of a mutation event that web applications can rely on to detect when a WAI-ARIA state or property has changed. Web applications use WAI-ARIA information for rendering their components. For example, if the web application includes a DHTML checkbox as part of its interface, then the web app renders the visual appearance of the checkbox based on its aria-checked state. If an outside agent were to change the state of that checkbox without the web app receiving any notification, then the checked state of the checkbox is no longer in agreement with its visual appearance. It is likely that the behaviour of the web app will suffer.

W3C is investigating device-independent interfaces to allow web applications to receive notification of changes to WAI-ARIA states and properties. When this is available, WAI-ARIA will be bidirectional with respect to the platform accessibility API, allowing Assistive Technologies to alter WAI-ARIA states and properties. Even so, the set of states and properties that an Assistive Technology is likely to change is limited to the following:

The following States and Properties are unlikely to be manipulated by an assistive technology: An AT would need to have greater understanding of the application and the results could be adverse.

11. Design Patterns

For these widgets and structures, this document describes the keyboard interaction and identifies the relevant WAI-ARIA roles, states, and properties.

If the host language does not define key mappings, such as hot keys, and the author defines key mappings other than those described here or in Drag-and-Drop Support, then the author must provide documentation of those key mappings. These mappings can be provided in the contents of the web page, or in the case of a more complex application, within the help file documentation and training materials.

Note: Although users of Mac OS X are familiar with using the Command key instead of the Control key, the Command key is typically reserved for desktop applications and OS-level integration. Until device and platform independence can be addressed in WAI-ARIA 2.0, the primary Control modifier key for WAI-ARIA widget interaction is specified as Control on all platforms, including Mac OS X.

Global Recommendations

The following may apply to some or all widgets.


Accordion (widget)

Characteristics:
Description:

An accordion component is a collection of expandable panels associated with a common outer container. Panels consist of a header and an associated content region or panel. The primary use of an Accordion is to present multiple sections of content on a single page without scrolling, where all of the sections are peers in the application or object hierarchy. The general look is similar to a tree where each root tree node is an expandable accordion header. The user navigates and makes the contents of each panel visible (or not) by interacting with the Accordion Header. Terms for understanding accordions include:

accordion component:
Collection of panels within a common outer pane.
accordion header:
Label area of an accordion panel. This is where you find the control to expand or collapse the panels.
accordion panel:
Contents area associated with an accordion header.
Keyboard Interaction:
  • Tab - When focus is on an accordion header, pressing the Tab key moves focus in the following manner:
    1. If interactive glyphs or menus are present in the accordion header, focus moves to each in order.
    2. When the corresponding panel is expanded (its aria-expanded state is 'true'), then focus moves to the first focusable element in the panel.
    3. If the panel is collapsed (its aria-expanded state is 'false' or missing), OR, when the last interactive element of a panel is reached, the next Tab key press moves focus as follows:
      • If a subsequent accordion panel is already expanded, focus moves to the first focusable element in this subsequent panel.
      • If no subsequent accordion panel is expanded, focus moves to the first focusable element outside the accordion component.
  • Left arrow
    • When focus is on the accordion header, a press of up/left arrow keys moves focus to the previous logical accordion header.
    • When focus reaches the first header, further up/left arrow key presses optionally wrap to the first header.
  • Right arrow
    • When focus is on the accordion header, a press of down/right moves focus to the next logical accordion header.
    • When focus reaches the last header, further down/right arrow key presses optionally wrap to the first header
  • Up arrow - behaves the same as left arrow
  • Down arrow - behaves the same as right arrow
  • Control+Up arrow - Moves focus from anywhere in the accordion content to its associated accordion header or tab respectively.
  • Control+PageUp -
    • When focus is inside of an accordion pane, pressing Control+PageUp moves focus to the accordion header of the previous accordion pane.
    • When focus is in the first accordion header content, pressing Control+PageUp optionally moves focus to the last accordion header.
    • Focus will simply move to the header and will require Enter/Space to expand/collapse the accordion pane.
  • Control+PageDown -
    • When focus is inside of an accordion pane, pressing Control+PageDown moves focus to the header of the accordion pane.
    • When focus is in the last accordion header content, pressing Control+PageDown optionally moves focus to the first accordion header.
    • In the case of an accordion, focus simply moves to the header and requires Enter/Space to expand/collapse the accordion pane.
  • End - When focus is on the accordion header, an End key press moves focus to the last accordion header.
  • Home - When focus is on the accordion header, a Home key press moves focus to the first accordion header.
  • Enter/Space - When focus is on an accordion header, pressing Enter/Space toggles the expansion of the corresponding panel.
    • If collapsed, the panel is expanded, and its aria-expanded state is set to 'true'.
    • If expanded, the panel is collapsed and its aria-expanded state is set to 'false'.
  • Shift+Tab - Generally the reverse of Tab.
  • Alt+Delete -
    • When deletion is allowed, with focus anywhere within the tab panel or tab, pressing Alt+Delete 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. If no additional tabs remain, then focus moves to the last place that held focus in the previous tab panel.
    • 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.
    • A warning should be given to the user before allowing the delete to occur.

In Firefox, pressing Control+PageUp / Control+PageDown moves between browser tabs. Firefox also supports Control+Tab and Control+Shift+Tab to move between tabs. Internet Explorer 7 also uses Control+Tab and Control+Shift+Tab. There may be advantages to using Control+PageUp/PageDown as the keys to change tabs because it is a recognizable keystroke to at least Firefox users and it is also supported by the Windows operating system to move between panels in a tabbed dialog.

You should be aware of two issues with using Control+PageUp/PageDown:

  • The first arises when the user is within a tabbed interface control on a Web page. Here they can not easily switch browser tabs without first moving focus outside of the tabbed interface control. This may be acceptable.
  • The second arises when the entire web page is a tabbed interface control. In this case the user could not switch browser tabs unless the control on the web page ignored the Control+PageUp/PageDown keypress (and thus letting the browser access it) when the first or last tab was reached.
WAI-ARIA Roles, States, and Properties:
  • The accordion component must have a role of tablist and have aria-multiselectable="true" This will enable an assistive technology, such as screen reader, to convey that the tablist is an accordion or a multiselectable tablist. This will also tell the user that the keyboard navigation matches an accordion and not a tablist.
  • Contained within the tablist is a set of tab/tabpanel pairs.
  • Each header tab in the tablist has a role of tab.
  • The accordion panel uses the role tabpanel and should have an aria-labelledby relationship referencing the correponding header having a role of tab
  • The tabpanel is considered a grouping for all content consisting of that tabpanel.
  • An accordion should manage the expanded/collapsed state of each tab by maintain its aria-expanded state.
  • An accordion should manage the selected state of each tab by maintaining its aria-selected state.
  • An accordion should convey the visibility of each tabpanel by maintaining its aria-hidden state.
Example:

Open Ajax Alliance Accordion


Alert (widget)

Characteristics:
Description: A message with important information
Keyboard Interaction:

An alert (WAI-ARIA live region) does not require any keyboard shortcuts

WAI-ARIA Roles, States, and Properties:

The widget has a role of alert.

Example:

Open Ajax Alliance


Alert or Message Dialog (widget)

Characteristics:
Description:

A dialog with the primary purpose of communicating a message and acquiring a user response to that message. Examples include action confirmation prompts, warning messages, or help for an invalid form entry. The dialog should be modal. Keyboard focus is set on an element in the dialog. The element that has initial focus will depend on the nature of the information conveyed in the dialog. Simple message dialogs, as described below, have their initial focus set to the confirmation button (e.g., the OK button). Detail message dialogs have their initial focus set on the element containing the message.

A detail message dialog conveys a message that has any one of the following attributes:

  • Is more than one sentence in length;
  • Contains information where punctuation is an essential part of the message, such as syntax of a required date format;
  • Contains detail information the user may need to re-use, e.g., a phone number, e-mail address, error number, etc.;
  • Contains an interactive element, such as a link to a help resource.

If the dialog is not a detail message dialog, one can consider it a simple message dialog.

Keyboard Interaction:

See Dialog (Modal).

  • Content authors make alert dialogs modal by ensuring that, while the alertdialog is shown, keyboard and mouse interactions only operate within the dialog.
  • The message area of a detail message dialog is focusable and has a document role so screen reader users will have complete access to the message content, e.g., the screen reader can read it by character, word, or line.
  • When the message area of a dialog is focusable and has focus, a visual focus indicator around the message is recommended.
WAI-ARIA Roles, States, and Properties:
  • The node containing all elements of the dialog, including the alert message and any dialog buttons, has an alertdialog role.
  • Message areas have role document and tabindex="0".
  • The Alert dialog has an aria-labelledby that references the title of the dialog. If there is not a visible title, use an appropriate aria-label instead.
  • The element with role alertdialog has an aria-describedby referring to the message element that has role document.
Example:

Open Ajax Alliance


Auto Complete (widget)

Characteristics:
Description:

A textbox and an associated drop-down list of choices where the choices offered are filtered based on the information typed into the box. Typically, an icon associated with the textbox triggers the display of the drop-down list of choices. An editable auto-complete accepts text entry of choices that are not in the list. An example of an editable auto-complete is the URL field in the browsers.

Keyboard Interaction:
  • With focus in an empty textbox, press Down Arrow, Up Arrow, Alt+Down Arrow, or Alt+Up Arrow to display the entire list of choices. Focus remains in the textbox and no choice is highlighted.
    • Press the Down Arrow to highlight the first choice in the list.
    • Press the Down Arrow and Up Arrow keys to highlight the desired choice in the list.
    • Note that the arrows will wrap through the textbox when the top or bottom of the list is reached. For example, pressing the down arrow when the last choice is highlighted will move focus back to the textbox, pressing down again will move focus to the first item in the list. Likewise, with focus in the textbox and the list displayed, pressing up arrow will move focus to the last item in the list.
    • When a choice is highlighted using the arrow keys, the highlighted choice is displayed in the textbox.
    • Press Enter to select the highlighted choice and close the drop-down list. This mimics the behavior of the HTML select element.
  • With the drop-down list of choices displayed, move the mouse pointer over an item in the list to highlight it. The textbox value is not modified when the mouse is used to highlight a choice. Clicking on the highlighted choice will close the drop-down and update the textbox with the selected choice. This mimics the behavior of the HTML select element.
  • With focus in an empty textbox, type any letter. If any of the available choices begin with the letter typed, those choices are displayed in a drop down. If the letter typed does not match any of the available choices the drop-down list is not displayed.
  • With focus in textbox with an existing value type additional letters. As the user types letters the list of choices is filtered so that only those that begin with the typed letters are displayed.
    • Until the user presses the arrow keys to highlight a particular choice, only the typed letters are displayed in the textbox.
    • In an editable auto-complete, if no choices match the letter(s) typed, the drop down list closes.
    • In a non-editable auto-complete, any letters that do not result in a match from the list are ignored, the drop down list of choices remains static until the user presses Escape to clear the text field, Backspace to remove some of the letters previously typed, or types an additional letter that results in a valid list of choices.
    • Navigation through the list of choices and display of the highlighted choice in the textbox works as described above.
      Optional: When a choice is highlighted via arrow key navigation, the input cursor is left at the end of the typed entry and the highlighted choice is displayed in the textbox with the characters after the input cursor selected. Typing an additional character will remove the auto-completed portion and append the newly typed character to the end of the previously typed characters. The list will be filtered based on the additional character(s) typed.
  • With focus in a textbox, press Escape
    • If there is no text in the textbox, pressing Escape closes the drop-down if it is displayed.
    • For an editable autocomplete that has text in the textbox that was both typed by the user and auto-completed by highlighting a choice using the keyboard, the auto-completed portion of the text is cleared and the user typed characters remain in the textbox. The drop-down list is closed. To completely clear the textbox contents the user must use the backspace key to remove the typed characters. This is how the Google search box in the Firefox UI works. Recommend that pressing the Escape key again completely clears the textbox rather than relying on only the backspace key.
    • For a non-editable auto-complete that has text in the textbox that was both typed by the user and auto-completed by highlighting a choice using the keyboard, pressing Escape closes the drop-down list and leaves the current choice in the textbox.
    • For an editable or non-editable auto complete with text in the textbox that was typed by the user and the mouse is highlighting a choice in the drop down (keyboard navigation was NOT used), pressing Escape closes the drop down and leaves the typed text displayed in the text box. Need to consider if pressing Escape again should clear the typed text. The user must press the Down arrow or Alt+Down arrow or click the associated icon to invoke the drop-down list of choices again.
  • Moving focus out of an empty auto complete field where a value is required should either invoke an error or if a default value was initially assigned, reset the value to the default value.
  • Moving focus out of an auto complete field that does not contain a valid entry should either invoke an error or if a default value was initially assigned, reset the value to the default value.

It is good practice to limit the number of matching items in the drop down to a reasonable number. The reasonable number is determined by the task at hand. A list of the 50 US States is probably reasonable, but a list containing all of the office numbers in a building is probably not appropriate.

WAI-ARIA Roles, States, and Properties:
  • The widget has a role of combobox.
  • The combobox has an aria-autocomplete property set to one of 'inline', 'list', or 'both'.
  • For more information, see the combobox design pattern.
Example: Dojo autocomplete

Button (widget)

Characteristics:
Description:

button widgets allow for user-triggered actions, and they are most often used for discrete, atomic actions. Buttons support the optional state aria-pressed (state). Buttons with this state are toggle buttons. When aria-pressed (state) is true the button is depressed, when pressed is false it is not depressed.

Sometimes a button will launch a dialog box. This is indicated using "…" (ellipsis) at the end of the button label. An example is "Save as …".

Keyboard Interaction:

With focus on the button, pressing Space 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.
WAI-ARIA Roles, States, and Properties:
  • The button receives a role of button.
  • The button description is given by its aria-describedby property.
  • When the action associated with a button is unavailable, the button displays in a aria-disabled state.
  • If the button is a toggle button, it has an aria-pressed state. When the button is toggled, the value of this state is true, and when not toggled, the state is false.
Example:

Check Box (widget)

Characteristics:
Description: A widget that has three possible values: true, false, or mixed.

Many checkboxes do not use the mixed value, and thus are effectively dual state checkboxes. However, the aria-checked (state) state supports the mixed value to handle cases, such as installers, where an option has been partially installed.

A tristate checkbox is frequently associated with a set of dual state checkboxes. The relationships between the tristate and dual state checkboxes are:

  1. tristate unchecked (aria-checked="false"): none of the dual state checkboxes are checked.
  2. tristate checked (aria-checked="true"): all of the dual state checkboxes are checked.
  3. tristate mixed (aria-checked="mixed"): some of the dual state checkboxes are checked.

If the tristate checkbox is currently unchecked and is clicked with the mouse, then it changes to checked and all of the dual state checkboxes are also set to checked. If the tristate checkbox is checked and is clicked, then it changes to unchecked and all of the dual state checkboxes are switched to unchecked. The behavior is the same if using the keyboard: if the tristate checkbox has focus, then Space switches between checked and unchecked states.

A tristate checkbox changes to the mixed state by interacting with the dual state checkboxes associated with it, such that only some of them are in a checked state. The effect is achieved using the mouse or keyboard by navigating among the dual state checkboxes, switching their checked state such that only some are checked while the rest are unchecked.

Although it requires effort, it is sometimes more user friendly to track which of the dual state checkboxes are checked. If that information is stored, then for the tristate checkbox, repeated clicking or pressing Space cycles through checked, unchecked, and mixed states. The associated dual state checkboxes correspondingly switch among all checked, all unchecked, and a checked subset -- the subset that the tristate's mixed state represents.

Keyboard Interaction:

Dual State Check Box

  • Space key toggles the selection, checking or unchecking the box.

Tristate Check Box

  • If not checked, Space:
    • Mixed state unknown: checks the check box.
    • Mixed state known: reinstates the mixed state.
  • If checked, Space unchecks the check box.
  • If mixed, Space checks the check box.
WAI-ARIA Roles, States, and Properties:
  • The checkbox should have a role of checkbox.
  • If checked it should have the state aria-checked="true".
  • If not checked it should have the state aria-checked="false".
  • If partially checked, it should have the state aria-checked="mixed".
  • If you use an image to render the state of a checkbox, it should not appear in the accessibility API mapping. This can be accomplished using CSS to render it or setting a role of presentation on the image.
  • Put the checkbox in the tab order, such as by setting its tabindex="0".
  • Checkboxes having a logical grouping should be children of a DOM element whose role is group.
  • The group should assign a label that is visible and referenced through the aria-labelledby property set to the ID of the label.
  • Use an aria-describedby property to add additional help information to the checkbox or grouping.
Examples:

Combo Box (widget)

Characteristics:
Description: A combo box enables the user to type in a field and at the same time chose a predefined value from a list. By using the keyboard the user can select an item from the list. After selection she will be able to type further characters in the field.
Keyboard Interaction:
  • Left Arrow or Right Arrow move the caret within the edit field.
  • Alt+Up/Down Arrow opens and closes the list.
  • Up Arrow and Down Arrow moves focus up and down the list. As focus moves inside the dropdown list, the edit field is updated.
  • Page Up/Page Down selects the next/previous pages item depending on the lists size.
  • Escape closes the dropdown list, returns focus to the edit field, and does not change the current selection.
  • Enter selects the current item on the list, updates the edit field, highlights the selected item in the dropdown list, closes the dropdown list, and returns focus to the input field.
  • Typing a letter (printable character) key moves focus to the next instance of a visible node whose title begins with that printable letter.

For combo boxes that implement aria-autocomplete, see the autocomplete design pattern.

WAI-ARIA Roles, States, and Properties:

A combobox can be implemented using either of two design patterns:

  1. As a combination of text field, which may be editable, a displayable list of items, and a drop button to toggle the display of that list; all wrapped in the form of a single widget with role of combobox.
  2. As a combobox, which behaves like a textfield and may be editable, with a displayable list of items, and a drop button to toggle the display of that list;

Like text fields a combobox should be labeled to convey the purpose of the widget. Keyboard focus within the widget must be managed by the widget. Comboboxes are used extensively in graphical user interfaces and the design pattern for the widget should be semantically correct.

For the first combobox design pattern:

  • The container element that wraps the combobox has a role of combobox.
  • The first element within the combobox is an input text field and is responsible for managing the keyboard focus between the text field and the list as well as displaying the list. The text field is in the tab order. If you create a text field without using a standard HTML text field form control then ensure that it is in the tab order.
  • If the text field is not editable it must have have aria-readonly = true.
  • The combobox must have aria-expanded = true if the list is displayed or aria-expanded = false when it is not.
  • The next element is an html <button>, or another element with a role of button. This element is used to toggle the display of the combobox's drop down list.
  • The next element has a listbox role and represents the drop down list. It manages keyboard navigation among list items and navigating back to the text field if necessary.
  • Each item in the listbox is an option. Options are not in the tab order.
  • Provide a label for the combobox by referencing the text field in the combobox. You can use an aria-label to associate this label with the combobox or you may use the HTML <label> element and its for attribute to reference the text field.

For the second combobox design pattern:

  • The first element for the combobox has a role of combobox and behavies like an input text field and is responsible for managing the keyboard focus between the combobox and the list as well as displaying the list. The text field is in the tab order. If you create a text field without using a standard HTML text field form control then ensure that it is in the tab order.
  • If the combobox is not editable it must have have aria-readonly = true .
  • The combobox must have aria-expanded = true if the list is displayed or aria-expanded = false when it is not.
  • The next element is an html <button>, or another element with a role of button. This element is used to toggle the display of the combobox's drop down list.
  • The next element has a listbox role and represents the drop down list. It manages keyboard navigation among list items and navigating back to the text field if necessary.
  • Each item in the listbox is an option. Options are not in the tab order.
  • Provide a label for the combobox by referencing the text field in the combobox. You can use an aria-label to associate this label with the combobox or you may use the HTML <label> element and its for attribute to reference the text field.

For each combobox pattern the button need not be in the tab order if there is an appropriate keystroke associated with the input element such that when focus is on the input, the keystroke triggers display of the associated drop down list. In this case, a Tab to focus the button is unnecessary. This is the same behavior as the select element.

Example:

First design pattern -- container element with role combobox :

Second pattern -- text field with role combobox :


Date Picker (widget)

Characteristics:
Description: The DatePicker widget allows the user to select a date or date ranges. The DatePicker shows one month at least. All navigation that is described below depends on the application. If no range selection is possible, the relevant keystroke interaction can be ignored. Also navigation to the past might be optional. Each week might be labeled with the corresponding calendar week number.

As a general rule the actual calendar portion of the date picker follows a table structure where days of the week and calendar day numbers are layed out in table cells. This provides context so an assistive technology can render the day of the week; its corresponding numeric calendar day, and week number if necessary. Consequently, it is best to start with an HTML table and apply WAI-ARIA semantics for a grid. However, should the author wish to uses a div or span to represent the cells then the DOM structure for a table is duplicated with rows marked with role="row."

The calendar portion can be displayed in a numbers of ways, including as a popup associated with another widget, or as a static region of a page.

Keyboard Interaction:

Keyboard navigation on days that are not included the currently displayed month should move to the month automatically and lead to the day in the next or previous month.

  • Tab - Like other widgets, the date picker widget receives focus by tabbing into it. Once focus is received, focus is repositioned on today's date in a grid of days and weeks. A second tab will take the user out of the date picker widget. Focus initially is placed on today's date.
  • Shift+Tab - reverses the direction of the tab order. Once in the widget, a Shift+Tab will take the user to the previous focusable element in the tab order.
  • Up Arrow and Down Arrow - goes to the same day of the week in the previous or next week respectively. If the user advances past the end of the month they continue into the next or previous month as appropriate.
  • Left Arrow and Right Arrow - advances one day to the next, also in a continuum. Visually focus is moved from day to day and wraps from row to row in a grid of days and weeks.
  • Control+Page Up - Moves to the same date in the previous year.
  • Control+Page Down - Moves to the same date in the next year.
  • Space -
    • Singleton Mode: acts as a toggle either selecting or deselecting the date.
    • Contiguous Mode: Similar to selecting a range of text. Space selects the first date. Shift+Arrows add to the selection. Pressing Space again deselects the previous selections and selects the current focused date.
  • Home - Moves to the first day of the current month.
  • End - Moves to the last day of the current month.
  • Page Up - Moves to the same date in the previous month.
  • Page Down - Moves to the same date in the next month.
  • Enter -
    • If the the calendar is a popup attached to some other widget (e.g., a text field), then Enter dismisses the popup, and the selected date(s) are shown in the associated widget.
    • If the calendar is a static region on the page, then Enter confirms the selected date(s).
  • Escape - in the case of a popup date picker, closes the widget without any action.

Navigation into the past is optional

Do not implement keyboard navigation schemes that would place more than one calendar day in the tab order at any time as this impacts the usability of keyboard navigation. For example, using HTML anchors for the gridcells places them all in the tab order impacting the usability of keyboard navigation.

WAI-ARIA Roles, States, and Properties:
  • The current month has a label representing the month and year. It is advisable to use a role heading but is not essential. This "label" should have a unique ID.
  • If the author would like to ensure that a label is announced by a screen reader, as the label changes, include live region properties with the label element: aria-live="assertive" and aria-atomic="true".
  • The container for the day of week headers and numeric days of the week has a role of grid.
  • The grid has an aria-labelledby property with a value equivalent to the id of the label for the grid.
  • Each name for the day of the week has a role columnheader and is not navigable via the keyboard.
  • Each numeric day of the week has the role gridcell.
  • When a day is selected its aria-selected is set to true, otherwise it is set to false or removed.
  • Changes in aria states, identified here, as well as focus, are clearly styled to show the user where their point of regard is and what days are selected.

When the datepicker is active a calender day of the week always has focus. This can be achieved by setting the tabindex on that day as appropriate and then using script to give it focus. Alternatively, the grid container could set aria-activedescendant to the id of the currently focused gridcell. Keep in mind that older browsers may not support aria-activedescendant.

Example:

Dialog (Modal) (widget)

Characteristics:
Description:

A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response (dialog). A modal dialog is a dialog that takes and holds focus until the dialog is closed or submitted. A specific kind of modal dialog is the alertdialog, that is used to convey a short message to the user. See the "Alert Dialog" design pattern.

Keyboard Interaction:

Keyboard navigation within a modal dialog includes these aspects:

  • Enter If the purpose of the dialog is to gather information, the dialog should have a mechanism to submit the data gathered usually via a keyboard accessible button. The Enter key should serve as the default submit action.
  • Escape There should be a method to close the dialog without taking any action. This could be implemented via a cancel button which is keyboard accessible. It is recommended that a dialog also be cancelled by pressing the Escape key with focus on any item.
  • Tab Focus must be held within the dialog until it is cancelled or submitted. As the user presses tab to move within items in the dialog, pressing tab with focus on the last focusable item in the dialog will move focus back to the first focusable item in the dialog.
  • Shift+Tab Likewise, if the user is shift-tabbing through elements in the dialog, pressing shift-tab with focus on the first focusable item in the dialog will move focus to the last item in the dialog.

Notes:

  • If the current focus item has Escape key behavior, the press of the Escape will be handled by the current item and the user may have to press Escape an additional time to close the dialog.
  • Even if the user clicks outside of the dialog on the application which invoked the dialog, focus remains in the dialog.
  • Because the dialog is modal and the user can not interact with the invoking application while the dialog is displayed, there is no requirement to make the dialog moveable via the mouse although this behavior is recommended.
  • When the dialog is closed or cancelled focus should return to the element in the application which had focus before the dialog is invoked. This is usually the control which opened the dialog.
  • When a modal dialog opens focus goes to the first focusable item in the dialog. Determining the first focusable item must take into account elements which receive focus by default (form fields and links) as well as items which may have a tabindex attribute with a positive value. If there is no focusable item in the dialog, focus is placed on the dialog container element.
  • Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. Authors should ensure that Enter activates only the widget they intend.
WAI-ARIA Roles, States, and Properties:
  • Generally, a modal dialog has a role of dialog.
  • If it is a simple dialog with a message that alerts, warns, or requests confirmation (e.g., "Are you sure you want quit?"), then authors are advised to use the alertdialog role. See the "Alert Dialog" design pattern for more information.
  • The dialog box title is provided by either the aria-label or the aria-labelledby property.
Example:

Dialog (Non-Modal) (widget)

Characteristics:
Description:

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

A non-modal dialog is one which is displayed and focusable at the same time as the application which invoked it. Also like the modal dialog, focus via the tab and shift-tab key must be maintained within the dialog. However, a non-modal dialog should have a keyboard mechanism to return focus to the application while leaving the dialog open.

Keyboard Interaction:
  • Escape cancels the dialog without taking any action
  • Enter submits any data gathered in the dialog.
  • F6 is the recommended key to move focus between the application and an open non-model dialog.

Notes:

  • The mouse user may click on either the application or the dialog to change focus between the two.
  • In a Web application the non-modal dialog is usually always displayed above the application page, rather than in a separate browser window but that is not a requirement.
  • This dialog box is dragable by the mouse user and an equivalent behavior (Drag & Drop) should be offered to the keyboard only user.
  • Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. Authors should ensure that Enter activates only the widget they intend.
WAI-ARIA Roles, States, and Properties:

See Dialog (Modal).

Example:

Experimental dojo floating non-modal pane


Dialog (Tooltip) (widget)

Characteristics:
Description:

A tooltip dialog is a modal dialog that is rendered near the invoking element and visually connected via a cartoon bubble-like protrusion. It is displayed when the mouse passes over or rests on that element.

Keyboard Interaction:
  • Escape The tooltip dialog is closed by pressing the escape key when focus is within the dialog, mouse clicking on a close icon, or mouse clicking outside of the dialog onto the application.
  • Tab Focus must be held within the dialog until it is cancelled or submitted. As the user presses tab to move within items in the dialog, pressing tab with focus on the last focusable item in the dialog will move focus back to the first focusable item in the dialog.
  • Shift+Tab Likewise, if the user is shift-tabbing through elements in the dialog, pressing shift-tab with focus on the first focusable item in the dialog will move focus to the last item in the dialog.

Note: It is modal because focus is trapped within the dialog as the user navigates via the Tab and Shift+Tab key.

Note: Unlike a true modal dialog, the user can click outside of the dialog, however in that case the tooltip dialog is immediately closed.

Note: A tooltip dialog can not be moved/dragged.

Note: Other than the close and move behavior, all other behaviors of a modal dialog are implemented by the tooltip dialog.

WAI-ARIA Roles, States, and Properties:

See Dialog (Modal).

Example:

Dojo nightly


Drag & Drop

Characteristics:
Description: A drag and drop operation can occur in contexts that support selection of objects, including single and multiple selection models. An example is a tree view. The tree is a container of objects that are potentially draggable.
Keyboard Interaction:

See Drag and Drop Support, above.

WAI-ARIA Roles, States, and Properties:
  • Draggable objects are identified using the aria-grabbed state.
    • If the aria-grabbed state is absent, or if it has the value undefined, then the object cannot partake in a drag and drop operation.
    • If aria-grabbed is false, the object is draggable, but currently not being dragged.
    • If aria-grabbed is true, the object is both draggable and currently being dragged.
  • Other objects are potential drop targets. Drop targets are identified using the aria-dropeffect property.

See Drag and Drop Support for more detail.

Example:

Grid (Simple Data Tables) (widget)

Characteristics:
Description:

Unlike an HTML table, which is display only, a grid presents tabular data in rows and columns that are navigable via the keyboard, and allows for cells to be selected in the grid. The user moves focus through each data cell having a role of gridcell, through the use of arrow keys. Each column has an associated element with the role columnheader. Data cells carry the role gridcell. A grid may also contain hierarchical rows. In this case the role of the grid container should be treegrid rather than grid. This design pattern, and corresponding examples, reflect a basic two-dimensional grid without grids embedded within a gridcell.

WAI-ARIA grids are not meant to replace the full functionality of a table. Consequently, there may be instances when you need to have cells span multiple columns or rows for which WAI-ARIA does not provide semantics. This can be achieved by overlaying grid and gridcell semantics onto an HTML table to provide appropriate column and row span semantics. Authors should ensure that headers are properly marked using a native header tag or WAI-ARIA columnheader or rowheader semantics. The connection between gridcell and header can be achieved using standard HTML attribute header. In HTML, multiple column or row headers for one data cell can be identified through the use of a space separated list of header ids in the headers attribute.

If a WAI-ARIA grid is not overlayed on a table, authors should mark the rowheader, columnheader, and gridcell roles on the appropriate elements. For gridcells that span multiple columns or have multiple headers, the author should apply the aria-labelledby property to the cell to the space delimited list of corresponding row or column header element IDs. Gridcells that span multiple rows or columns should be reflected in the keyboard navigation.

If a grid contains editable data, it should have both an editable mode and a navigation mode.

Keyboard Interaction:

There are two modes of keyboard interaction, namely, navigation mode and actionable mode.

Navigation Mode (Read-Only) is the default mode, and allows quick and intuitive navigation around the grid.

  • The first Tab into the grid moves focus to the first cell of the first row.
  • The second Tab leaves the grid and moves focus to the next tabbable item on the page.
  • Subsequent Tab: Once focus has been moved inside the grid, subsequent tab presses that re-enter the grid shall return focus to the cell that last held focus.
  • Right/Left arrow keys navigate through the columns. There is no wrap at the end or beginning of columns.
  • Up/Down arrow keys navigate through the rows. There is no wrap at the first or last rows.
  • Home moves the focus to the first cell of the current row.
  • End moves the focus to the last cell in the current row.
  • Page Up moves the focus to the first cell in the current column
  • Page Down moves the focus to the last cell in the current column
  • Selecting Cells
    • Control+Space selects the current column.
    • Shift+Space selects the current row.
    • Control+A selects the entire grid.
    • Shift+Arrow selects contiguous cells.
    • Shift+F8 Allows additional cells to be added to a previous selection to accomplish non-contiguous selection.

    See Global Recommendations for information on cut, copy and paste.

  • Enter or F2 pressed while focus is on a cell containing an actionable item enters Actionable Mode (see following).
  • Optionally, alphanumeric keys pressed while focus is on an actionable item enters Actionable Mode. Focus remains on the actionable item that has focus.

Actionable Mode (Interactive) allows interaction with other objects that might be found in the grid cells such as edit fields, links, menu buttons, and so on.

  • Tab moves to the next actionable item in the grid and stays within the grid wrapping at the bottom. In this mode each tabbable object in each cell of the grid can be reached with the Tab key. If multiple tabbable items are located inside a single grid cell, Tab stops at each one. When the last tabbable item in a cell is reached the next Tab moves to the next tabbable item in the grid, wrapping at the last tabbable item in the grid.
  • Shift+Tab moves to the previous actionable (tabbable) item in the grid and stays within the grid, wrapping at the top.
  • Escape exits Actionable mode (by which the user may enter text or perform an action to complete a operation) and returns to Navigation Mode (where the user is allowed to move focus among elements). If a widget is in the current grid cell that also uses the Escape key, then it should cancel the event propagation. A subsequent press of the Escape key returns focus to the parent widget.

Option: the author may choose to enable 'auto action' on a cell in order to avoid having to press Enter or F2 a second time to activate the default behavior of the object contained in a cell. For example, if the cell contains a single link the author may want to have enter follow the link rather than just move focus to it. This auto action mode should be configurable on a per cell basis as its utility is dependent on each cell's content. For example, if the cell contains multiple links, auto action should be disabled as its behavior would be ambiguous.

Option: the author may choose to implement Enter or F2 as a toggle such that pressing these keys multiple times will enter and exit actionable mode. Opinion was divided on this point. Some thought this would be confusing while others found it intuitive.

It is recommended the developer use different styling for the selection when the grid is not focused (hint: non-active selection is often shown with a lighter background color).

WAI-ARIA Roles, States, and Properties:
  • The DOM representation of the grid should follow the HTML DOM structure, although it will be possible to use aria-owns to add a row or table cell. This is an edge case and may not be supported by assistive technologies.
  • The grid container should have a role of grid.
  • The data cells should have a role of gridcell.
  • Each row should be clearly marked using a <TR> from HTML and by using a role of row.
  • Column and row headers may be represented by a <TH> if you are using an HTML table or you may explicitly use an aria role of columnheader and rowheader respectively.
  • Whenever a gridcell is selected, set aria-selected="true".
  • Whenever a row is selected, set its role to row and its aria-selected="true" allowing an AT to quickly determine that the entire row is selected.
  • By default a grid is considered to be editable, meaning all gridcells are editable. Should you want to make a grid read-only, set aria-readonly="true" on the document element having a role="grid". This will make all grid cells read-only. To override the read-only status on an individual grid cell, set its aria-readonly property to false.
Example:

Actionable, Sortable Column Header in a Grid (widget)

Characteristics:
Description:

An example of a grid whose headers are sortable in either ascending or descending order based on the name in the grid column headers.

This design pattern matches that of the grid design pattern where, specifically, the author has included use of the arrow keys to permit navigation to the row or column headers that contain a button for sorting the rows of the table. Sorting is based on the data cell contents in the column being sorted, the name in the column header, and whether the contents of the column are sorted in ascending or descending order. As the order of the cells change in the column the corresponding rows move in position with respect to that sort.

Keyboard Interaction:

Keyboard navigation is identical to grid with the exceptions that: arrow key navigation includes the headers; you are not required to enter actionable mode to toggle the sort of a row or column when on the corresponding header; and content selection does not affect the selected state of row or column headers.

Simply pressing the space bar while focus is on a row or column header toggles the ascending/descending sort of the corresponding row or column.

It is recommended the developer use different styling for the selection when the grid is not focused (hint: non-active selection is often shown with a lighter background color).

WAI-ARIA Roles, States, and Properties:
  • The same as the grid design pattern with the exception that each row or column header, signified by a role of columnheader and rowheader respectively, has an aria-sort value that reflects the current state for sort for the associated row or column. If another row or column header adjusts the sort of the grid the remaining row or column header aria-sort values must reflect their sorting impact on the grid.
Example:

Landmark Navigation (widget)

Characteristics:
Description:  
Keyboard Interaction:

 

WAI-ARIA Roles, States, and Properties:

Provide the appropriate landmark for the role attribute. See the section describing landmark use.

Example:


Listbox (widget)

Characteristics:
Description: A widget that allows the user to select one or more items from a list of choices. (listbox).
Keyboard Interaction:
  • Tab: When a list is tabbed to, select the first item if nothing else is already selected. A second tab will take the user out of the widget to the next tab stop on the page.
  • Up/down arrows navigate up and down the list.
  • Shift+Up Arrow and Shift+Down Arrow move and extend the selection.
  • Typing letter or several letters to navigate (same letter goes to each item starting with that, different letters go to first item starting with that entire string).
  • Shift+F10: If the current item has an associated context menu, then this key combination will launch that menu.
  • Selection
    • Checkbox - Space toggles checkboxes, if the list items are checkable
    • Selectable List Items
      • Space acts as a toggle to select and deselect the current item. If previous items have been selected, it also deselects them and selects the current item.
      • Shift+Space selects contiguous items from the last selected item to the current item.
      • Control+Arrow moves without selecting.
      • Control+Space toggles selection of non-contiguous items, adding or removing the current item from the set of selected items.
      • Control+A - It is recommended a checkbox, link or other method be used to select all. The Control+A key could be used to provide the shortcut key.

It is recommended the developer use different styling for the selection when the list is not focused (hint: non-active selection is often shown with a lighter background color).

WAI-ARIA Roles, States, and Properties:
  • The listbox container has a role of listbox.
  • Each entry in the listbox should have a role option and should be DOM children of listbox.
  • If is not a DOM child of listbox, then it should be referenced in the listbox by aria-owns.
  • If all items in the listbox are not DOM children of the listbox, then set their aria-setsize and aria-posinset accordingly; otherwise, this information cannot be computed for context by the user agent.
  • If the listbox is not part of another widget, then it should have a visible aria-label referenced on the listbox by
    aria-labelledby.
  • Each selected list item should have aria-selected="true".
Example:

Media Player (widget)

Characteristics:
Description:  
Keyboard Interaction:

 

WAI-ARIA Roles, States, and Properties:  
Example:  



Popup Menu (widget)

Characteristics:
Description:

A popup menu is otherwise known as a Context Menu. Unlike a menu in a menubar or a menu button, a popup menu has no visible trigger widget. The popup menu is typically invoked, using the mouse, with a right-click on empty space. The items in the menu depend on where the right-click occurred, or, the context in which the menu was invoked. An example is clicking on white space on a web page. A menu appears with items applicable to the page, such as "Back", "Forward", "Reload", "Bookmark This Page", and so on. Clicking right in a different context, such as an empty spot on the desktop, will invoke a different menu, one that is appropriate to desktop operations, such as "New Folder".

When presenting the popup, ensure that it is completely visible on screen.

Keyboard Interaction:

The keyboard navigation for this widget was designed to work for both the popup and menubar menu widgets. The goal was to present a desktop paradigm for posting and dismissing menu widgets.

  • Shift F10
    • Posts the Popup Menu Widget When it is used as a Context Menu.
    • Place input focus on the first available menuitem in the Popup Menu.
    • The Browser's Context Menu pops up if the element with input focus does not have a Popup Menu attached.
    • Experiment indicated that Javascript is able to re-purpose to post the widget's popup menu instead of the browser's.
    • Shift F10 is used by IE to "Display a shortcut menu for a link". In IE7 and IE8 event.cancelBubble=true; and event.returnValue=false; will allow the re-purposing of keys used by the browser. In the case of IE6, you can not stop the bubble up of keys used by the browser, but can stop the bubble up to the OS. In the case of Firefox and other standard compliant browsers, event.stopPropagation(); and event.preventDefault(); will re-purpose the keys.
  • ESC
    • Causes no menu action and dismisses Popup Menu.
    • Input focus is returned to the element from which the Popup Menu was called.
  • Up and Down Arrow
    • Moves input focus vertically between each menuitem.
    • Input focus wraps from the last to the first menuitem on a Down key press and vice-versa when the Up key is pressed.
  • Right and Left Arrow
    • Where applicable, causes a sub-menu to post or un-post.
    • Causes no action if there is no sub-menu.
  • Enter
    • What occurs when Enter is pressed depends on the state the menu is in:
      • Posts the Popup Menu if input focus is on the element, or widget it is attached to, e.g., a menubutton, link, etc.:
        • Input focus is placed on the first menuitem when the menu pops up.
      • Dismisses the menu when input focus is on an active menuitem.
      • Nothing occurs if input focus is on a menuitem marked as disabled.
  • Page Down
    • Moves input focus to the first menuitem on the next view of the menu.
    • Moves input focus to the last menuitem on menus that display all their content in one view.
  • Page Up
    • Moves input focus to the last menuitem on the previous view of the menu.
    • Moves input focus to the first menuitem on menus that display all their content in one view.
  • Tab
    • One of the following occurs:
      • Moves input focus between elements in the Popup Menu's tabbing order.
        • Input focus stays in the Popup Menu until one of the following occurs:
          • ESC is pressed.
          • Enter is pressed when input focus is on an interactive widget/element.
  • Typing a letter (printable character) key moves focus to the next instance of a visible node whose title begins with that printable letter.
WAI-ARIA Roles, States, and Properties:

See the Menu design pattern for information about the WAI-ARIA roles, states, and properties of the popup menu.

In all cases where there is no visual cue in the context that a popup menu is supported it is unnecessary to add an aria-haspopup property.

Example:
  • Dojo nightly build:
    • Mouse: right click on the page.
    • Keyboard: Control+Space (Mac), or Shift+F10 (Windows).

Popup Help (aka Bubble Help) (widget)

Characteristics:
Description:

Popup Help contains more descriptive, or actionable, help-like text and elements. It may contain, and was designed to handle, interactive elements such as a button, link, or text field. It is essentially a Popup Menu with un-necessary keystrokes turned off. The key sequence for posting Popup Help was to take advantage of F1's tie to the Help paradigm (F1 calls up application Help for example).

Keyboard Interaction:
  • Control+F1
    • Posts the Popup Help widget.
    • Input focus is placed on the first interactive element in the Popup Help.
    • Control F1 is used by IE to "Display a help dialog box". In IE7 and IE8 event.cancelBubble=true; and event.returnValue=false; will allow the re-purposing of keys used by the browser. In the case of IE6, you can not stop the bubble up of keys used by the browser, but can stop the bubble up to the OS. In the case of Firefox and other standard compliant browsers, event.stopPropagation(); and event.preventDefault(); will re-purpose the keys.
    • With the exception of Control F1 to bring up Popup Help this widget is very similar to Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip) described elsewhere in this document.
  • Esc
    • Causes no menu action and dismisses Popup Help.
    • Input focus is returned to the element, or widget the Popup Help was invoked from.
    • Pressing Enter when input focus is on the "X" glyph acts the same as pressing Esc.
  • Tab
    • One of the following occurs:
      • Modal behavior
        • Moves input focus between elements in the Popup Help's tabbing order.
          • Input focus stays in the Popup Help until one of the following occurs:
            • Esc is pressed.
            • Enter is pressed when input focus is on an interactive widget/element.
      • Non-Modal behavior
        • Moves input focus to the next tab-able element in the tabbing order if the following applies:
          • Popup Help is posted.
          • It contains no tab navigable elements in it.
  • Shift+Tab
    • As with other keyboard conventions described here, the Shift+Tab has the effect of moving the focus up rather than down and follows the same conventions as described for the modal and non-modal Tab key above.
  • Enter
    • Activates the element in the Popup Help that has input focus, if applicable, then dismisses the popup.
      • Input focus should be placed on the appropriate element after the user presses the Enter key.
        • The appropriate place to move input focus to will not always be the parent element the Popup Help was invoked from.
      • Nothing occurs if input focus is on an element that has no associated action.
  • F6
    • In the non-modal instance, the F6 key can be used to move focus between the application and the open non-modal window. This is also the behavior described in Dialog (Non-Modal) above.
WAI-ARIA Roles, States, and Properties:

See Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip).

Example:  

Radio Button (widget)

Characteristics:
Description: An option in single-select list
Keyboard Interaction:
  • Tab key will enter the radio group.
    • When Tab or Shift+Tab into a radio group, focus goes to the selected radio button. If none is selected, focus goes to the first radio button if Tab was pressed, or the last radio bottom if Shift+Tab was pressed.
    • When focus is on any radio button, Tab or Shift+Tab will exit the radio group.
  • Up Arrow and Left Arrow moves focus to the previous radio button in the group, and selects that button. If focus is on the first item, then focus wraps to last item.
  • Down Arrow and Right Arrow moves focus to the next radio button in the group, and selects that button. If focus is on the last item, then focus wraps to first item.
  • Control+Arrow moves through the options without updating content or selecting the button.
  • Space selects the radio button with focus and de-selects other radio buttons in the group.
WAI-ARIA Roles, States, and Properties:
  • Use a container with a role radiogroup for the set of radio buttons.
  • An individual radio button has a role of radio.
  • If selected, the radio button has the state aria-checked="true".
  • If not selected, it has the state aria-checked="false".
  • If an image is used to render the state of a radio button, the image element does not appear in the accessibility API mapping. This is accomplished using CSS to render the image as a background image, or by setting role="presentation" on the image.
  • It is recommended that the radiogroup has a label that is visible and referenced using the aria-labelledby property.
  • Use an aria-describedby property to add additional information to the radio buttons or radiogroup.
Example:

Rich Text Editor (widget)

Characteristics:
Description: Input control that accepts free-form text as its value.
Keyboard Interaction:
  • The edit control is provided by the browser; it provides the keyboard support for navigating, adding, removing and selecting text, so that behavior is not defined by the rich internet application.
  • The browser should also provide a keyboard mechanism for navigating into and out of the edit control. Within most browsers the edit control is put into the tab order of the page and can be navigated into, out of, and through using the tab and shift-tab keys like any standard form control.
  • A rich text editor widget needs to provide a user interface for interacting with the browser provided edit control. Interaction between the user interface and editor is defined here assuming that a toolbar is used.
  • Tab and Shift+Tab - If not provided by the browser, the rich text editor widget provides a keyboard mechanism to move into and out of the edit control. Tab and shift-tab are the recommended keystrokes. The toolbar or other user interface component associated with the editor is placed in the tab order immediately before the editor. To set an attribute on text within the edit control the user sets focus into the edit control, moves the insertion point, selects text and presses shift-tab to move focus from the editor back to the toolbar. The user navigates through the toolbar (see toolbar behavior) to a desired attribute and invokes that attribute. When an attribute is invoked, that attribute is applied to the selected text in the editor and focus moves back into the editor at the previous insertion point with the selection intact.
  • Options:
    • Rather than using Shift+Tab to move focus from within the editor to the toolbar, another key combination could be used (Alt+Up arrow, Control+Shift+Letter, etc.). This would eliminate the need to put the user interface control (in this example a toolbar) into the tab order immediately before the editor component. However, there are drawbacks to using a different keystroke to navigate to the user interface:
      1. It is not as "discoverable" as relying on the standard Tab/Shift+Tab behavior;
      2. It is difficult to find key combinations which are not already captured by the browser or assistive technology.
      3. Focus could stay within the toolbar after the user invokes an attribute. The user would then have to press an additional key to move focus back into the editor. This would allow multiple attributes to be set on the current selection without having to return back to the user interface but it would add an extra key sequence after setting just a single attribute. Requiring a keystroke to move focus back into the editor would also require modifying the toolbar behavior to intercept this keystroke and to know how to set focus back to the component (the editor) that the toolbar is associated with.

Optionally, if the developer wishes to provide the ability to insert a tab into the document, it is recommended one of the following methods be used.

  • Provide indent and outdent buttons in the menu. Keyboard shortcuts to the buttons should be Control+M for indent and Control+Shift+M for outdent.
  • Provide a button in the menu to toggle the use of Tab between the two modes. If this button is used, then Control+M is recommended as a keyboard shortcut to toggle the button.

 

WAI-ARIA Roles, States, and Properties:

Authors are advised to not use ARIA for rich text editors, but to rely on native HTML markup. Current rich text editors typically use an iframe element for editable content. As a result, the editable content is implicitly mapped to a document role in accessibility APIs. If using HTML5, it is recommended that authors use the designMode or contentEditable attributes.

Example:




Slider (widget)

Characteristics:
Description: A slider is user input where the user selects a value from within a given range. Sliders typically have a button such that when moved will change the current value within the current range of the slider. The button must be keyboard accessible. It is typically possible to add or subtract to the current value by using directional keys such as arrow keys.
Keyboard Interaction:
  • Right Arrow and Up Arrow increase the value of the slider.
  • Left Arrow and Down Arrow decrease the value of the slider.
  • Home and End move to the minimum and maximum values of the slider.
  • Tab into and out of the slider.
  • Page Up and Page Down optionally increment or decrement the slider by a given amount.

Focus is placed on the slider. (The visual object that the mouse user would move, also known as the thumb.)

Localization for right to left languages may wish to reverse the left and right arrows.

WAI-ARIA Roles, States, and Properties:
  • The slider control has the role slider.
  • Sliders support the aria-valuemin, aria-valuemax, and aria-valuenow properties representing the minimum possible value of the slider, the maximum possible value, and the current value. All of these are decimal numbers. The minimum and maximum are typically fixed and do not change.
  • Sometimes the value is not user readable, such as a number for the day of the week, e.g., "1". In those cases, use the aria-valuetext property to provide a human readable string for the slider's value, e.g. "Monday".
  • It is recommended that authors provide a visible label for the slider, referencing it using aria-labelledby.
Example:

Please note that not all examples work in all browser and version combinations. For example, note the compatibility statement.


Slider (Multi-Thumb) (widget)

Characteristics:
Description: A multi-thumb slider is a slider with multiple user inputs designed to change the maximum and minimum range for an object it controls.
Keyboard Interaction:

This range slider allows author to modify the maximum and minimum range of an object within an applications. Moving the thumb on either end allows the author to modify the corresponding maximum or minimum value of what it is controlling.

  • Tab to the first slider thumb.
  • Second Tab moves to next slider thumb..
  • Third Tab moves to the next slider thumb or if there are no more, it moves to the next tab stop on the page.
  • Shift+Tab moves backwards through the tabs.
  • With focus on a thumb: Same as Slider above.
    • Right Arrow and Up Arrow increase the value of the slider constrained by the value of the other thumb.
    • Left Arrow and Down Arrow decrease the value of the slider constrained by the value of the other thumb.
    • Home and End move to the minimum and maximum values of the slider constrained by the value of the other thumb.
    • Page Up and Page Down optionally increment or decrement the slider by a given amount, constrained by the value of the other thumb.

Focus is placed on one of the thumbs of the slider.

All thumbs are in the tab order.

Localization for right to left languages may wish to reverse the left and right arrows.

If the current value of a slider crosses over one of the other sliders, the tab order remains the same. Example. If a high range slider is moved so that its current value is below the current value of a low range slider, the thumb will visually appear to be before the low range slider. This should not change the tab order of the slider.

WAI-ARIA Roles, States, and Properties:
  • Each slider control has the role slider.
  • Each slider supports the aria-valuemin, aria-valuemax, and aria-valuenow properties representing the minimum possible value of the slider, the maximum possible value, and the current value. All of these are decimal numbers. The maximum of the lower slider limits the minimum of the upper slider and vice versa.
  • Sometimes the value is not user readable, such as a number for the day of the week, e.g., "1". In those cases, use the aria-valuetext property to provide a human readable string for the slider's value, e.g. "Monday".
  • Each slider thumb defines an aria-controls relationship between it and the minimum/maximum it controls.
  • It is recommended that authors provide a visible label for the multi-thumb slider, referencing it using aria-labelledby.
  • If the multi-thumb slider controls a live region, then add an aria-controls between each thumb (upper and lower), and the live region they control.
Example:

Spinbutton (widget)

Characteristics:
Description:

A widget that allows users to select from a range of values. A spinbutton typically provides the use of an up and down button on the keyboard. Visibly, the value is incremented or decremented until a maximum or minimum value is reached. A spinbutton usually includes a text field to display the current value and allow users to edit the value directly.

Keyboard Interaction:

The associated text field generally supports standard text entry operations such as selection of characters, deletions, insertions, and caret movement using the Right Arrow and Left Arrow keys. The exception is when the spinbutton's value space is restricted and the associated script limits the characters. For example, an hour-and-minute spinner would allow only the digits 1-59, the colon ':', and the characters 'AM' and 'PM'. If the user typed any other character, it would not change the contents of the text field nor the value of the spinbutton.

  • Up Arrow increases the value.
  • Down Arrow decreases the value.
  • Home and End key move to the maximum or minimum values.
  • Optional: Page Up and Page Down increase or decrease the value in larger steps.
  • Tab key moves into and out of the widget.

Focus should remain on the edit field

Localization for right to left languages may wish to reverse the left and right arrows.

WAI-ARIA Roles, States, and Properties:
  • The widget has the role spinbutton.
  • Spinbuttons support the aria-valuemin, aria-valuemax, and aria-valuenow properties representing the minimum possible value of the spinner, the maximum possible value, and the current value. All of these are decimal numbers. The minimum and maximum are typically fixed.
  • Sometimes the value is not user readable, such as a number for the day of the week, e.g., "1". In those cases, use the aria-valuetext property to provide a human readable string for the slider's value, e.g. "Monday".
Example:

Tab Panel (widget)

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 the corresponding tab panel 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
  • Control+Up Arrow - with focus anywhere within the tab panel, pressing Control+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 Control+PageUp/Control+PageDown in Firefox to switch tabs?
  • Alt+Delete - When deletion is allowed, with focus anywhere within the tab panel, pressing Alt+Delete 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
  • Control+PageUp - When focus is inside of a tab panel, pressing Control+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 Control+PageUp will move focus to the last tab in the tab list and activate that tab.
  • Control+PageDown When focus is inside of a tab panel, pressing Control+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 Control+PageUpwill move focus to the first tab in the tab list and activate that tab.

Regarding Control+PageUp/Control+PageDown. This is currently implemented in Firefox to move between browser tabs. Firefox also supports Control+Tab and Control+Shift+Tab to move between tabs. Internet Explorer 7 also uses Control+Tab and Control+Shift+Tab. There may be advantages to using Control+PageUp/Control+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 Control+PageUp/Control+PageDown keypress (and thus letting the browser access it) when the first or last tab was reached.

WAI-ARIA Roles, States, and Properties:
  • The tabbed interface component contains tabs and their associated content panels.
  • The content panel uses the role tabpanel.
  • An element with role tab is used as a grouping label, providing a link for selecting the tabpanel to be rendered to the user.
  • Assign the aria-controls relationship of a tab to the ID of its tabpanel.
  • Authors manage the selected state of each tab by maintaining its aria-selected state.
  • A tablist is the container role for a set of elements with the role attribute set to tab.
Example:

Tool Bar (widget)

Characteristics:
Description:

A toolbar is a flat non-hierarchical collection of controls that provides quick access to a subset of the functions found in the menubar/menu hierarchy. Its purpose is to reduce effort in using these functions. There should neither be too few nor too many controls within a toolbar. When creating toolbars try to limit the number of items to approximately seven, as forcing users to navigate through an excessive number of items is a usability concern. Since navigation between toolbars is accomplished using a Tab keystroke, too few controls within a toolbar also creates a usability issue as it requires numerous Tab keystrokes to navigate between toolbars.

Authors must supply an aria-label property on each toolbar when their application contains more than one toolbar. The label provides information about the purpose of each toolbar; for example, an "Edit" toolbar that contains cut, copy, paste, clear, undo, and redo controls. If the application has many toolbars, it is recommended that they be placed inside a container element with a role of group to allow for keyboard navigation to the entire collection of toolbars. It is recommended that authors provide a documented key combination that allows a user to move focus quickly to the tool bar from elsewhere within the web application, placing keyboard focus on a tool within the tool bar.

It is further recommended that authors provide access to these functions via a menubar and menus to avoid cluttering the user interface with a surplus of toolbars.

Keyboard Interaction:
  • Tab moves focus to the first enabled toolbar button.
  • A subsequent Tab moves focus out of the toolbar
  • Left Arrow and Right Arrow keys navigate to the enabled buttons in the toolbar

Direction may need to be adjusted for Right to Left languages

Recommended: provide a documented keystroke that allows users to move focus quickly to the tool bar from elsewhere within the web application, placing focus on a tool within the tool bar.

There is debate concerning the treatment of disabled toolbar buttons -- should they be focusable or not? Visually, disabled buttons are grayed-out, and typicially not placed in the navigation order. This invites an issue about how a screen reader user discovers these buttons if they are not keyboard navigable. Several ways of handling this include:

  • In software applications like Microsoft® Word, the toolbars themselves are not reachable by the keyboard user, but the features are available on one of the drop-down menus.
  • Users set a preference indicating whether they want disabled buttons focusable.
  • Disabled buttons are not focusable until they are enabled. This is the way tool bars currently work.
  • Disabled buttons are focusable, but read by the screen reader as disabled.
WAI-ARIA Roles, States, and Properties:
  • The element has the role toolbar.
  • The children of the toolbar are frequently elements with role button.
  • Other tools that are common within toolbars are comboboxes and pull-down menus.
  • It is recommended that a toolbar is labelled using aria-label.
Example:

Tooltip Widget (widget)

Characteristics:
Description: Popup that displays a description for an element when a user passes over or rests on that element. Supplement to the normal tooltip processing of the user agent. It should popup automatically when the user gives input focus to the widget or element with which it is associated. The tooltip widget can be dismissed by pressing the Escape key or by other methods noted below. The tooltip widget differs from the Dialog (Tooltip) in that it does not receive focus at any time.
Keyboard Interaction:

Escape: Dismisses the Tooltip.

Note: The trigger element to which the tooltip is attached, e.g., a link, should never actually lose input focus.

Note: If the tooltip is invoked when the trigger element gets focus, then it should be dismissed when it no longer has focus (onBlur). If the tooltip is invoked with mouseIn, then it should be dismissed with a mouseOut.

Note: If more then one widget uses the same keys, e.g., Escape, then they should be handled in a Last In First Out (LIFO) manner. For example, an editable grid contains gridcells which contain date fields. The user invokes Actionable mode on the grid and then interacts with the Date Field to invoke the Date Picker. At this point the first press of the Escape key will close the Date Picker, the second press will exit Actionable mode and return to Navigation mode.

WAI-ARIA Roles, States, and Properties:
  • Uses the WAI-ARIA role tooltip.
  • The element that the tooltip is for references the tooltip using aria-describedby.
Example:

Tree Grid (widget)

Characteristics:
Description: A grid whose rows can be expanded and collapsed in the same manner as for a tree. A Tree Grid is a combination of a Treeview and a Table with rows that are expandable
Keyboard Interaction:

There are two modes of keyboard interaction:

  • Navigation Mode (Read-Only) is the default mode, and allows quick and intuitive navigation around the grid.
    • Tab
      • The initial tab enters the grid with focus on the first cell of the first row, often a header.
      • Once in the grid a second tab moves out of the grid to the next tab stop.
      • Once focus is established in the grid, a Tab into or a Shift+Tab into the grid will return to the cell which last had focus.
    • Left Arrow and Right Arrow keys navigate between columns. If the next cell in the row is empty, focus should not move.
    • Up Arrow and Down Arrow The down arrow moves focus to the first column of a child row, if expanded. Otherwise focus is moved to the same column in the next row. Up arrow performs the same navigation but in reverse.
    • Control+Left and Control+Right Arrows expand or collapse rows.
    • If the cell contains an editable field, the Enter key starts edit mode and the Escape key exits edit mode.
    • Selecting Cells
      • Control+Space selects the current column.
      • Shift+Space selects the current row.
      • Control+A selects the entire grid.
      • Shift+Arrow selects contiguous cells.
      • Shift+F8 Allows additional cells to be added to a previous selection to accomplish non-contiguous selection.

      See Global Recommendations for information on cut, copy and paste.

Note: The author may choose to indent child nodes visually. This should be done with an appropriate number of spacer cells marked as presentation in order to keep the headers aligned.

Note: If cells are used for padding or layout of the hierarchy, navigation to those presentational cells should be prevented.

  • Actionable Mode (Interactive) allows the interaction with other objects that might be found in the grid cells such as edit fields, links, etc.
    • F2 pressed anywhere inside the grid will enter Actionable Mode. Focus will not be moved.
    • Enter pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
    • Optionally, alphanumeric keys pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
    • Tab will move to the next actionable (tabbable) item in the grid and stay within the grid wrapping at the bottom. In this mode each tabbable object in each cell of the grid can be reached with the tab key. If multiple tabbable items are located inside a single grid cell, the tab will stop at each one. When the last tabbable item in a cell is reached the next tab will move to the next tabbable item in the grid, wrapping at the last tabbable item in the grid.
    • Shift+Tab moves to the previous actionable (tabbable) item in the grid and stays within the grid, wrapping at the top.
    • Escape exits Actionable mode (by which the user may enter text or perform an action to complete a operation) and returns to Navigation Mode (where the user is allowed to move focus among elements). If a widget is in the current grid cell that also uses the Escape key, then it should cancel the event propagation. A subsequent press of the Escape key will return focus to the parent widget.
WAI-ARIA Roles, States, and Properties:

Uses the WAI-ARIA role treegrid, and requires the child element row. By default a treegrid is considered to be editable, meaning all gridcells are editable.

  • To make a treegrid read-only, set aria-readonly="true" on the document element having a role="treegrid." This will make all gridcells read-only.
  • To override the read-only status on an individual gridcell, set its aria-readonly property to false.
Example:
  • For a visual (not accessible) example of where padding cells have been implemented see: dojo's TreeGrid example.
  • An example where padding cells have not been used (also not accessible): Oracle's Tree Grid.

Tree View (widget)

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 Arrow 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 performs the default action on end nodes.
  • 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.
  • Control+Arrow to an item with the keyboard focuses the item (but does not select it). Previous selections are maintained, provided that the Control key is not released or that some other keyboard function is not performed.
  • Control+Space with focus on an item toggles the selection of the item.
  • Shift+Up Arrow extends selection up one node.
  • Shift+Down Arrow 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.
WAI-ARIA Roles, States, and Properties: A tree view uses the WAI-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 [ARIA] specification.
Example:

Window Splitter (widget)

Characteristics:
Description: Visible separator between sections of a Window that is used to modify the size of the panes.
Keyboard Interaction:

A Window Splitter can take one of two forms, namely, fixed size and variable size.

  • Tab - Like other widgets, the tab key is used to move focus to the splitter. It should appear in the normal tab order of the page. A second tab will move focus to the next tabbable item on the page.
  • Left Arrow and Right Arrow - In the case of a vertical splitter these keys will move the splitter to the left and to the right.
  • Up Arrow and Down Arrow - In the case of a horizontal splitter these keys will move the splitter up and down.
  • End - Moves splitter to the maximum size of the region.
  • Home - Moves splitter to the minimum size of the region.
  • Enter Restore splitter to previous position (undo Home or End).
  • F6 Optionally is recommended to rotate through the window panes.
  • Control+F6 Optionally brings focus directly to the splitter. Pressing Control+F6 again would rotate forward through additional splitters located on the page.
  • Shift+Control+F6 optionally reverses the direction rotating backwards through additional splitters located on the page.

Note: Fixed size splitter simply omits implementation of the arrow keys.

Note: The group recommends unique naming of the window splitter to avoid the confusion that could be created by multiple splitters located on the same window.

Note: The group recommends that a splitter "default position restore" option be available in a context menu.

 

WAI-ARIA Roles, States, and Properties:

Uses the WAI-ARIA role separator.

  • Most window splitters are expandable and collapsible. Ensure that the splitter's aria-expanded state is updated accordingly.
  • As there may be multiple splitters, use aria-label, aria-labelledby, or the title attribute, to label text on the splitter in order that an accessible name is computed by the user agent. The assistive technology can then convey to users which window splitter they are controlling.
  • Authors should set the aria-controls attribute of the element having the separator role. Its value should be the IDs of the panes whose sizes it controls. An assistive technology can then provide navigation among the panes.
Example:

Wizard (widget)

Characteristics:
Description: A sequence of dialogs or panels guiding the user through performing a task.
Keyboard Interaction:

A Wizard can be done in several ways. Either is valid.

  • Method 1: Like a Tool Bar
  • Method 2: Controls as Default Actions
    • Escape cancels the wizard.
    • Enter invokes the "next" action; If the last page, it invokes "finish"
  • Method 3: Hot Keys
    • Control+Alt+N next, finish
    • Control+Alt+P previous
    • Escape cancel, exit without saving
    • Control+Alt+R reset current page to default settings
    • Control+Alt+S save and exit
  • Method 4: Like a Dialog

Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. Authors should ensure that Enter activates only the widget they intend.

WAI-ARIA Roles, States, and Properties:  
Example:

Dojo nightly

12. Reusable Component Libraries

Rich internet applications are complex to author. To save time, it is often faster to use existing widget libraries that implement WAI-ARIA and that have already gone through:

Some publicly available UI component libraries have already implemented WAI-ARIA. Authors can reuse such libraries to start developing accessible rich internet applications.

13. Appendices

13.1. References

This section is normative.

13.1.1. Normative References

Resources referenced normatively are considered part of this specification. Implementations of this specification MUST implement the requirements of these resources.

[ARIA]
Accessible Rich Internet Applications (WAI-ARIA) 1.0. J. Craig, M. Cooper, L. Pappas, R. Schwerdtfeger, L. Seeman, Editors, W3C Recommendation, 20 March 2014. This version of WAI-ARIA is available at http://www.w3.org/TR/2014/REC-wai-aria-20140320/. Latest version of WAI-ARIA available at http://www.w3.org/TR/wai-aria/.
[ARIA-IMPLEMENTATION]
WAI-ARIA 1.0 User Agent Implementation Guide. J. Scheuhammer, A. Snow-Weaver, M. Cooper, A. Leventhal, Editors, W3C Recommendation, 20 March 2014. This version of WAI-ARIA User Agent Implementation Guide is available at http://www.w3.org/TR/2014/REC-wai-aria-implementation-20140320/. Latest version of WAI-ARIA User Agent Implementation available at http://www.w3.org/TR/wai-aria-implementation/.

13.1.2. Informative References

Resources referenced informatively provide useful information relevant to this document, but do not comprise a part of its requirements.

[ARIA-PRACTICES]
WAI-ARIA Authoring Practices. J. Scheuhammer, M. Cooper, L. Pappas, R. Schwerdtfeger, Editors, W3C Working Draft (work in progress), 7 March 2013. This version of WAI-ARIA 1.0 Authoring Practices is available at http://www.w3.org/TR/2013/WD-wai-aria-practices-20130307/. Latest version of WAI-ARIA Authoring Practices available at http://www.w3.org/TR/wai-aria-practices/.
[ARIA-PRIMER]
WAI-ARIA 1.0 Primer. L. Pappas, R. Schwerdtfeger, M. Cooper, Editors, W3C Working Draft (work in progress), 16 September 2010. This version of WAI-ARIA Primer is available at http://www.w3.org/TR/2010/WD-wai-aria-primer-20100916/. 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/.
[ATK]
Gnome Accessibility Toolkit 2.10.0. Available at https://developer.gnome.org/atk/2.10/.
[AT-SPI]
Assistive Technology-Service Provider Interface 2.10. Available at https://developer.gnome.org/libatspi/2.10/.
[AXAPI]
The Mac OS X Accessibility Protocol Mac OS 10.9. Available at: https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Protocols/NSAccessibility_Protocol/Reference/Reference.html.
[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/.
[IA2]
IAccessible2 1.3. Available at http://www.linuxfoundation.org/collaborate/workgroups/accessibility/iaccessible2.
[MSAA]
Microsoft Active Accessibility (MSAA) 2.0. Available at http://msdn.microsoft.com/en-us/library/ms697707.aspx.
[UIA-ARIA]
UI Automation for W3C Accessible Rich Internet Applications Specification. Available at http://msdn.microsoft.com/en-us/library/ee684013%28VS.85%29.aspx.
[WCAG20]
Web Content Accessibility Guidelines 2.0, B. Caldwell, G. Vanderheiden, L. Guarino Reid, M. Cooper, Editors, W3C Recommendation, 11 December 2008, http://www.w3.org/TR/2008/REC-WCAG20-20081211/. Latest version of WCAG 2.0 available at http://www.w3.org/TR/WCAG20/.

13.2. Acknowledgments

The following people contributed to the development of this document.

13.2.1. Participants active in the PFWG at the time of publication

  • Christy Blew (Invited Expert, University of Illinois)
  • David Bolter (Mozilla Foundation)
  • Michael Cooper (W3C/MIT)
  • James Craig (Apple Inc.)
  • Joanmarie Diggs (Igalia)
  • Steve Faulkner (The Paciello Group)
  • John Foliot (Invited Expert)
  • Scott González (JQuery Foundation)
  • Karl Groves (The Paciello Group)
  • Jon Gunderson (Invited Expert, University of Illinois)
  • Markus Gylling (DAISY Consortium)
  • Mona Heath (Invited Expert, University of Illinois)
  • Matthew King (IBM Corporation)
  • Dominic Mazzoni (Google, Inc.)
  • Shane McCarron (Invited Expert, Aptest)
  • Charles McCathieNevile (Yandex)
  • Mary Jo Mueller (IBM Corporation)
  • James Nurthen (Oracle Corporation)
  • Mark Sadecki (W3C)
  • Janina Sajka (Invited Expert, The Linux Foundation)
  • Joseph Scheuhammer (Invited Expert, Inclusive Design Research Centre, OCAD University)
  • Stefan Schnabel (SAP AG)
  • Richard Schwerdtfeger (IBM Corporation)
  • Lisa Seeman (Invited Expert)
  • Cynthia Shelly (Microsoft Corporation)
  • Alexander Surkov (Mozilla Foundation)
  • Andi Snow-Weaver (IBM Corporation)
  • Léonie Watson (The Paciello Group)
  • Wu Wei (W3C / RITT)
  • Gottfried Zimmermann (Invited Expert, Access Technologies Group)

13.2.2. Other ARIA contributors, commenters, and previously active PFWG participants

The Protocols and Formats Working Group expresses special thanks to three individuals for extraordinary contributions to ARIA:

  • Richard Schwerdfeger who conceived the technology now encapsulated in the ARIA specification and who has lead the PF's work on ARIA from the beginning as our ARIA Task Force Facilitator.
  • Alfred Gilman who, as Chair of PFWG, grasped the need and the opportunity for PF to create this technology and convinced the W3C that PF should develop ARIA.
  • Aaron Leventhal for authoring literally tens of thousands of lines of software code that allowed Firefox to demonstrate the practical viability of ARIA, and for conceiving and authoring the first ARIA User Agent Implementation Guide draft.

Other contributors:

  • Shadi Abou-Zahra (W3C)
  • Jim Allan (TSB)
  • Jonny Axelsson (Opera Software)
  • David Baron (Mozilla Foundation)
  • Art Barstow (Nokia Corporation)
  • Simon Bates
  • Chris Blouch (AOL)
  • Judy Brewer (W3C/MIT)
  • Mark Birbeck (Sidewinder Labs)
  • Sally Cain (Royal National Institute of Blind People (RNIB))
  • Gerardo Capiel (Benetech)
  • Ben Caldwell (Trace)
  • Sofia Celic-Li
  • Jaesik Chang (Samsung Electronics Co., Ltd.)
  • Alex Qiang Chen (University of Manchester)
  • Charles Chen (Google, Inc.)
  • Christian Cohrs
  • Deborah Dahl
  • Erik Dahlström (Opera Software)
  • Dimitar Denev (Frauenhofer Gesellschaft)
  • Micah Dubinko (Invited Expert)
  • Mandana Eibegger
  • Beth Epperson (Websense)
  • Donald Evans (AOL)
  • Chris Fleizach (Apple Inc.)
  • Kelly Ford (Microsoft Corporation)
  • Geoff Freed (Invited Expert, NCAM)
  • Kentarou Fukuda (IBM Corporation)
  • Bryan Garaventa
  • Guido Geloso
  • Ali Ghassemi
  • Becky Gibson (IBM)
  • Alfred S. Gilman
  • Andres Gonzalez (Adobe Systems Inc.)
  • James Graham
  • Georgios Grigoriadis (SAP AG)
  • Jeff Grimes (Oracle)
  • Loretta Guarino Reid (Google, Inc.)
  • Katie Haritos-Shea (Invited Expert)
  • Barbara Hartel
  • James Hawkins (Google, Inc.)
  • Benjamin Hawkes-Lewis
  • Sean Hayes (Microsoft Corporation)
  • Jan Heck
  • Shawn Henry
  • Tina Homboe
  • John Hrvatin (Microsoft Corporation)
  • Takahiro Inada
  • Masayasu Ishikawa (W3C)
  • Jim Jewitt
  • Kenny Johar (Microsoft Corporation)
  • Shilpi Kapoor (BarrierBreak Technologies)
  • Masahiko Kaneko (Microsoft Corporation)
  • Marjolein Katsma
  • George Kerscher (International Digital Publishing Forum)
  • Jason Kiss (New Zealand Government)
  • Todd Kloots
  • Johannes Koch
  • Sam Kuper
  • Earl Johnson (Sun)
  • Jael Kurz
  • Rajesh Lal (Nokia Corporation)
  • Diego La Monica (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  • Aaron Leventhal (IBM Corporation)
  • Gez Lemon (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  • Alex Li (SAP)
  • Chris Lilley
  • Thomas Logan (HiSoftware Inc.)
  • William Loughborough (Invited Expert)
  • Linda Mao (Microsoft)
  • David MacDonald (Invited Expert, CanAdapt Solutions Inc.)
  • Carolyn MacLeod
  • Anders Markussen (Opera Software)
  • Matthew May (Adobe Systems Inc.)
  • Krzysztof Maczyński
  • Alexandre Morgaut (4D)
  • Ann Navarro (Invited Expert)
  • Joshue O Connor (Invited Expert, CFIT)
  • Artur Ortega (Microsoft Corporation)
  • Sailesh Panchang (Deque)
  • Lisa Pappas (Society for Technical Communication (STC))
  • Marta Pawlowlska (Samsung Electronics Co., Ltd.)
  • Dave Pawson (RNIB)
  • Steven Pemberton (CWI Amsterdam)
  • Simon Pieters (Opera Software)
  • Jean-Bernard Piot (4D)
  • David Poehlman, Simon Pieters (Opera Software)
  • Sarah Pulis (Media Access Australia)
  • T.V. Raman (Google, Inc.)
  • Jan Richards
  • Gregory Rosmaita (Invited Expert)
  • Tony Ross (Microsoft Corporation)
  • Alex Russell (Dojo Foundation) (
  • Mario Sánchez Prada (Samsung Electronics Co., Ltd. and Gnome Foundation)
  • Martin Schaus (SAP AG)
  • Doug Schepers (W3C)
  • Matthias Schmitt
  • Marc Silbey (Microsoft Corporation)
  • Leif Halvard Sili
  • Henri Sivonen (Mozilla)
  • Michael Smith (W3C)
  • Ville Skyttä
  • Henny Swan (BBC)
  • Neil Soiffer (Design Science)
  • Vitaly Sourikov
  • Mike Squillace (IBM)
  • Maciej Stachowiak (Apple Inc.)
  • Christophe Strobbe
  • Suzanne Taylor (Pearson plc)
  • Terrill Thompson
  • David Todd
  • Gregg Vanderheiden (Invited Expert, Trace)
  • Anne van Kesteren
  • Ryan Williams (Oracle)
  • Tom Wlodkowski
  • Sam White (Apple Inc.)

13.2.3. Enabling funders

This publication has been funded in part with Federal funds from the U.S. Department of Education, National Institute on Disability and Rehabilitation Research (NIDRR) under contract number ED-OSE-10-C-0067. 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.