[contents]

W3C

WAI-ARIA 1.0 User Agent Implementation Guide

A user agent developer's guide to understanding and implementing Accessible Rich Internet Applications

Editors' Draft 14 December 2009

This version:
http://www.w3.org/WAI/PF/aria-implementation/20091214/
Latest editors' draft:
http://www.w3.org/WAI/PF/aria-implementation/
Latest public version:
http://www.w3.org/TR/wai-aria-implementation/
Editors:
Andi Snow-Weaver, IBM
Michael Cooper, W3C
Previous Editors:
Aaron Leventhal (until January 2009 while at IBM)

Abstract

This document describes how user agents should support keyboard navigation and respond to roles, states, and properties provided in Web content via WAI-ARIA [ARIA]. These features are used by authors creating accessible rich internet applications. Users often access the content using assistive technologies that rely on platform accessibility APIs to obtain and interact with information from the page. The WAI-ARIA User Agent Implementation Guide defines how implementations should expose content to accessibility APIs, helping to ensure that this information appears in a manner consistent with author intent. 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 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.

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. 1. Introduction
    1. 1.1. Accessibility APIs
    2. 1.2. The Accessible Tree and the DOM Tree
  2. 2. Normative User Agent Implementation Requirements for WAI-ARIA
  3. 3. Supporting Keyboard Navigation
    1. 3.1. Controlling focus with tabindex
    2. 3.2. Controlling focus with aria-activedescendant
    3. 3.3. Handling focus changes from the Assistive Technology
  4. 4. Mapping WAI-ARIA to Accessibility APIs
    1. 4.1. General rules for exposing WAI-ARIA semantics
    2. 4.2. Conflicts between native markup semantics and WAI-ARIA
    3. 4.3. Exposing attributes that do not directly map to accessibility API properties
    4. 4.4. Role mapping
    5. 4.5. State and Property Mapping
    6. 4.6. Special Processing Requiring Additional Computation
      1. 4.6.1. Name and Description
      2. 4.6.2. Widget Values
      3. 4.6.3. Relations
      4. 4.6.4. Group Position
    7. 4.7. Actions
    8. 4.8. Events
      1. 4.8.1. State and Property Change Events
      2. 4.8.2. Changes to document content or node visibility
      3. 4.8.3. Selection
      4. 4.8.4. Menus in MSAA/IAccessible2/UIA
  5. 5. Special Document Handling Procedures
    1. 5.1. Documents, Handling frame and iframe elements
    2. 5.2. CSS Selectors
    3. 5.3. Author Errors
  6. 6. Appendices
    1. 6.1. Glossary
    2. 6.2. References
    3. 6.3. Acknowledgments
      1. 6.3.1. Participants in the PFWG at the time of publication
      2. 6.3.2. Other previously active PFWG participants and other contributors to the Accessible Rich Internet Applications specification
      3. 6.3.3. Enabling funders

1. Introduction

This section is informative.

In traditional desktop graphical user interface (GUI) applications, elements of the user interface (UI) are displayed when needed and hidden when not needed based on user interactions. Accessibility application programming interfaces (APIs) are used to communicate semantic information about the user interface to assistive technology software used by people with disabilities. These APIs constitute a contract between applications and assistive technologies, such as screen readers, magnifiers, alternate input devices, and speech command and control, to enable them to access the appropriate semantics needed to produce a usable alternative to interactive applications. For example, screen reading software for the blind can determine whether a particular UI element is a menu, button, text field, list box, etc.

In traditional static Web pages, the HTML elements provided the necessary semantic information. Assistive technologies obtain the information from the Document Object Model (DOM) or, in the case of form elements, through the Accessibility API. In both cases, the assistive technology expects that nothing changes until a new page is loaded based on a user action. Yet, technologies such as JavaScript, Ajax, and CSS have enabled Web pages to look and behave more like interactive desktop GUI applications without the need to reload the page with each user interaction. Developers can now repurpose HTML elements into UI elements not previously defined in HTML. For example, Javascript can be used with CSS to modify a <div> element based on user interactions to make it look and behave like a popup menu. Unfortunately, the <div> element does not provide the author with a vehicle to add semantic metadata that can be exposed through the DOM and mapped to Accessibility APIs so that a screen reader can understand that it is a menu.

WAI-ARIA enables rich Internet applications to have the same accessibility features as desktop GUI applications by adding metadata to markup technologies such as (X)HTML. Authors include WAI-ARIA in their markup and user agents translate the WAI-ARIA markup to the platform accessibility APIs.

The WAI-ARIA User Agent Implementation Guide is intended to provide readers with an understanding of how to implement WAI-ARIA in user agents. As explained in the WAI-ARIA Primer [ARIA-PRIMER], accessibility deficiencies in traditional 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) has addressed these deficiencies through several W3C standards efforts, with a focus on the WAI-ARIA specifications.

The WAI-ARIA User Agent Implementation Guide is part of a set of resources that support the WAI-ARIA specification. For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Primer [ARIA-PRIMER] provides a basic introduction to the concepts behind and reason for WAI-ARIA. The WAI-ARIA Authoring Practices Guide [ARIA-PRACTICES] describes recommended usage patterns for Web content developers. The User Agent Implementation Guide describes how WAI-ARIA roles, states, and properties should be supported in user agents using platform accessibility APIs. The WAI-ARIA Suite fills gaps identified by the Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap) [ARIA-ROADMAP]. These documents serve as important places of clarification where topics appear to be unclear.

With the conceptual basis provided in the WAI-ARIA Primer [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 a general overview of accessibility APIs and the accessible object hierarchy known as the accessible tree. The following sections give guidance on supporting keyboard navigation and mapping WAI-ARIA roles, states, and properties to accessibility APIs. Other sections give guidance on calculating text alternatives, mapping actions to events, event processing, special document handling procedures, and error handling.

This guide assumes that a user agent already exposes static content to ATs via the accessibility API on a given platform. Most of the additional work to enable WAI-ARIA can be divided into three parts:

  1. Making focus and tab navigation work on elements that previously were not focusable
  2. Mapping the WAI-ARIA roles and properties into the roles, states and other property getters in the accessibility API
  3. Computing text alternatives and managing states and events

In general, WAI-ARIA properties should only affect how content is mapped to platform accessibility APIs. They should not affect the visual rendering of content or the behavior of mainstream desktop browsers, except when style sheets are deliberately keyed off of WAI-ARIA attributes as recommended in the specification. This allows one of the primary principles of WAI-ARIA to be upheld—that content still renders and behaves the same for the majority of users in legacy browsers which do not support WAI-ARIA.

1.1. Accessibility APIs

The Document Object Model (DOM) is used to represent the structure and state of the elements in the document being rendered by the user agent. The elements of the document are organized into a hierarchy of nodes known as the DOM tree. Developers use APIs to manipulate the objects in the DOM tree enabling the concept of rich Internet applications.

For traditional Web pages, assistive technologies, such as screen readers, interact with user agents using the DOM. In order to make a Web application behave like a desktop application, the user agent needs to map accessibility information from the elements in the DOM tree to the Accessibility APIs of the underlying operating system or software platform throughout the lifecycle of the application. The screen reader or other assistive technology uses the semantic information exposed via the accessibility API to provide an alternative rendering of an application that is meaningful to a user. Originally, screen readers used heuristic techniques to determine the meaning of the user interface and built an alternative off screen model of the user interface. For example, a row of labels displayed horizontally near the top of an application window might be a menu. Labels with a border drawn around them might be buttons. Heuristic techniques are not always accurate, however, and require assistive technologies to be updated whenever the software application is updated.

A much better technique is for the software application to provide the necessary information for interoperability with assistive technology. To meet this need, platform owners have developed specialized interfaces, called accessibility APIs, which can be used to communicate accessibility information to assistive technologies. When developers use WAI-ARIA to provide the semantic role, state, and property information for elements in a rich Internet Application (RIA), the user agent must then map the information to the appropriate accessibility API for the platform.

Accessibility APIs covered by this document are:

If User Agent developers need to expose to other accessibility APIs, it is recommended that they work closely with the developer of the platform where the API runs, and assistive technology developers on that platform.

1.2. The Accessible Tree and the DOM Tree

The accessible tree and the DOM tree are parallel structures. Roughly speaking the accessible tree is a subset of the DOM tree. It includes the user interface objects of the user agent and the objects of the document. Accessible objects are created in the accessible tree for every DOM element that should be exposed to an assistive technology, either because it may fire an accessible event or because it has a property, relationship or feature which needs to be exposed. Generally if something can be trimmed out it will be, for reasons of performance and simplicity. For example, a <span> with just a style change and no semantics may not get its own accessible object, but the style change will be exposed by other means.

2. Normative User Agent Implementation Requirements for WAI-ARIA

This section is normative.

This specification indicates whether a section is normative or informative and the classification applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.

Normative sections provide requirements that must be followed for an implementation to conform to this specification. The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Keywords for use in RFCs to indicate requirement levels [RFC2119].

Informative sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.

3. Supporting Keyboard Navigation

This section is normative.

Enabling keyboard navigation in web applications is a necessary step toward making accessible web applications possible. User agents MUST ensure all renderable elements are focusable and may be focusable without having to be placed in a pre-defined tabbing order. All focusable elements must also provide for programmatic access. This allows for device-independent access, is needed to conform to the User Agent Accessibility Guidelines, and is vital for a successful implementation of WAI-ARIA.

Usable keyboard navigation in a rich Internet application is different from the tabbing paradigm among interactive elements such as links and form controls in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant complex widgets and uses the arrow keys to navigate within a complex widget, such as a menu or spreadsheet. The changes that WAI-ARIA introduces in keyboard navigation make this enhanced accessibility possible. In WAI-ARIA, any element can be keyboard focusable.

There are two mechanisms that allow for keyboard operation of accessible script widgets: tabindex and aria-activedescendant. Most other aspects of WAI-ARIA widget development depend on keyboard navigation functioning properly.

Assistive technologies often need to set the focus. For example, voice input software, onscreen keyboards and screen readers supply their own structured navigation modes, providing additional commands for moving to elements in a page. Both the user agent and web pages need to handle this gracefully. Script container widgets cannot expect that focus changes occur only from the keyboard or a mouse click. They need to listen for focus or aria-activedescendant changes and update their state when that occurs.

3.1. Controlling focus with tabindex

User agents that support WAI-ARIA expand the usage of tabindex, focus, and blur to allow them on all HTML elements. Authors may add any element such as a div, span or img to the default tab order by setting tabindex="0". In addition, any item with tabindex equal to a negative integer can be focused via script or a mouse click, but is not part of the default tab order. This is not supported in the HTML 4 specification but is expected to be in compliance with HTML 5..

The tabindex system provides one way to develop custom widgets which are keyboard accessible, from simple widgets like a slider to container widgets like a menubar, tree view or spreadsheet.

The user agent implementation MUST to do the following to enable tabindex on all elements:

  1. Where tabindex equals a negative integer, the user agent MUST allow the element to be focused, but MUST not include the element in the sequential tab order.
  2. Where tabindex="0", the user agent MUST allow the element to be focused and MUST include the element in the sequential tab order.
  3. Where tabindex is greater than zero, the user agent MUST allow the element to be focused, and MUST include the element in the sequential tab order according to the value of the tabindex attribute and before any elements with tabindex either omitted or with a value of zero. See Sequential focus navigation for details.
  4. Every HTML Element that supports the tabindex attribute MUST expose the element.tabIndex property.
  5. The focus and blur methods MUST be added to the HTMLElement interface (available to script for every type of element).
  6. Any element that can receive focus MUST fire focus and blur events.
  7. Canceling a keydown event MUST also cancel the keypress event, for purposes of compatibility with other browsers.
  8. All elements which are focusable MUST be exposed in the accessible tree, so that when they receive focus, there is an object for which to fire an accessibility event.
  9. Expose the FOCUSED and FOCUSABLE accessibility API states, and FOCUS events for any element in the accessible tree as described in State and Property Mapping.
  10. When the user triggers an element that is only focusable because of its tabindex attribute in a manner other than clicking it, such as by pressing Enter, and the element has no defined activation behavior, the user agent MUST fire a click event.
  11. When the user triggers an element with a defined activation behavior in a manner other than clicking it, such as by pressing Enter, the user agent MUST simulate a click on the element. The steps to simulate a click include:
    1. running pre-click activation steps
    2. firing a click event
    3. running post-click activation steps
    If the event is cancelled, the user agent MUST run cancelled activation steps on the element instead.

Note: Over time, user agents have provided differing implementations and levels of support for the tabindex attribute. Examples include: the Gecko documentation on Key-navigable custom DHTML widgets; the documentation for Internet Explorer's's tabindex behavior in MSDN: tabindex Property, and Opera simple testcases. The HTML 5 spec documents what the extended behavior of tabindex should be ([HTML5]) and user agent implementations.

3.2. Controlling focus with aria-activedescendant

Editorial note: In current implementations as described below, user agents keep the desktop focus on the container but communicate focus events and states to the AT as if the active descendant has focus.

Alternatively, the actual desktop focus could move to the active descendant. This would be a less complex scenario for user agents to implement and would be a better scenario for users who have customized the appearance of their desktop keyboard focus. There is some concern that if the desktop focus is placed on the active descendant, some keyboard events might get dropped.

The User Agent Implementation task force seeks feedback from reviewers on this issue.

The aria-activedescendant property could also be used to enable keyboard accessibility on any type of WAI-ARIA element. It is often a more convenient way of creating container widget keyboard navigation (where the entire widget is in the tab order just once, but the user can use keystrokes to navigate to descendant items of the container).

Typically, the author will use tabindex="0" on the container element and aria-activedescendant to point to the ID of the currently active descendant. The author, not the user agent, is responsible for styling the currently active descendant to show it has keyboard focus (not via :focus since actual focus is on the container).

The user agent MUST do the following to implement aria-activedescendant:

  1. Implement the tabindex recommendations in Controlling focus with tabindex. Support for tabindex="0" on all elements is still necessary for authors to use the aria-activedescendant system, because the container widget MUST be in the tab order.
  2. For an element that has focus in the DOM, but also has aria-activedescendant which points to a valid ID, the user agent MUST not mark it as focused in the accessibility API.
  3. When the aria-activedescendant attribute changes on an element that currently has DOM focus, the user agent MUST fire an accessibility API FOCUS event on the new active descendant. If aria-activedescendant is cleared or does not point to an element in the current document, the user agent MUST fire a focus event for the container object that had the attribute change.
  4. For any element with an ID attribute, where the element is a descendant of an element with the aria-activedescendant attribute, the user agent MUST apply the following states to the target to ensure the object is accessible:
    1. FOCUSABLE, if the element also has a WAI-ARIA role—because the aria-activedescendant of the container can potentially point to it. It is not absolutely necessary to check this when there is no role, because real HTML elements that would be focused would already be focusable.
    2. ACTIVE, whenever the container element sets aria-activedescendant to match the ID of this descendant
    3. FOCUSED, if ACTIVE and the container widget with aria-activedescendant has true DOM focus
  5. If the AT sets focus to a descendant of a container with aria-activedescendant, the user agent MUST change the value of aria-activedescendant to point to that item.

3.3. Handling focus changes from the Assistive Technology

Alternative input software needs to be able to set focus to items that are focusable. Screen readers, voice input software and on-screen keyboards may set focus based on user commands implemented in that software. The following table describes the API used to set focus.

MSAAUIAATKMAC Accessibility
accSelect(SELFLAG_TAKEFOCUS)RaiseAutomationEventAtkComponent::grab_focus 

4. Mapping WAI-ARIA to Accessibility APIs

This section is normative.

4.1. General rules for exposing WAI-ARIA semantics

Where supported by the platform Accessibility API, WAI-ARIA semantics MUST be exposed through the standard mechanisms of the desktop accessibility API. For example, for WAI-ARIA widgets, compare how the widget is exposed in a similar desktop widget. In general most WAI-ARIA widget capabilities are exposed through the role, value, Boolean states and relations of the accessibility API.

User agents MUST provide an accessible object corresponding to DOM elements that meet any of the following criteria in the accessible tree:

The following elements are not exposed via the accessibility API and user agents SHOULD NOT include them in the accessible tree:

User agents MUST notify assistive technology of state changes but SHOULD only notify assistive technology of property changes if the accessibility API defines a change event for the property. For example, IAccessible2 defines an event to be used when aria-activedescendant changes.

4.2. Conflicts between native markup semantics and WAI-ARIA

WAI-ARIA is generally used on elements that have no native semantics of their own with respect to user interface objects. WAI-ARIA is meant to extend the semantics of native host language elements when the desired element is modified to create a new UI object but has insufficient semantics to meet the intent of the author. At times, WAI-ARIA is used on elements that have similar but not identical semantics to the intended object (for instance, nested list elements might be used to represent a tree structure). This is usually done as part of a fallback strategy, or because native presentation of the re-purposed element reduces the amount of style and script the author must use. In these cases, the user agent MUST use the WAI-ARIA semantics to define how it exposes the element to accessibility APIs, not the native semantics. To achieve this the following rules MUST be followed:

It should be noted that while the user agent overrides the native semantics with the WAI-ARIA semantics, host languages may define some combinations of WAI-ARIA and native semantics as invalid, and validators for those languages may flag such uses as coding errors or warnings.

4.3. Exposing attributes that do not directly map to accessibility API properties

Platform accessibility APIs may have features that are not in WAI-ARIA. Likewise, WAI-ARIA exposes capabilities that are not supported by accessibility APIs at the time of publication. There typically is not a one to one relationship between all WAI-ARIA attributes and platform accessibility APIs. When WAI-ARIA roles, states and properties do not directly map to an accessibility API, and there is a way in the API to expose a text string, user agents MUST expose the raw WAI-ARIA data as a text string. User agents MAY also expose the raw WAI-ARIA information through this API even when there is a direct mapping to an accessibility API.

IAccessible2 and ATK use object attributes to expose semantics that are not directly supported in the APIs. Object attributes are name-value pairs that are loosely specified, and very flexible for exposing things that an accessibility API does not have a specific interface for. For example, at this time, the aria-live attribute can be exposed via an object attribute because accessibility APIs have no such property available. Specific rules for exposing object attribute name-value pairs are described throughout this document, and rules for the general cases not covered are in State and Property Mapping.

In UIA, use the AriaRole and AriaProperties properties.

For accessibility APIs that do not have "object attributes" per se, it is useful to find a similar mechanism or develop a new interface to expose name/value pairs. Under the Mac OS X Accessibility Protocol, all getters are already simply name-value pairs and it is possible to expose new semantics whenever necessary. Keep in mind, this also requires working with the assistive technology developers to gain support for the new semantics.

4.4. Role mapping

Platform accessibility APIs traditionally have had a finite set of predefined roles that are expected by assistive technologies on that platform and only one or two roles may be exposed. In contrast, WAI-ARIA allows multiple roles to be specified as an ordered set of space-separated valid role tokens. The additional roles are fallback roles similar to the concept of specifying multiple fonts in case the first choice font type is not supported.

WAI-ARIA includes some roles, such as landmarks and advanced widgets, that are not traditionally part of accessibility APIs. Because landmarks do not generally have mappings in platform accessibility APIs, they may occur anywhere within the role string without affecting how the first widget role is exposed. In addition, future versions of WAI-ARIA may allow for author-defined roles to be used in the role string. In that case, it is expected that a fallback role may be provided after the custom role, in the role string.

The user agent MUST expose roles so that the standard role mechanism of the accessibility API provides the best-fit widget role, yet the entire role string MUST also be available for parsing:

  1. The first token in the sequence of tokens in the role attribute value which matches, on case-sensitive comparison, the name of any non-abstract WAI-ARIA role MUST be used for the standard role mechanism of the accessibility API. Use the role mapping table below and apply any special case rules that are specified. When a matching role is found, user agents MUST use it to override any implicit role inferred from the host language markup in performing this mapping. Note that this overriding does not result in any changes in the DOM, only in the accessibility API representation of the document.

    The following steps will correctly identify the applicable WAI-ARIA role:

    1. Use the rules of the host language to detect that an element has an attribute with attribute name of role and to identify the attribute value string for that attribute.
    2. Separate the attribute value string for that attribute into a sequence of whitespace-free substrings by separating on whitespace.
    3. Do a case-sensitive comparison of the substrings to all the names of the non-abstract WAI-ARIA roles.
    4. Use the first such substring in textual order that matches the name of a non-abstract WAI-ARIA role for the API role mapping.
  2. Roles defined in the WAI-ARIA spec as "abstract" MUST NOT be mapped via the standard role mechanism of the accessibility API. The abstract roles are:
  3. If the element does not have a role attribute, or if the role attribute contains no tokens matching the name of a non-abstract WAI-ARIA role, the user agent MUST fall back on normal processing of the base markup for the element with the role attribute. For example, for <table role="log"> use the tag name "table" to determine what platform accessibility API role to use. For <input type="text" role="search">, use the platform accessibility API for a text input.
  4. The entire role string MUST be exposed as a text string if the API supports it. This allows assistive technologies to do their own additional processing of roles.
    • Microsoft Active Accessibility:
    • IAccessible2: expose as an object attribute pair (role=string)
    • User Interface Automation: expose as AriaRole property. The AriaRole property can also support secondary roles using a space as a separator.
    • Accessibility Toolkit: expose as an object attribute pair (role=string)
    • Apple:
  5. Platform accessibility APIs typically do not provide a vehicle to notify assistive technologies that a role has changed. Due to this and document caching, assistive technologies are unlikely to process a change in role attribute value. Authors who wish to change a role are advised by the WAI-ARIA specification to delete the associated element and its children and replace it with a new element having the appropriate role. If a role is changed, however, user agents SHOULD update the mapping in order to reflect the content in the DOM. Since assistive technologies will not know that the role has changed, a user agents MAY address this error condition by treating it as removing a subtree item and inserting a new one as described in Changes to document content or node visibility.
Table describing mapping of WAI-ARIA roles to accessibility APIs.
WAI-ARIA roleMSAA roleIAccessible2 role and other IAccessible2 featuresUIA Control Pattern TypeATK roleMAC Accessibility Role
alertROLE_SYSTEM_ALERT TextATK_ROLE_ALERTAXGroup, AXRoleDescription="alert"
alertdialogROLE_SYSTEM_DIALOG WindowATK_ROLE_DIALOGAXGroup, AXRoleDescription="alert dialog"
applicationROLE_SYSTEM_APPLICATION PaneATK_ROLE_EMBEDDEDAXGroup, AXRoleDescription="application"
articleROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY  ATK_ROLE_DOCUMENT_FRAME + do not expose ATK_STATE_EDITABLEAXGroup, AXRoleDescription"article"
banner Object attribute role="banner"Expose as text string in AriaRoleObject attribute role="banner"AXGroup, AXRoleDescription="banner"
buttonROLE_SYSTEM_PUSHBUTTON. If aria-haspopup="true" it SHOULD be exposed as a ROLE_SYSTEM_BUTTONMENUIf aria-pressed is not undefined, it SHOULD be exposed as IA2_ROLE_TOGGLE_BUTTONButtonATK_ROLE_PUSH_BUTTONAXButton
checkboxROLE_SYSTEM_CHECKBUTTONobject attribute checkable="true"CheckboxATK_ROLE_CHECK_BOX + object attribute checkable="true"AXCheckBox
columnheaderROLE_SYSTEM_COLUMNHEADERused to help support AccessibleTable for the container grid roleDataItemATK_ROLE_COLUMN_HEADERAXCell
comboboxROLE_SYSTEM_COMBOBOX + STATE_SYSTEM_HASPOPUP. If aria-expanded is not "true", expose STATE_SYSTEM_COLLAPSED ComboboxATK_ROLE_COMBO_BOX + ATK_STATE_EXPANDABLE + object attribute haspopup="true"AXComboBox
complementary Object attribute role="complementary"Expose as text string in AriaRoleObject attribute role="complementary"AXGroup, AXRoleDescription="complementary"
contentinfo Object attribute role="contentinfo"Expose as text string in AriaRoleObject attribute role="contentinfo"AXGroup, AXRoleDescription="content"
definition Object attribute role="definition"Expose as text string in AriaRoleObject attribute role="definition" 
dialogROLE_SYSTEM_DIALOG WindowATK_ROLE_DIALOGAXGroup, AXRoleDescription="dialog"
directoryROLE_SYSTEM_LIST List AXList
documentROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY DocumentATK_ROLE_DOCUMENT_FRAME + readonlyAXGroup, AXRoleDescription="document"
gridROLE_SYSTEM_TABLEUse IAccessibleTable2 interfaceDataGridATK_ROLE_TABLEAXTable
gridcellROLE_SYSTEM_CELL DataItemATK_ROLE_TABLE_CELLAXCell
groupROLE_SYSTEM_GROUPING GroupATK_ROLE_PANELAXGroup
headingROLE_SYSTEM_TEXT or use xml-rolesIA2_ROLE_HEADINGTextATK_ROLE_HEADINGAXHeading
imgROLE_SYSTEM_GRAPHIC ImageATK_ROLE_IMAGEAXImage
linkROLE_SYSTEM_LINK. Also, apply special rule to expose STATE_LINKED to link and all its descendants. HyperLinkATK_ROLE_LINKAXLink
listROLE_SYSTEM_LIST + STATE_SYSTEM_READONLY ListATK_ROLE_LIST + do not expose ATK_STATE_EDITABLEAXList
listbox. If child of or owned by a combobox, expose as menuROLE_SYSTEM_LIST ListATK_ROLE_LIST. Special case: if a listbox has a parent or is owned by (via aria-owns) a combobox, it SHOULD be exposed with ATK_ROLE_MENU.AXList
listitemROLE_SYSTEM_LISTITEM + STATE_SYSTEM_READONLY ListItemATK_ROLE_LISTITEM + do not expose ATK_STATE_EDITABLEAXGroup
logROLE_SYSTEM_PANEExpose as object attribute role="log"Pane AXGroup, AXRoleDescription="log"
main Object attribute role="main"Expose as text string in AriaRoleObject attribute role="main"AXGroup, AXSubrole: AXLandmarkMain, AXRoleDescription="main"
marqueeROLE_SYSTEM_ANIMATION or use xml-rolesExpose as object attribute role="marquee"TextATK_ROLE_PANELAXGroup, AXRoleDescription="marquee"
mathROLE_SYSTEM_EQUATION  ATK_ROLE_UNKNOWNAXGroup, AXRoleDescription="math"
menuROLE_SYSTEM_MENUPOPUP MenuATK_ROLE_MENU. These objects SHOULD NOT be exposed for a submenu if there is a parent menu item spawning the submenuAXMenu
menubarROLE_SYSTEM_MENUBAR MenuBarATK_ROLE_MENU_BARAXMenuBar
menuitemROLE_SYSTEM_MENUITEM MenuItemATK_ROLE_MENU_ITEM
  • If aria-checked is not undefined, support object attribute checkable"="true"

If the option's parent has a group role, then role="menuitem" maps to NSAccessibilityMenuButtonRole

If the option's parent has a menu role, then role="menuitem" maps to NSAccessibilityMenuItemRole

AXMenuItem

menuitemcheckboxROLE_SYSTEM_CHECKBUTTON or ROLE_SYSTEM_MENUITEMIA2_ROLE_CHECK_MENU_ITEM + object attribute checkable="true"CheckboxATK_ROLE_CHECK_MENU_ITEM + object attribute checkable="true"AXMenuItemRole
menuitemradioROLE_SYSTEM_RADIOBUTTON or ROLE_SYSTEM_MENUITEMIA2_ROLE_RADIO_MENU_ITEM + object attribute checkable="true"RadioButtonATK_ROLE_RADIO_MENU_ITEM + object attribute checkable="true"AXMenuItemRole
navigation Expose as object attribute role="navigation"  AXGroup, AXRoleDescription="navigation"
noteIA2_ROLE_NOTE   AXGroup, AXRoleDescription="note"
optionROLE_SYSTEM_LISTITEMIf aria-checked is not undefined, support object attribute checkable="true"ListItemATK_ROLE_LIST_ITEM
  • If aria-checked is not undefined, support object attribute checkable="true"
  • Special case: if an option has a parent that was exposed as an ATK_ROLE_MENU, the option SHOULD be exposed as an ATK_ROLE_MENU_ITEM

If the option's parent has a menu role, then role="option" maps to NSAccessibilityMenuItemRole

If the option's parent has a listbox role, then role="option" maps to NSAccessibilityStaticTextRole

AXStaticText

presentationROLE_SYSTEM_PANE. Do not expose this object unless it is focusable PaneDo not expose this object unless it is focusableAXGroup, AXRoleDescription="presentation"
progressbarROLE_SYSTEM_PROGRESSBAR + STATE_SYSTEM_READONLY ProgressBarATK_ROLE_PROGRESS_BAR + do not expose ATK_EXTENDED_STATE_EDITABLEAXProgressIndicator
radioROLE_SYSTEM_RADIOBUTTON RadioButtonATK_ROLE_RADIO_BUTTONAXRadioButton
radiogroupROLE_SYSTEM_GROUPING GroupATK_ROLE_PANELAXRadioGroup
regionROLE_SYSTEM_PANE PaneATK_ROLE_PANELAXGroup, AXRoleDescription="region"
rowROLE_SYSTEM_ROW unless inside a "tree" or "treegrid", in which case ROLE_SYSTEM_OUTLINEITEMused to help support: IAccessibleTable2 interface for the container grid roleDataItemATK_ROLE_LIST_ITEMAXRow
rowheaderROLE_SYSTEM_ROWHEADERUsed to help support IAccessibleTable2 interface for the container grid roleDataItemATK_ROLE_ROW_HEADERAXCell
scrollbarROLE_SYSTEM_SCROLLBAR    
search    AXGroup, AXRoleDescription="search"
separatorROLE_SYSTEM_SEPARATOR SeparatorATK_ROLE_SEPARATORAXSplitter
sliderROLE_SYSTEM_SLIDER SliderATK_ROLE_SLIDERAXSlider
spinbuttonROLE_SYSTEM_SPINBUTTON SpinnerATK_ROLE_SPIN_BUTTONAXProgressIndicator
statusROLE_SYSTEM_STATUSBAR StatusBarATK_ROLE_STATUSBARAXGroup, AXRoleDescription="status"
tabROLE_SYSTEM_PAGETAB. Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby. TabItemATK_ROLE_PAGE_TAB. Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby.AXRadioButton, AXRoleDescription="tab"
tablistROLE_SYSTEM_PAGETABLIST TabATK_ROLE_PAGE_TAB_LISTAXTabGroup
tabpanelROLE_SYSTEM_PANE or ROLE_SYSTEM_PROPERTYPAGE PaneATK_ROLE_SCROLL_PANEAXTabGroup
textboxROLE_SYSTEM_TEXTIA2_STATE_SINGLE_LINE if aria-multiline is not "true"DocumentATK_ROLE_ENTRY + ATK_STATE_SINGLE_LINE if aria-multiline is not "true"AXTextArea
timer Expose as object attribute role="timer"  AXGroup, AXRoleDescription="timer"
toolbarROLE_SYSTEM_TOOLBAR ToolBarATK_ROLE_TOOL_BARAXToolbar
tooltipROLE_SYSTEM_TOOLTIP ToolTipATK_ROLE_TOOL_TIPAXGroup, AXRoleDescription="tooltip"
treeROLE_SYSTEM_OUTLINE TreeATK_ROLE_TREEAXOutline
treegridROLE_SYSTEM_OUTLINEUse IAccessibleTable2 interface

Expose as object attribute role="treegrid"

DataGridATK_ROLE_TREE_TABLEAXOutline
treeitemROLE_SYSTEM_OUTLINEITEMIf aria-checked is not undefined, support object attribute checkable="true"TreeItemATK_ROLE_LIST_ITEM + if aria-checked is not undefined, support object attribute checkable="true"AXRow, AXRoleDescription="outline row"

4.5. State and Property Mapping

This section describes how to expose states and object properties. Where possible, API standard states are used. When that is not possible, object attributes (or a similar mechanism) are required.

  1. Compute the states that are managed by the user agent such as VISIBLE/INVISIBLE, SHOWING/OFFSCREEN, etc. This typically is done in the same way as for ordinary elements that do not have WAI-ARIA attributes present. The FOCUSABLE/FOCUSED states may be affected by aria-activedescendant. See the rules in Controlling focus with aria-activedescendant.
  2. Add in states and object attributes supported by the accessibility implementation for the base markup. Map states and properties that are supported in the API.
  3. User agents SHOULD add additional information to the description, object attribute, or other text string.
  4. Some roles require additional states to be exposed. Apply special case rules for the primary role as defined in the table in Role mapping.
  5. Compute states for the relevant WAI-ARIA properties. To determine the relevant WAI-ARIA properties, see the table below.
  6. For forward compatibility with new WAI-ARIA properties in future versions, user agents SHOULD expose all properties not in these tables with a text string, removing the "aria-" prefix from the name. For example, aria-foo="bar" would be exposed with a text string foo=bar, since aria-foo is not a currently known WAI-ARIA property.
  7. Some WAI-ARIA properties are not global, and are only supported on certain roles. If a non-global WAI-ARIA state or property is used where it is not supported, user agents SHOULD act as if the WAI-ARIA state or property is absent, and not not map the given WAI-ARIA property to the platform accessibility API. For example, aria-checked should not be exposed as CHECKED on <div role="grid">
  8. In UIA, the AriaProperties property directly corresponds to the ARIA states and properties when an element is exposed in the accessible tree. UIA AriaProperties is a string property formatted as a name and value pair. For example, "checked=true;disabled=false". Deliminators are the equal sign ("=") and the semicolon (";"). A backslash (\) is used as an escape when the deliminator character or a backslash appears in the value. Some states that take ID as context are not however supported by the UIA AriaProperties. Instead, UIA supports specific relations properties such as DescribedBy or LabeledBy. Full mapping from ARIA states to MSAA and UIA properties are available at MSDN UIA SDK Appendix.
WAI-ARIA state and property mapping rule table
WAI-ARIA State or PropertyMSAAIAccessible2 (if different from MSAA)UI AutomationATKMAC Accessibility
aria-activedescendantSee Controlling focus with aria-activedescendant and Handling focus changes from the Assistive Technology. See also ID Reference Error Processing in Relations.

In cases, however, the focus can be transparent in an accessible tree as it may exposed as focus delegation from the container element to the child object that takes active focus. This is represented by an accessible object that comes with STATE_SYSTEM_FOCUSED state; When this happens standard focus event and event handling should apply.

  See Controlling focus with aria-activedescendant and Handling focus changes from the Assistive Technology. See also ID Reference Error Processing in Relations.

In cases, however, the focus can be transparent in an accessible tree as it may exposed as focus delegation from the container element to the child object that takes active focus. This is represented by an accessible object that comes with HasKeyboardFocus state; When this happens standard focus event and event handling should apply.

If AXFocused is true, post "NSAccessibilityFocusedUIElementChangedNotification" notification when aria-activedescendant value changes
aria-atomic="true" Expose object attribute atomic="true". In addition, expose object attribute container-atomic="true" on all descendants as well as IA2_RELATION_MEMBER_OF pointing to this element (the atomic root) as described in Changes to document content or node visibility. Expose object attribute atomic="true". In addition, expose object attribute container-atomic="true" on all descendants as well as RELATION_MEMBER_OF pointing to this element (the atomic root) as described in Changes to document content or node visibility. 
aria-atomic="false" (default)     
aria-autocomplete="inline", "list", or "both" Expose as object attribute autocomplete

Expose the IA2_STATE_SUPPORTS_AUTOCOMPLETION equivalent state

 Expose as object attribute autocomplete

Expose the ATK_SUPPORTS_AUTOCOMPLETION equivalent state

 
aria-autocomplete="none" (default)     
aria-busy (state)="true" (state)Expose the STATE_SYSTEM_BUSY state  Expose the ATK_STATE_BUSY state 
aria-busy (state)="false" (state) (default)Clear the STATE_SYSTEM_BUSY state  Clear the ATK_STATE_BUSY state 
aria-checked (state)="true" (state)Set the STATE_SYSTEM_CHECKED stateExpose object attribute checkable="true"Expose as ToggleState property in Toggle Control PatternExpose object attribute checkable="true"AXValue="1"
aria-checked (state)="false" (state)Clear the STATE_SYSTEM_CHECKED stateExpose object attribute checkable="true"Expose as ToggleState property in Toggle Control Pattern.Expose object attribute checkable="true"AXValue="0"
aria-checked (state)=""mixed" (state)Set the STATE_SYSTEM_CHECKED stateExpose object attribute checkable="true"Expose as ToggleState property in Toggle Control Pattern.Expose ATK_STATE_INDETERMINATE/STATE_SYSTEM_MIXED, unless on a role of radio or menuitemradio (in those cases treat as "false")

Expose object attribute checkable="true"

AXValue="0.5"
aria-checked is undefined (state)     
aria-controls Expose pointer to the accessible object in IA2_RELATION_CONTROLLER_FOR

Expose reverse relations as described in Relations.

Expose pointer to the accessible object ControllerFor propertyExpose pointer to the accessible object RELATION_CONTROLLER_FOR

Expose reverse relations as described in Relations.

 
aria-describedbyIf hidden, expose via accDescriptionIf not hidden, expose pointer to the accessible object in IA2_RELATION_DESCRIBED_BY

Expose reverse relations as described in Relations.

Expose pointer to the accessible object in DescribedByExpose pointer to the accessible object in RELATION_DESCRIBED_BY

Expose reverse relations as described in Relations.

Set AXDescription to text value of element found by property value
aria-disabled (state)="true" (state)Set STATE_SYSTEM_UNAVAILABLE

Expose STATE_SYSTEM_SENSITIVE + STATE_SYSTEM_ENABLED

Propagate to all descendants of the element with STATE_SYSTEM_FOCUSABLE

 Set IsEnabled to "false" Set AXEnabled to "false"
aria-disabled (state)="false" (state) (default)Clear STATE_SYSTEM_UNAVAILABLE Set IsEnabled to "true"Expose ATK_STATE_ENABLEDSet AXEnabled to "true"
aria-dropeffect (state) Expose as object attribute "dropeffect" Expose as object attribute "dropeffect" 
aria-dropeffect="none" (state) (default) Expose as object attribute "dropeffect" Expose as object attribute "dropeffect" 
aria-expanded (state)="true" (state)Set STATE_SYSTEM_EXPANDED Expose as ExpandCollapseState property of ExpandCollapse Control PatternExpose ATK_STATE_EXPANDABLE and ATK_STATE_EXPANDED 
aria-expanded (state)="false" (state)Set STATE_SYSTEM_COLLAPSED Expose as ExpandCollapseState property of ExpandCollapse Control PatternExpose ATK_STATE_EXPANDABLE 
aria-expanded is undefined (state) (default)The object is neither expandable or collapsible.    
aria-flowto Expose reference to the accessible object in IA2_RELATION_FLOW_TO

Expose reverse relations as described in Relations.

Expose a reference to the accessible object in FlowsTo propertyExpose reference to the accessible object in RELATION_FLOW_TO

Expose reverse relations as described in Relations.

 
aria-grabbed (state)="true" or "false" Expose object attribute grabbed="true" Expose object attribute grabbed="true" 
aria-grabbed is undefined (default) Expose object attribute grabbed="false" Expose object attribute grabbed="false" 
aria-haspopup="true"Expose as STATE_SYSTEM_HASPOPUP. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU. Expose state of the pop-up activities in the ExpandCollapseState property in the ExpandCollapse Control Pattern.Expose as object attribute haspopup="true"Expose AXShowMenu action
aria-haspopup="false" (default)Clear the HASPOPUP state. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU    
aria-hidden (state)="true" (state)This is not used in mapping to platform accessibility APIs. Instead, use information from the browser core to determine if the element is hidden or not. Advisory: it is incorrect use of WAI-ARIA if an element with aria-hidden (state)="true" is visible. The aria-hidden property is exposed only so that DOM-based assistive technologies can be informed of visibility changes. However, the browser core will be able to provide the most complete set of all truly hidden nodes.    
aria-hidden (state)="false" (state) (default)This is not used in mapping to platform accessibility APIs. Instead, use information from the browser core to determine if the element is hidden or not. Advisory: it is incorrect use of WAI-ARIA if an element with aria-hidden (state)="true" is visible. The aria-hidden property is exposed only so that DOM-based assistive technologies can be informed of visibility changes. However, the browser core will be able to provide the most complete set of all truly hidden nodes.    
aria-invalid (state)="true", "spelling", or "grammar" (state) Set IA2_STATE_INVALID_ENTRY.

Expose the value as a text attribute (not object attribute).

Expose status in IsDataValidForForm propertyExpose the value as a text attribute (not object attribute). 
aria-invalid (state)="false" (state) (default) Clear IA2_STATE_INVALID_ENTRY or equivalent state.Expose status in IsDataValidForForm property  
aria-labelExpose in accessible name    
aria-labelledby Expose a reference to the accessible object in IA2_RELATION_LABELLED_BY

Expose reverse relations as described in Relations and compute the accessible name as described in Name Computation

Expose a reference to the accessible object in the LabeledBy property.Expose a reference to the accessible object in RELATION_LABELLED_BY

Expose reverse relations as described in Relations and compute the accessible name as described in Name Computation

 
aria-levelExpose the level by accValue property of an outline object. The structure should be reflected in the accessible tree as directed by aria-level.Expose as object attribute "level" and in groupPosition.

May affect RELATION_NODE_CHILD_OF when used on a tree item. See section Group Position.

The tree hierarchy should be represented in the Automation Element structure as directed by aria-level.Expose as object attribute "level" 
aria-live="polite" or "assertive" Expose as object attribute "live".

Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.

 Expose as object attribute "live".

Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.

 
aria-live="off" (default) Expose as object attribute "live".

Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.

 Expose as object attribute "live".

Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.

 
aria-multiline="true" Set the IA2_MULTI_LINE state and clear IA2_SINGLE_LINE Expose ATK_STATE_MULTI_LINEReport "textbox" role as AXTextArea
aria-multiline="false" (default) Clear the IA2_MULTI_LINE state, and set IA2_SINGLE_LINE  Report "textbox" role as AXTextArea
aria-multiselectable="true"Set the MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match MULTISELECTABLE.Expose the AccessibleSelection interface. See Selection.Set CanSelectMultiple property on the Selection Control Pattern.Expose ATK_STATE_MULTISELECTABLE 
aria-multiselectable="false" (default)Clear the MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match MULTISELECTABLE.Expose the AccessibleSelection interface. See Selection.   
aria-orientation="horizontal" Set IA2_STATE_HORIZONTAL Set ATK_STATE_HORIZONTAL 
aria-orientation="vertical" (default) Clear IA2_STATE_HORIZONTAL Set ATK_STATE_VERTICAL 
aria-ownsthe structure should be reflected in the accessible tree as directed by aria-owns.IA2_RELATION_PARENT_WINDOW_OF

Expose reverse relations as described in Relations

The structure should be reflected in the accessible tree as directed by aria-owns.RELATION_PARENT_WINDOW_OF

Expose reverse relations as described in Relations

 
aria-posinset.The structure should be reflected in the accessible tree as directed by aria-posinset.Expose as object attribute "posinset" and in groupPosition.The structure should be reflected in the accessible tree as directed by aria-posinset.Expose as object attribute "posinset". 
aria-pressed="true" (state)Set the STATE_SYSTEM_PRESSED state.If on a button (WAI-ARIA/HTML/XUL), expose the role as IA2_ROLE_TOGGLE_BUTTON.

Expose object attribute checkable="true"

Expose as ToggleState property of Toggle Control PatternIf on a button (WAI-ARIA/HTML/XUL), expose the role as ATK_ROLE_TOGGLE_BUTTON.

Expose object attribute checkable="true"

 
aria-pressed (state)="mixed" (state)Set the STATE_SYSTEM_PRESSED state.If on a button (WAI-ARIA/HTML/XUL), expose the role as IA2_ROLE_TOGGLE_BUTTON.

Expose object attribute checkable="true"

Expose as ToggleState property of Toggle Control PatternExpose ATK_STATE_INDETERMINATE/STATE_SYSTEM_MIXED. If on a button (WAI-ARIA/HTML/XUL), expose the role as ATK_ROLE_TOGGLE_BUTTON.

Expose object attribute checkable="true"

 
aria-pressed (state)="false" (state)Clear the STATE_SYSTEM_PRESSED stateIf on a button (WAI-ARIA/HTML/XUL), expose the role as IA2_ROLE_TOGGLE_BUTTON.

Expose object attribute checkable="true"

Expose as ToggleState property of Toggle Control PatternIf on a button (WAI-ARIA/HTML/XUL), expose the role as ATK_ROLE_TOGGLE_BUTTON.

Expose object attribute checkable="true"

 
aria-pressed is undefined (state) (default)     
aria-readonly="true"Expose as STATE_SYSTEM_READONLYIf on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY If on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY 
aria-readonly="false" (default)Expose as STATE_SYSTEM_READONLYIf on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY If on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY 
aria-relevant="additions", "removals", "text", or "all" Expose as object attribute "relevant".

Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility.

 Expose as object attribute "relevant".

Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility.

 
aria-relevant="additions text" (Default) Expose the value in an object attribute called "relevant". Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility. Expose the value in an object attribute called "relevant". Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility. 
aria-required Expose IA2_STATE_REQUIREDExpose as IsrequiredForForm property.Expose ATK_STATE_REQUIRED 
aria-selected (state)="true" (state)Expose STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

If not DISABLED, toggle between "true" and "false" as appropriate when the AccessibleSelection interface is used on an ancestor with aria-multiselectable as described in Selection.Expose IsSelected property on SelectionItem Control Pattern.

The availability of the SelectionItem Control Pattern indicates the item is selectable.

If not DISABLED, toggle between "true" and "false" as appropriate when the AccessibleSelection interface is used on an ancestor with aria-multiselectable as described in Selection. Expose ATK_STATE_SELECTEDSet AXSelected attribute
aria-selected (state)="false" (state)Clear STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

If not DISABLED, toggle between "true" and "false" as appropriate when the AccessibleSelection interface is used on an ancestor with aria-multiselectable as described in Selection.  Set AXSelected attribute
aria-selected is undefined (state) (default)     
aria-setsize Expose object attribute "setsize" and in groupPosition. Expose object attribute "setsize". 
aria-sort="ascending" or "descending" Expose as object attribute "sort" Expose as object attribute "sort" 
aria-sort="none" (default) Expose as object attribute "sort" Expose as object attribute "sort" 
aria-valuemax Expose via AccessibleValue interface.

See Widget values for additional information

Expose the Maximum property in RangeValue Control Pattern

See Widget values for additional information

Expose via AccessibleValue interface.

See Widget values for additional information

set AXMaxValue attribute

See Widget values for additional information

aria-valuemin Expose via AccessibleValue interface

See Widget values for additional information

Expose the Minimum property in RangeValue Control Pattern

See Widget values for additional information

Expose via AccessibleValue interface

See Widget values for additional information

Set AXMinValue attribute

See Widget values for additional information

aria-valuenowIf aria-valuetext is not defined, expose via IAccessible::get_accValueExpose via AccessibleValue interface. If aria-valuetext is undefined, expose a string version of the aria-valuenow in the "valuetext" object attribute.

See Widget values for additional information

Expose Value property in RangeValue Control Pattern

See Widget values for additional information

Expose via AccessibleValue interface. If aria-valuetext is undefined, expose a string version of the aria-valuenow in the "valuetext" object attribute.

See Widget values for additional information

Set AXValue and post NSAccessibilityValueChangedNotification if necessary

See Widget values for additional information

aria-valuetextExpose via IAccessible::get_accValueExpose in "valuetext" object attribute

See Widget values for additional information

Expose Value property in Value Control Pattern which can co-exist with RangeValue Control Pattern.

See Widget values for additional information

Expose in "valuetext" object attribute

See Widget values for additional information

Set NSAccessibilityValueDescriptionAttribute to aria-valuetext string.

See Widget values for additional information

4.6. Special Processing Requiring Additional Computation

4.6.1. Name and Description

4.6.1.1. Text Alternative Computation

The text alternative is reused in both the name and description computation, as described below. There are different rules provided for several different types of nodes and combinations of markup. Text alternatives are built up, when appropriate, from all the relevant content contained within an element. This is accomplished via rule 2D (which is recursive), using the full set of rules to retrieve text from its own children.

To compute the text alternative for an element:

  1. Skip hidden elements unless the author specifies to use them via an aria-labelledby or aria-describedby being used in the current computation. By default, users of assistive technologies won't receive the hidden information, but an author will be able to explicitly override that and include the hidden information.
  2. For any non-skipped elements:
    1. Authors MAY specify an element's text alternative in content attributes, used in this order of preference:
      • The aria-label attribute, which defines an explicit text string, takes precedence as the element's text alternative.
      • If aria-label is empty or undefined, the aria-labelledby attribute is used unless this computation is already occurring as the result of a recursive aria-labelledby declaration (in other words, aria-labelledby is not recursive, so it will not cause loops). The text alternatives for all the elements referenced will be computed using this same set of rules. User agents will then trim whitespace and join the substrings using a single space character. Substrings will be joined in the order specified by the author (IDREF order in the aria-labelledby attribute).
      • If aria-label and aria-labelledby are empty or undefined, check for the presence of an equivalent host language attribute or element for associating a label, and use those mechanisms to determine a text alternative. For example, in HTML, the img element's alt attribute defines a label string and the label element references the form element it labels.
    2. Authors sometimes embed a control within the label of another widget, where the user can adjust the embedded control's value. For example, consider a check box label that contains a text input field: "Flash the screen [input] times". If the user has entered "5" for the embedded text input, the complete label is "Flash the screen 5 times". For such cases, include the value of the embedded control as part of the text alternative in the following manner:
      • If the embedded control is a text field, use its value.
      • If the embedded control is a menu, use the text alternative of the chosen menu item.
      • If the embedded control is a select or combobox, use the chosen option.
      • If the embedded control is a range (e.g. a spinbutton or slider), use the value of the aria-valuetext attribute if available, or otherwise the value of the aria-valuenow attribute.
    3. Otherwise, if the attributes checked in rules A and B didn't provide results, text is collected from descendant content if the current element's role allows "Name From: contents." The text alternatives for child nodes will be concatenated, using this same set of rules. This same rule may apply to a child, which means the computation becomes recursive and can result in text being collected in all the nodes in this subtree, no matter how deep they are. However, any given descendant subtree may instead collect their part of the text alternative from the preferred markup described in A and B above. These author-specified attributes are assumed to provide the correct text alternative for the entire subtree. All in all, the node rules are applied consistently as text alternatives are collected from descendants, and each containing element in those descendants may or may not allow their contents to be used. Each node in the subtree is consulted only once. If text has been collected from a child node, and is referenced by another IDREF in some descendant node, then that second, or subsequent, reference is not followed. This is done to avoid infinite loops.
    4. The last resort is to use text from a tooltip attribute (such as the title attribute in HTML). This is used only if nothing else, including subtree content, has provided results.
  3. Text nodes are often visited because they are children of an element that uses rule 2C to collect text from its children. However, because it is possible to specify textual content using the CSS :before and :after pseudo-elements, it is necessary for user agents to combine such content with the text referenced by the text nodes to produce a complete text alternative.

The purpose of the flat text alternative string is to create a perceivable label in alternative presentations. At each step of the algorithm, an implementation will trim the existing text alternative string and the string to be added, then join those two strings with a single space. For example, a space character may be inserted between the text of two elements used one after the other in a description.

4.6.1.2. Name Computation

If aria-label is not present but aria-labelledby is present, the user agent MUST compute the name by concatenating the text alternative of each element referenced by the IDs in the aria-labelledby attribute, in sequential order, with a space delimeter between each text alternative.

Otherwise, aria-labelledby will not be used, and the accessible name MUST be computed using the text alternative computation on the current element.

If the element is an <img> and the computed text alternative is empty, then check for the presence of role presentation or any labeling attribute, specifically aria-label, aria-labelledby, alt or title. The presence of any of these indicates the author's intention to indicate that the <img> is decorative or redundant. In this case, the user agent MUST set the name to an empty string. If none of these attributes are present, this indicates the author simply did not provide an accessible label for the image, and the implementation MUST return an accessible name of NULL instead of an empty string if the API supports it. This hints to the AT to do its own heuristic processing to repair the missing accessible name.

4.6.1.3. Description Computation

To compute the accessible description for an element, start with an empty string:

If aria-describedby is present, collect the description from the elements pointed to by aria-describedby. Process the IDs in aria-describedby in the order they occur. Ignore IDs that are not specified on an element in the document. For each ID use the text alternative computation.

4.6.2. Widget Values

Widgets that have a particular value within a range of values, such as progressbar, spinbutton, and slider, use aria-valuemin and aria-valuemax to specify the range of valid values, aria-valuenow to specify the current value, and optionally aria-valuetext to specify a text string equivalent for the current value.

If the value is not set on a control that requires value, then current value SHOULD return an error.

When the user or assistive technology sets the value on an object that is not readonly or disabled, the user agent SHOULD set aria-valuenow to reflect the new value. The implementation SHOULD reject values which are less than the aria-valuemin or greater than the aria-valuemax. In the case of an invalid aria-valuenow attribute, an error may be reported to the debugging console but should not be reported through the API. If the value cannot be set because the object is readonly or disabled or the new value would be out of bounds, the user agent SHOULD throw an exception rather than set the value.

When assistive technology requests the current value, user agents are not required to ensure that aria-valuenow is greater than aria-valuemin and less than aria-valuemax.

If an element has the aria-valuetext property set, but not aria-valuenow, expose the string in aria-valuetext as specified in State and Property Mapping, but return an error for any value getter that only returns a numeric type.

4.6.3. Relations

Often in a GUI, there are relationships between the widgets that can be exposed programmatically to assistive technology. WAI-ARIA provides several relationship properties which are globally applicable to any element. Therefore, it is not important to check the role before computing them.

Both forward and reverse relationship can be defined. A forward relation exists when an element has properties that refer to the ID of another element. User agents MUST map forward relations to accessibility APIs as defined in State and Property Mapping. A reverse relation exists when an element's ID is referenced by a property in another element. The following table defines the API mapping when an element's ID is referenced by a relation property of another element.

Reverse relation mapping table
WAI-ARIA RelationMSAAIAccessible2 (if different from MSAA)UI AutomationATKMAC Accessibility
aria-controls references the element's ID IA2_RELATION_CONTROLLED_BY RELATION_CONTROLLED_BY 
aria-describedby references the element's ID IA2_RELATION_DESCRIPTION_FOR RELATION_DESCRIPTION_FOR 
aria-flowto references the element's ID IA2_RELATION_FLOW_FROM RELATION_DESCRIPTION_FOR 
aria-labelledby references the element's ID IA2_RELATION_LABEL_FOR RELATION_DESCRIPTION_FOR 
aria-owns references the element's ID IA2_RELATION_NODE_CHILD_OF RELATION_DESCRIPTION_FOR 

If both aria-labelledby and HTML <label for=> are used, the WAI-ARIA relation wins and the HTML label relation is ignored.

4.6.3.1. Additional implied reverse relations for IAccessible2 and ATK

In addition to the explicit relationships defined by WAI-ARIA properties, IAccessible2 and ATK reverse relations are implied in two other situations: elements with role="treeitem" where the ancestor does not have an aria-owns property and descendents of elements with aria-atomic property.

In the case of role="treeitem", when aria-owns is not used:

  • If the current treeitem uses aria-level, then walk backwards in the tree until a treeitem is found with a lower aria-level, then set RELATION_NODE_CHILD_OF to that element. If the top of the tree is reached, then set RELATION_NODE_CHILD_OF to the tree element itself.
  • If the parent of the treeitem has a role of group, then walk backwards from the group until an element with a role of treeitem is found, then set RELATION_NODE_CHILD_OF to that element.

In the case of aria-atomic:

  • User agents SHOULD check the chain of ancestor elements for aria-atomic="true". If found, user agents SHOULD set the RELATION_MEMBER_OF relation to point to the ancestor that sets aria-atomic="true".
4.6.3.2. ID Reference Error Processing

User agents should ignore ID references that do match the ID of another element in the same document.

It is the web author's responsibility to ensure that IDs are unique. If more than one element has the same ID, the user agent should use the first element found with the given ID. The behavior will be the same as getElementById.

If the same element is specified multiple times in a single WAI-ARIA relation, user agents should return multiple pointers to the same object.

aria-activedescendant is defined as referencing only a single ID reference. If more than one ID is specified for aria-activedescendant, the user agent should use the whole string to search for an element that has that ID. For instance, aria-activedescendant="foo bar" would match an element with id="foo bar".

4.6.4. Group Position

aria-level, aria-posinset, and aria-setsize are all 1-based. When the property is not present or is "0", it indicates the property is not computed or not supported. If any of these properties are specified by the author as either "0" or a negative number, user agents SHOULD use "1" instead. If aria-posinset is larger than aria-setsize, use aria-setsize for aria-posinset.

If aria-level is not provided or inherited for an element of role treeitem, user agents MUST compute it by following the explicit or computed RELATION_NODE_CHILD_OF relations as described in Relations.

If aria-posinset and aria-setsize are not provided, user agents MUST compute them as follows:

  • for role="treeitem", walk the tree backward and forward until the explicit or computed level becomes less than the current item's level. Count items only if they are at the same level as the current item.
  • Otherwise, walk backward and forward within the DOM parent, counting items that have the same role.
  • aria-posinset includes the current item and items before it in the group. aria-setsize adds to that the number of items in the same group after the current item.

Because these values are 1-based, the current item must be included in the computation. For aria-posinset, add items only if they are before the current item in the DOM. For aria-setsize, also add items after the current item in the DOM.

4.7. Actions

Actions are exposed by the following rules

In MSAA, an action can be mapped to the DoDefaultAction and DefaultAction properties unless it is already supported by the baseline mapping (e.g., "jump" action for the hyperlink element).

In UIA, an action can be mapped to the Invoke pattern, unless it is already supported by the baseline mapping.

In IAccessible2, an action can be exposed by the AccessibleAction interface.

Table of WAI-ARIA Roles that have actions associated with them
WAI-ARIA RoleDefault actionMSAA EventUIA Event
buttonpressEVENT_OBJECT_STATECHANGE 
checkboxcheck/uncheckEVENT_OBJECT_STATECHANGE 
comboboxopen/close  
linkjump  
listitemselect/unselect if parent role is listbox  
menuitemclickDoDefaultAction 
menuitemcheckboxclick  
menuitemradioclick  
optionselect/unselect  
radioselect  
scrollbar (sub-parts)scrollEVENT_OBJECT_CONTENTSCROLLEDVerticalScrollPercentProperty or HorizontalScrollPercentProperty property change on the associated scroll bars
tabswitch  
textboxactivate  
treeitemactivate + expand/collapse  
Table of WAI-ARIA States and Properties that cause elements to have actions associated with them
WAI-ARIA State or PropertyActionsEventsNotes
aria-activedescendantclick, activate, invoke (UIA)focus, blurAdd focused and focusable API states
aria-dropeffectShift-F10, right clickfocus, blurpopup collection of actions the user can perform
focusable
Should have a navigation dialog for all hit targets and landmarks
Should have style sheet to highlight all targets
aria-expandedclick, arrow keyexpansion eventsEditorial note: interested in exploring expand/collapse
aria-grabbedif grabbable, expose grab action
if grabbed, targets become focusable
MSAA: EVENT_SYSTEM_DRAGDROPSTART, EVENT_SYSTEM_DRAGDROPENDfocusable, selectable
if aria-grabbed="true", change to focused, collection of drop targets will become focusable
aria-haspopupdisplay popup menuSee Menus in MSAA/IAccessible2/UIA 
aria-live update 
aria-relevant  live region, what's relevant to listen for?
what events the API should be supporting
aria-selected selection 
aria-sortclick  

4.8. Events

User agents must fire events for user actions, WAI-ARIA, state changes, changes to document content or node visibility, changes in selection and operation of menus. User agents SHOULD not fire events for property changes unless the accessibility API defines an event for the particular property change.

4.8.1. State and Property Change Events

For dynamic WAI-ARIA state and property changes, user agents MUST expose an event, such as state change, to indicate the change occurred. For simplicity and performance the user agent MAY trim out change events for state or property changes that assistive technologies typically ignore. An event MUST be fired for changes in:

  • aria-disabled: this will affect ENABLED and SENSITIVE states
  • aria-checked or aria-pressed: this will affect the CHECKED state. A state change for MIXED/INDETERMINATE SHOULD also be fired when the value changes to or from "mixed".
  • aria-invalid: this will affect the INVALID_ENTRY state. Note that this is different from the INVALID state in some APIs which means no valid state.
  • aria-expanded, aria-readonly, aria-required: these will affect the states of similar names in the accessibility APIs

Other types of changes:

Table of events to be fired in each API for changes in WAI-ARIA states and properties
State or PropertyMSAA eventIAccessible2 event (if different from MSAA)UIA eventATK eventApple Event
aria-busy     
aria-checkedEVENT_OBJECT_STATECHANGE ToggleStateProperty  
aria-disabledEVENT_OBJECT_STATECHANGE    
aria-expandedEVENT_OBJECT_STATECHANGE    
aria-grabbedEVENT_OBJECT_SELECTION    
aria-hiddenEVENT_OBJECT_SELECTION, EVENT_OBJECT_HIDE, EVENT_OBJECT_SHOW StructureChangedEvent  
aria-invalid     
aria-pressed     
aria-readonlyEVENT_OBJECT_STATECHANGE    
aria-required     
aria-selected     
aria-valuenow  ValueProperty property change  

4.8.2. Changes to document content or node visibility

Processing document changes is important regardless of WAI-ARIA. It is described here, however, because it is so crucial to enable Ajax and other use cases that often go along with WAI-ARIA markup.

In UIA, fire the extChangedEvent, TextSelectionChangedEvent, or PropertyChanged event for the corresponding property. For example, when there is a change to the inner text of an element that supports the Text Control Pattern, fire the TextChangedEvent. For an element that supports the Value Pattern, and maps the inner text to the Value property of the pattern, fire the PropertyChanged event for the Value property.

Table of document change scenarios and events to be fired in each API
ScenarioMSAA eventIAccessible2 event (if different from MSAA)UIA eventATK eventApple Event
When text is removed IA2_EVENT_TEXT_REMOVEDTextPattern..::.TextChangedEventtext_changed:delete 
When text is inserted IA2_EVENT_TEXT_INSERTEDextPattern..::.TextChangedEventtext_changed:insert 
When text is changedfire a removal event followed by an insertion eventfire a removal event followed by an insertion eventfire a removal event followed by an insertion eventfire a removal event followed by an insertion eventfire a removal event followed by an insertion event

Fire these events for node changes where the node in question is an element and has an accessible object:

Table of document change scenarios and events to be fired in each API
ScenarioMSAA eventIAccessible2 event (if different from MSAA)UIA eventATK eventApple Event
When a subtree is hidden

Depends on aria-relevant?
EVENT_OBJECT_HIDE
The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and ATs avoid it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed.
 AutomationElement..::.StructureChangedEventchildren_changed:remove 
When a subtree is removed

Depends on aria-relevant?
EVENT_OBJECT_REORDER
The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and ATs avoid it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed.
 AutomationElement..::.StructureChangedEventchildren_changed:remove 
When a subtree is shownEVENT_OBJECT_SHOW  children_changed:add 
When a subtree is insertedEVENT_OBJECT_REORDER  children_changed:add 
When a subtree is movedtreat it as a removal from one place and insertion in another and
fire EVENT_OBJECT_REORDER on the parent
 treat it as a removal from one place and insertion in anothertreat it as a removal from one place and insertion in anothertreat it as a removal from one place and insertion in another
When a subtree is changed (e.g. replaceNode)treat it as a removal and insertion and
fire EVENT_OBJECT_REORDER on the parent
 treat it as a removal and insertiontreat it as a removal and insertiontreat it as a removal and insertion

For node changes where the node is not an element or has no accessible object:

  • This will likely affect the text output by the AccessibleText interface. Compute and fire relevant text change events as described above.
  • There may be accessible descendants. The appropriate show/hide/children_changed events MUST be fired for the first-line descendants with accessible objects.

When firing any of the above-mentioned change events, it is very useful to provide information about whether the change was caused by user input (as opposed to a timeout initiated from the page load, etc.). This allows the AT to have different rules for presenting changes from the real world as opposed to from user action. Mouse hovers are not considered explicit user input because they can occur from accidental bumps of the mouse.

To expose whether a change occurred from user input:

  • In ATK this can be provided by appending the string ":system" to the event name when the user did not cause the change.
  • In IAccessible2, which screen readers typically access in process on the same thread, the best practice is to expose the object attribute "event-from-user-input=true" on the accessible object for the event, if the user caused the change.

Exposing additional useful information about the context of the change:

  • The RELATION_MEMBER_OF relation on the accessible event object SHOULD point to any ancestor with aria-atomic="true" (if any).
  • The container-live, container-relevant, container-busy, container-atomic object attributes SHOULD be exposed on the accessible event object, providing the computed value for the related WAI-ARIA properties. The computed value is the value of the closest ancestor. It is recommended to not expose the object attribute if the default value is used.

Additional MSAA events may be necessary:

  • If something changes in an ancestor with a mapped MSAA role of ROLE_SYSTEM_ALERT, then an EVENT_SYSTEM_ALERT event SHOULD be fired for the alert. The alert role has an implied value of "assertive" for the aria-live property.
  • Menu events may need to be fired. See Menus in MSAA/IAccessible2.

4.8.3. Selection

There are two cases for selection:

  • Single selection
  • Multiple selection

In the single selection case, it is not always necessary to manage selection events and states separate from focus, since selection mirrors focus. One exception is for tab lists. In the case of a tab, if either the tab or its associated tabpanel has focus, then the tab is considered to be SELECTED. To implement this, the user agent can walk up the parent chain from the focus until it finds a tabpanel, then traverse the aria-labelledby relation from the tabpanel to the related tab, and mark the found tab as focused.

The multiple selection case occurs when aria-multiselectable="true" on an element with a role that supports that property. There are several important aspects:

  1. Expose the correct states on the container: MULTISELECTABLE and, in MSAA, it is also EXTSELECTABLE
  2. In UIA, the Selection and SelectionItem Control Patterns expose the selection availability, state, and methods.
  3. In IAccessible2, support the AccessibleSelection interface on the container with aria-multiselectable.
  4. The selection interface can be used by an AT to actually set the selection on a descendant. This SHOULD fail for the specified descendant if aria-selected is undefined, which indicates the element is not SELECTABLE. It SHOULD also fail if the specified descendant is DISABLED or READONLY for any reason. When clearing selection on an item, set aria-selected="false" but do not remove the attribute, so that it is still SELECTABLE.
  5. Fire the correct events when aria-selected changes on a descendant, as follows:
ScenarioMSAA/IA2UI AutomationATK/AT-SPI
Toggle aria-selectedEVENT_OBJECT_SELECTIONADD/EVENT_OBJECT_SELECTIONREMOVE on the current container + EVENT_OBJECT_STATECHANGE on the itemSelectionItem Control Pattern; ElementSelected, ElementRemovedFromSlection, ElementAddedToSelectionobject::selection_changed + atk_object_notify_state_change on the item
Selection follows focusEVENT_OBJECT_SELECTION then state change event on newly focused item, but arrange events so state change does not occur on focused item, to avoid extra selection change announcementsFocusChangedEvent should fired but individual selection event may not happen, to avoid redundancy.object:selection_changed + atk_object_notify_state_change, but arrange events so state change does not occur on focused item, to avoid extra selection change announcements
Select or deselect many items at once:EVENT_OBJECT_SELECTIONWITHIN is all that is necessary. The state change events MAY be trimmed out for performance.Selection Control Pattern Invalidated event can be used when the container has bulk of changes or when an exact selection is not clear.object:selection_changed. The state change events MAY be trimmed out for performance

4.8.4. Menus in MSAA/IAccessible2/UIA

When using MSAA and UIA, special events are required whenever a menu is opened or closed. Because menus can be made visible or hidden using a variety of techniques, a user agent MUST ensure that they are nested and symmetrical.

ScenarioMSAA/IA2UI Automation
Open menu in menubar

Focus goes to menuitem while menu "mode" is not currently active

Menubar must be in the natural parent chain or in the one caused by aria-owns (use RELATION_NODE_CHILD_OF)

EVENT_SYSTEM_MENUSTART, then set menu "mode"MenuModeStartEvent
Focus a menu item while in "menu"modeEVENT_OBJECT_FOCUS 
Menu popup made visible

Should only be fired once until the menu is closed and opened again.

If not in menu "mode", EVENT_SYSTEM_MENUSTART, then set menu "mode"

EVENT_SYSTEM_MENUPOPUPSTART, then a focus event on a menuitem

MenuOpenedEvent, then a focus event on a menuitem
Menu popup hiddenEVENT_SYSTEMMENUPOPUPEND once only for accessible menu object and only if EVENT_SYSTEM_MENUPOPUPSTART was fired for it.MenuClosedEvent
When in menu "mode" and all menus closedEVENT_SYSTEM_MENUEND, clear menu "mode"MenuModeEndEvent
Focus moved out of menuEVENT_SYSTEM_MENUPOPUPEND, then EVENT_SYSTEM_MENUEND and clear menu "mode"MenuClosedEvent, then MenuModeEndEvent

5. Special Document Handling Procedures

This section is normative.

5.1. Documents, Handling frame and iframe elements

Computing the accessible name for an outer document accessible:

Computing the accessible name for an inner document accessible:

  1. If a sub-document, do a depth-first name computation using aria-labelledby from the <frame> or <iframe>. If the name is still empty, use the title attribute from the <frame> or <iframe>.
  2. If the name is still empty, use a depth-first name computation from aria-labelledby on the document's root WAI-ARIA node. If it is still empty use the title attribute on the root WAI-ARIA node.
  3. If the name is still empty, and the <title> element or some other means exists of getting the accessible name, use that.

Computing the accessible description for an inner document accessible:

  1. If a sub-document, do a depth-first description computation using aria-describedby from the <frame> or <iframe>.
  2. If the description is still empty, use a depth-first name computation from aria-describedby on the document's root WAI-ARIA node.

Computing container-foo on any node in a sub document: For container-live, container-atomic, container-relevant, and container-busy, inner nodes override outer nodes from within the same document, because the inner subtree is the more relevant context. However, outer documents override inner documents, because the outer document author may be different and may wish to define the context for a live iframe. Therefore:

  1. Walk the entire parent chain including that from outer documents, collecting the properties from aria-live, aria-atomic, aria-relevant, and aria-busy into the container-[property] object attribute
  2. If a node sets a given object attribute, set a state that does not allow that value to change that object attribute again within the document
  3. When entering a parent document, refresh the state to again allow override of each of these object properties

Computing other properties for an inner document accessible:

  1. For user-controlled properties (aria-selected, aria-valuenow, aria-valuetext, aria-activedescendant), use the WAI-ARIA markup on the root WAI-ARIA node only
  2. The WAI-ARIA properties on the outer document accessible take precedence, on a property-by-property basis
  3. If the outer document accessible does not set a property, the root WAI-ARIA node for the inner document is used
  4. Relations are not concatenated. If the outer document accessible sets a relation, that is used instead of anything set on the inner document's root WAI-ARIA node.

5.2. CSS Selectors

Support for attribute selectors MUST include WAI-ARIA attributes. For example, .fooMenuItem['aria-haspop=true'] would select all elements with class "fooMenuItem", and WAI-ARIA attribute "aria-haspopup" with value true. The presentation MUST be updated for dynamic changes to WAI-ARIA attributes. This allows authors to match styling with WAI-ARIA semantics.

5.3. Author Errors

In general, user agents do not do much validation of WAI-ARIA properties. Some minor validation MAY occur on request, such as making sure valid IDs are specified for WAI-ARIA relations, and enforcing things like aria-posinset being within 1 and aria-setsize, inclusive. User agents are not responsible for logical validation, such as the following:

  1. Circular references created by relations, such as specifying that two elements own each other.
  2. Correct usage with regard to DOM tree structure, such as an aria-activedescendant being a DOM-descendant of the element with the relation.
  3. Elements with WAI-ARIA roles correctly implement the specified role. For example, user agents do not verify that an element with a role of checkbox actually behaves like a checkbox.
  4. Elements that do not correctly observe required child / parent role relationships or that appear elsewhere than in their required parent.
  5. Determining whether aria-activedescendant actually points to a descendant or not.

If the author specifies a non-numeric value for a decimal or integer value type, the user agent SHOULD do the following:

If a WAI-ARIA property contains an unknown or disallowed value, expose to platform accessibility APIs as follows:

If a required aria property for a given role is missing, supply a default value as follows:

WAI-ARIA roleRequired State/PropertyDefault value
checkboxaria-pressedundefined
comboboxaria-expandedundefined
slideraria-valuemax0
slideraria-valuemin0
slideraria-valuenow?
spinbuttonaria-valuemax0
spinbuttonaria-valuemin0
spinbuttonaria-valuenow 

Most errors that occur due to WAI-ARIA are not propagated to callers. For example, finding an invalid ID in an ID reference List is not a reason to return an error code to the caller. Errors that can propagate are specific to certain WAI-ARIA properties.

  1. ChildID and aria-owns: aria-owns appends a list of children to an element. Specifying a child ID outside of the new valid range still returns an error, the same that would occur before when specifying an invalid child ID.

6. Appendices

6.1. Glossary

This section is normative.

Accessibility API

Operating systems and other platforms provide a set of interfaces that expose information about objects and events to assistive technologies. Assistive technologies use these interfaces to get information about and interact with those widgets.

Accessible object

An visible user interface object whose basic accessibility is exposed to assistive technology.

Activation behavior

The action taken when an event, typically initiated by users through an input device, causes an element to fulfill a defined role. The role may be defined for that element by the host language, or by author-defined variables, or both. The role for any given element may be a generic action, or may be unique to that element. For example, the activation behavior of an HTML or SVG <a> element shall be to cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of specifying the browsing context for the traversal (such as the current window or tab, a named window, or a new window); the activation behavior of an HTML <input> element with the type attribute value submit shall be to send the values of the form elements to an author-defined IRI by the author-defined HTTP method.

Assistive Technologies

Hardware and/or software that acts as a user agent, or along with a mainstream user agent, to meet the interface requirements of users with disabilities beyond those offered by the mainstream user agents.

Services provided by assistive technologies include alternative presentations (e.g., synthesized speech or magnified content), alternative input methods (e.g., speech recognition), additional navigation or orientation mechanisms, and content transformations (e.g., to make tables more accessible).

Assistive technologies often communicate with mainstream user agents by using and monitoring accessibility APIs.

The distinction between mainstream user agents and assistive technologies is not absolute. Many mainstream user agents provide some features to assist individuals with disabilities. The basic difference is that mainstream user agents target broad and diverse audiences that usually include people with and without disabilities, assistive technologies target users with specific disabilities. The assistance provided by assistive technologies is more specific and appropriate to the needs of its target users.

Examples of assistive technologies that is important in the context of this document include the following:

  • screen magnifiers, which are used to to enlarge and improve the visual readability of rendered text and images;
  • screen readers, which are most-often used to convey information through synthesized speech, sound iconography, or Braille;
  • text-to-speech software, which is used to convert text into synthetic speech;
  • speech recognition software, which is used to allow spoken control and dictation;
  • alternate keyboards (including head pointers, single switches, and sip/puff devices), which are used to simulate the keyboard;
  • alternate pointing devices, which are used to simulate mouse pointing and clicking.
Attribute

In this specification, attribute is used as it is in markup languages. Attributes are structural features added to elements to provide information about the states and properties of the object represented by the element.

Class

An abstract type of object.

Current node

The DOM node currently traversed in order to compute the text alternative.

Current total text

When computing the text alternative, the text alternative that has been computed up until arrival at the current DOM node.

Element

In this specification, element is used as it is in markup languages. Elements are the structural elements in markup language that contains the data profile for objects.

Event

A programmatic message used to communicate discrete changes in the state of an object to other objects in a computational system. User input to a web page is commonly mediated through abstract events that describe the interaction and can provide notice of changes to the state of a document object. In some programming languages, events are more commonly known as notifications.

Hidden

Indicates that the element is not visible or perceivable to any user.

Informative

Content provided for information purposes and not required for conformance. Content required for conformance is referred to as normative.

Inner document accessible

the accessible object representing the root WAI-ARIA node for the spawned document. It is a child of the outer document accessible.

Normative

Required for conformance. By contrast, content identified as informative or "non-normative" is not required for conformance.

Object

A "thing" in the perceptual user experience, instantiated in markup languages by one or more elements, and converted into the object-oriented pattern by user agents. Objects are instances of classes, which define the general characteristics of object instances. A single DOM object may or may not correspond with a single object in an accessibility API. An object in an accessibility API may encapsulate one or more DOM objects.

Outer document accessible

the accessible object representing the <frame>/<iframe>

Perceivable

Presentable to users in ways they can sense. References in this document relate to WCAG 2 Principle 1; content must be perceivable [WCAG20].

Property

Attributes that are essential to the nature of a given object. As such, they are less likely to change than states; a change of a property may significantly impact the meaning or presentation of an object. Properties mainly provide limitations on objects from the most general case implied by roles without properties applied.

Role

An indicator of type. The object's role is the class of objects of which it is a member. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.

Root WAI-ARIA node

the <body> or <frameset> in HTML, or the document element in all other languages.

Semantics

The meaning of something as understood by a human, defined in a way that computers can process a representation of an object, such as elements and attributes, and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.

State

A state is a dynamic property expressing characteristics of an object that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities.

Sub-document

any document created from a <frame>, <iframe> or similar mechanism. A sub-document may contain a document, an application or any widget such as a calendar pulled in from another server. In the accessible tree there are two accessible objects for this situation—one represents the <frame>/<iframe> element in the parent document, which parents a single accessible object child representing the spawned document contents.

Target Element

An element specified in a WAI-ARIA relation. For example, in aria-controls=”elem1”, “elem1” is the target element.

User Agent

Any software that retrieves and renders web content for users, such as web browsers, media players, plug-ins, and other programs including assistive technologies.

Valid ID

A specified ID for a WAI-ARIA property that satisfies the following condition:
It refers to a target element that exists in the same document as the element specifying the relation.

Widget

Discrete user interface object with which the user can interact. Widgets range from simple objects that have one value or operation (e.g., check boxes and menu items), to complex objects that contain many managed sub-objects (e.g., trees and grids).

6.2. References

[ARIA]
Accessible Rich Internet Applications (WAI-ARIA) Version 1.0. L. Seeman, M. Cooper, R. Schwerdtfeger, L. Pappas, Editors, W3C Working Draft (work in progress), 24 February 2009. This version of WAI-ARIA is available at http://www.w3.org/TR/2009/WD-wai-aria-20090224/. Latest version of WAI-ARIA available at http://www.w3.org/TR/wai-aria/.
[ARIA-PRACTICES]
WAI-ARIA Authoring Practices. L. Pappas, R. Schwerdtfeger, M. Cooper, Editors, W3C Working Draft (work in progress), 24 February 2009. This version of WAI-ARIA Authoring Practices is available at http://www.w3.org/TR/2009/WD-wai-aria-practices-20090224/. Latest version of WAI-ARIA Best Practices available at http://www.w3.org/TR/wai-aria-practices/.
[ARIA-PRIMER]
WAI-ARIA Primer. L. Pappas, R. Schwerdtfeger, M. Cooper, Editors, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA Primer is available at http://www.w3.org/TR/2008/WD-wai-aria-primer-20080204/. Latest version of WAI-ARIA Primer available at http://www.w3.org/TR/wai-aria-primer/.
[ARIA-ROADMAP]
Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap), R. Schwerdtfeger, Editor, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA Roadmap is available at http://www.w3.org/TR/2008/WD-wai-aria-roadmap-20080204/. Latest version of WAI-ARIA Roadmap available at http://www.w3.org/TR/wai-aria-roadmap/.
[HTML5]
HTML 5, I. Hickson, D. Hyatt, Editors, W3C Working Draft (work in progress), 25 August 2009, http://www.w3.org/TR/2009/WD-html5-20090825/. Latest version of HTML 5 available at http://www.w3.org/TR/html5/.
[RFC2119]
Key words for use in RFCs to indicate requirement levels, RFC 2119, S. Bradner, March 1997. Available at: http://www.rfc-editor.org/rfc/rfc2119.txt.
[WCAG20]
Web Content Accessibility Guidelines 2.0, B. Caldwell, G. Vanderheiden, L. Guarino Reid, M. Cooper, Editors, W3C Working Draft (work in progress), 11 December 2007, http://www.w3.org/TR/2007/WD-WCAG20-20071211/. Latest version of WCAG 2.0 available at http://www.w3.org/TR/WCAG20/.

6.3. Acknowledgments

The following people contributed to the development of this document.

6.3.1. Participants in the PFWG at the time of publication

  1. Jim Allan (Invited Expert, Texas School for the Blind)
  2. David Bolter (Invited Expert, University of Toronto Adaptive Technology Resource Centre)
  3. Sally Cain (Royal National Institute of Blind People)
  4. Ben Caldwell (Invited Expert, Trace)
  5. Charles Chen (Google, Inc.)
  6. Michael Cooper (W3C/MIT)
  7. James Craig (Apple, Inc.)
  8. Dimitar Denev (Frauenhofer Gesellschaft)
  9. Steve Faulkner (Invited Expert, The Paciello Group)
  10. Geoff Freed (WGBH National Center for Accessible Media)
  11. Kentarou Fukuda (IBM Corporation)
  12. Andres Gonzalez (Adobe Systems Inc.)
  13. Georgios Grigoriadis (SAP AG)
  14. Jon Gunderson (Invited Expert, UIUC)
  15. Sean Hayes (Microsoft Corporation)
  16. John Hrvatin (Microsoft Corporation)
  17. Kenny Johar (Vision Australia)
  18. Masahiko Kaneko (Microsoft Corporation)
  19. Diego La Monica (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  20. Gez Lemon (International Webmasters Association / HTML Writers Guild (IWA-HWG))
  21. Thomas Logan (HiSoftware Inc.)
  22. William Loughborough (Invited Expert)
  23. Anders Markussen (Opera Software)
  24. Matthew May (Adobe Systems Inc.)
  25. Charles McCathieNevile (Opera Software)
  26. James Nurthen (Oracle Corporation)
  27. Joshue O'Connor (Invited Expert)
  28. Simon Pieters (Opera Software)
  29. David Poehlman (Invited Expert)
  30. T.V. Raman (Google, Inc.)
  31. Gregory Rosmaita (Invited Expert)
  32. Tony Ross (Microsoft Corporation)
  33. Janina Sajka (Invited Expert, The Linux Foundation)
  34. Martin Schaus (SAP AG)
  35. Joseph Scheuhammer (Invited Expert, University of Toronto Adaptive Technology Resource Centre)
  36. Stefan Schnabel (SAP AG)
  37. Richard Schwerdtfeger (IBM Corporation)
  38. Lisa Seeman (Invited Expert, Aqueous)
  39. Cynthia Shelly (Microsoft Corporation)
  40. Andi Snow-Weaver (IBM Corporation)
  41. Henny Swan (Opera Software)
  42. Gregg Vanderheiden (Invited Expert, Trace)
  43. Gottfried Zimmermann (Invited Expert, Access Technologies Group)

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

Special thanks to Aaron Leventhal for effort and insight as he implemented a working prototype of accessibility API bindings. Special thanks to Al Gilman for his work while chair of the PFWG in bringing the ARIA technology to fruition.

Simon Bates, Chris Blouch (AOL), Judy Brewer (W3C/MIT), Christian Cohrs, Donald Evans (AOL), Becky Gibson (IBM), Alfred S. Gilman, Andres Gonzalez (Adobe), Jeff Grimes (Oracle), Barbara Hartel, Earl Johnson (Sun), Jael Kurz, Aaron Leventhal (IBM Corporation), Alex Li (SAP), Linda Mao (Microsoft), Shane McCarron (ApTest), Lisa Pappas (Society for Technical Communication (STC)), Dave Pawson (RNIB), Marc Silbey (Microsoft Corporation), Henri Sivonen (Mozilla), Vitaly Sourikov, Mike Squillace (IBM), Ryan Williams (Oracle), Tom Wlodkowski.

6.3.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 ED05CO0039. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.