1. Introduction

This section is informative.

In traditional desktop graphical user interface (GUI) applications, components 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 blind users can determine whether a particular UI component is a menu, button, text field, list box, etc.

In traditional static Web pages, the HTML elements provided the necessary semantic information. The user agent provides keyboard navigation but only to the HTML elements that are known to be interactive, specifically links and form elements. Assistive technologies obtain the semantic information from the Document Object Model (DOM) or, in the case of links and 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 re-purpose HTML elements into UI components 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. These accessibility deficiencies in traditional markup render rich Internet applications unusable by people who use assistive technologies 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 Accessible Rich Internet Applications [WAI-ARIA] specification.

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.

For an introduction to WAI-ARIA, see the WAI-ARIA Overview. The User Agent Implementation Guide describes how WAI-ARIA roles, states, and properties should be supported in user agents using platform accessibility APIs. It is part of a set of resources that define and support the WAI-ARIA specification which includes the following documents:

The WAI-ARIA User Agent Implementation Guide begins by providing a general overview of accessibility APIs and the accessible object hierarchy known as the accessibility 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 assistive technology via the accessibility API on a given platform. Most of the additional work to enable WAI-ARIA can be divided into three parts:

  1. Enabling keyboard navigation on elements that previously were not focusable
  2. Mapping the WAI-ARIA roles and attributes 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 attributes 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.

This document includes general information for user agents to handle WAI-ARIA roles, states, and properties. It also includes host-language specific requirements where necessary to complete the accessibility model, in particular for HTML 4. In the future, the PFWG may split out technology-specific versions of this guide, moving some requirements out but retaining this document as the general ARIA implementation guide.

1.1. Accessibility APIs

To provide access to desktop GUI applications, assistive technologies originally used heuristic techniques to determine the meaning of the user interface and build an alternative off-screen model. 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 about user interfaces to assistive technologies.

In the case of static Web pages, the Document Object Model (DOM) is used to represent the structure and state of the elements in the document being rendered by a user agent. The elements of the document are organized into a hierarchy of nodes known as the DOM tree. For traditional static Web pages, assistive technologies, such as screen readers, interact with user agents using the DOM. For UI elements that are known to be interactive, such as HTML form elements and desktop applications, assistive technologies may use platform accessibility APIs.

In the case of rich Internet applications, developers use DOM APIs to manipulate objects in the DOM tree to make them behave like interactive desktop GUI applications. In order to make a Web application understandable to assistive technologies, 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 information needed is provided when developers use WAI-ARIA to supply semantic role, state, and property information for elements. 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.

Accessibility APIs covered by this document are:

If user agent developers need to expose information using 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 Accessibility Tree and the DOM Tree

The accessibility tree and the DOM tree are parallel structures. Roughly speaking the accessibility 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 accessibility tree for every DOM element that should be exposed to an assistive technology, either because it may fire an accessibility 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 user agents must follow 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]. RFC-2119 keywords are formatted in uppercase and contained in a strong element with class="rfc2119". When the keywords shown above are used, but do not share this format, they do not convey formal information in the RFC 2119 sense, and are merely explanatory, i.e., informative. As much as possible, such usages are avoided in this specification.

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. Important Terms

This section is informative.

While some terms are defined in place, the following definitions are used throughout this document.

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. Examples of accessibility APIs are the Microsoft Active Accessibility [MSAA], the Microsoft User Interface Automation [UIA-ARIA], the Mac OS X Accessibility Protocol [AXAPI], the Linux/Unix Accessibility Toolkit [ATK] and Assistive Technology Service Provider Interface [AT-SPI], and IAccessible2 [IA2].

Accessibility Subtree

An accessible object in the accessibility tree and its descendants in that tree. It does not include objects which have relationships other than parent-child in that tree. For example, it does not include objects linked via aria-flowto unless those objects are also descendants in the accessibility tree.

Accessibility Tree

Tree of accessible objects that represents the structure of the user interface (UI). Each node in the accessibility tree represents an element in the UI as exposed through the accessibility API; for example, a push button, a check box, or container.

Accessible Name

The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element.

A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g. "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.

Accessible object

A user interface object whose basic accessibility is exposed to assistive technology via a platform accessibility API. Accessible objects are included in the accessibility tree. MS UIA represents accessible objects as automation elements.

Assistive Technologies

Hardware and/or software that:

  • relies on services provided by a user agent to retrieve and render Web content
  • works with a user agent or web content itself through the use of APIs, and
  • provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities

This definition may differ from that used in other documents.

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

  • screen magnifiers, which are used 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 or a refreshable Braille display;
  • 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 input technologies (including head pointers, on-screen keyboards, 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

A set of instance objects that share similar characteristics.

Desktop focus event

Event from/to the host operating system via the accessibility API, notifying of a change of input focus.

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. An element is only considered hidden in the DOM if it or one of its ancestor elements has the aria-hidden (state) attribute set to true.

Note: Authors are reminded that visibility:hidden and display:none apply to all CSS media types; therefore, use of either will hide the content from assistive technologies that access the DOM through a rendering engine. However, in order to support assistive technologies that access the DOM directly, or other authoring techniques to visibly hide content (for example, opacity or off-screen positioning), authors need to ensure the aria-hidden attribute is always updated accordingly when an element is shown or hidden, unless the intent of using off-screen positioning is to make the content visible only to screen reader users and not others.

Informative

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

Keyboard Accessible

Accessible to the user using a keyboard or assistive technologies that mimic keyboard input, such as a sip and puff tube. References in this document relate to WCAG 2 Guideline 2.1; "Make all functionality available from a keyboard" [WCAG20].

Live Region

Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere. These regions are not always updated as result of a user interaction. This practice has become commonplace with the growing use of Ajax. Examples of live regions include a chat log, stock ticker, or a sport scoring section that updates periodically to reflect game statistics. Since these asynchronous areas are expected to update outside the user's area of focus, assistive technologies such as screen readers have either been unaware of their existence or unable to process them for the user. WAI-ARIA has provided a collection of properties that allow the author to identify these live regions and how to process them: aria-live, aria-relevant, aria-atomic, and aria-busy. Pre-defined live region roles are listed in the Choosing Between Special Case Live Regions ([ARIA-PRACTICES], Section 5.3).

Managed State

Accessibility API state that is controlled by the user agent, such as focus and selection. These are contrasted with "unmanaged states" that are typically controlled by the author. Nevertheless, authors can override some managed states, such as aria-posinset and aria-setsize. Many managed states have corresponding CSS pseudo-classes, such as :focus, and pseudo-elements, such as ::selection, that are also updated by the user agent.

Normative

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

Object

In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or more elements, and rendered by user agents.

In the context of programming, the instantiation of one or more classes and interfaces which define the general characteristics of similar objects. An object in an accessibility API may represent one or more DOM objects. Accessibility APIs have defined interfaces that are distinct from DOM interfaces.
Ontology

A description of the characteristics of classes and how they relate to each other.

Owned Element

An 'owned element' is any DOM descendant of the element, any element specified as a child via aria-owns, or any DOM descendant of the owned child.

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, or that represent a data value associated with the object. A change of a property may significantly impact the meaning or presentation of an object. Certain properties (for example, aria-multiline) are less likely to change than states, but note that the frequency of change difference is not a rule. A few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often. See clarification of states versus properties.

Relationship

A connection between two distinct things. Relationships may be of various types to indicate which object labels another, controls another, etc.

Role

Main indicator of type. 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.

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. See clarification of states versus properties.

Understandable

Presentable to users in ways they can construct an appropriate meaning. References in this document relate to WCAG 2 Principle 3; Information and the operation of user interface must be understandable [WCAG20].

User Agent

Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.

Valid IDREF

A reference to a target element in the same document that has a matching ID

Value

A literal that solidifies the information expressed by a state, property, role, or text content.

acrWidget

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).

4. 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 provide a mechanism for authors to specify that any renderable element may be focusable without placing the element in a pre-defined tabbing order. In HTML for example, tabindex is used to provide this function.

User agents MUST also provide programmatic access to all focusable elements. This allows for device-independent access, is needed to conform to the User Agent Accessibility Guidelines [UAAG], 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. In rich internet applications, 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. In addition to host language mechanisms such as tabindex in HTML, aria-activedescendant provides another mechanism for keyboard operation. 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. User agents need to allow assistive technologies to set the focus. See the section titled "Handling focus changes from the Assistive Technology" for details.

4.1. Focus States and Events Table

The following table defines the accessibility API keyboard focus states and events used in later sections of the document.

  • If the context is controlling focus with tabindex, the DOM focus (document.activeElement) is in sync with the focus states and events listed in the table.
  • If the context is controlling focus with aria-activedescendant, the DOM focus is separate from the focus states and events for the MSAA, and ATK/AT-SPI columns of the table.

    Note: An example is a single-selection listbox that controls focus using aria-activedescendent instead of tabindex. The option children are all marked with the focusable state in the accessibility API. As the user navigates from one option child to the next, DOM focus is maintained on the listbox parent, but the accessibility API emits a focus event and exposes the focused state for the option child that the listbox references as the active descendant.

Table of accessibility APIs for focus states and events
 MSAAATK/AT-SPIMac OS X Accessibility
Focusable stateSTATE_SYSTEM_FOCUSABLESTATE_FOCUSABLEboolean AXFocused (writable)
Focused stateSTATE_SYSTEM_FOCUSEDSTATE_FOCUSEDboolean AXFocused
Focus eventEVENT_OBJECT_FOCUSobject:state-changed:focused or focus:AXFocusedUIElementChanged

4.2. Controlling focus with tabindex

Editorial Note: this section is specific to HTML only and may be moved to the HTML Implementation Guide.

User agents that support WAI-ARIA for HTML 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 is focusable 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, treeview or grid.

Note: refer to the Table of accessibility APIs for focus states and events for the rules in this section.

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

  1. Where tabindex equals a negative integer, set the focusable state, but do not include the element in the sequential tab order.
  2. Where tabindex="0", set the focusable state and include it in the sequential tab order.
  3. Where tabindex is greater than zero, set the focusable state, and 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 [HTML5] for details.
  4. Expose the element.tabIndex property for every HTML element that supports the tabindex attribute.
  5. Add the focus and blur methods to the HTMLElement interface (available to script for every type of element).
  6. Fire focus, blur, DOMFocusIn, and DOMFocusOut events for any element that can receive focus.
  7. When a keydown event is cancelled, also cancel the keypress event.
  8. Expose the focusable states for any element in the accessibility tree.
  9. When any object has focus, expose the focused state. When it loses focus, remove the focused state.

4.3. Controlling focus with aria-activedescendant

When implementing aria-activedescendant as described below, the user agent keeps the DOM focus on the container element but communicates desktop focus events and states to the assistive technology as if the active descendant has focus. It is the responsibility of the user agent to ensure that keyboard events are processed at the container element that has DOM focus. Any keyboard events directed at the active descendant bubble up to the DOM element with focus, the container element, for processing.

The aria-activedescendant property may be used to enable keyboard accessibility on WAI-ARIA elements that support this attribute. 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 other keys, typically arrow keys, to navigate to descendant items of the container).

Typically, the author will use host language semantics to put the container element in the sequential tab order (tabindex="0" in HTML) 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. The author cannot use :focus to style the currently active descendant since actual focus is on the container.

Note: Refer to the Table of accessibility APIs for focus states and events for the rules in this section.

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

  1. Implement the host language method for keyboard navigation so that the container widget may be included in the tab order. For HTML implementations, see Controlling focus with tabindex.
  2. For platforms that expose desktop focus or accessibility API focus separately from DOM focus, do not expose the focused state in the accessibility API for any element when it has DOM focus and also has aria-activedescendant which points to a valid ID.
  3. When the aria-activedescendant attribute changes on an element that currently has DOM focus, remove the focused state from the previously focused object and fire an accessibility API desktop focus event on the new active descendant. If aria-activedescendant is cleared or does not point to an element in the current document, fire a desktop 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, apply the following accessibility API 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 HTML elements that would be focusable would already have the focusable state.
    2. Focused, whenever the container element sets aria-activedescendant to match the ID of this descendant and the container widget with aria-activedescendant has DOM focus.

4.4. Handling focus changes from the Assistive Technology

Assistive technologies, such as screen readers, voice input software and on-screen keyboards, might request that the keyboard focus be moved using the following accessibility APIs:

  • MSAA: accSelect(SELFLAG_TAKEFOCUS)
  • ATK/AT-SPI: AtkComponent::grab_focus
  • Mac OS X Accessibility: Notification: AXFocusedUIElementChanged

Note: Refer to the Table of accessibility APIs for focus states and events for the rules in this section.

When an assistive technology requests a change of focus using one of the above APIs, user agents MUST do the following:

  • Remove the focused state from the previously focused object.
  • If the element can take DOM focus, the user agent MUST set the DOM focus to it. Otherwise, if the current element has an ID and an ancestor with the aria-activedescendant attribute present, the user agent MUST set DOM focus to that ancestor. When it is not possible for the user agent to set DOM focus to the containing element with aria-activedescendant, the user agent MAY attempt to set DOM focus to the child element itself.
  • If the current element has an ID and an ancestor with the aria-activedescendant attribute present, the user agent MUST set the accessibility API focused state and fire an accessibility API desktop focus event on the new active descendant.

Note: the inability to set DOM focus to the containing element indicates an author error.

5. Mapping WAI-ARIA to Accessibility APIs

This section is normative.

5.1. General rules for exposing WAI-ARIA semantics

Where supported by the platform Accessibility API, user agents expose WAI-ARIA semantics 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.

With respect to WAI-ARIA 1.0, accessibility APIs operate in one direction only. User agents publish WAI-ARIA information (roles, states, and properties) via an accessibility API, and an AT can acquire that information using the same API. However, the other direction is not supported. WAI-ARIA 1.0 does not define mechanisms for assistive technologies to directly modify WAI-ARIA information.

5.1.1. Excluding Elements from the Accessibility Tree

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

  • Elements with presentation as the first mappable role in the role attribute string, according to the rules for presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [ARIA].
  • Elements, including their descendents, that have host language semantics specifying that the element is not displayed, such as CSS display:none or visibility:hidden or HTML 5 hidden attribute.

If not already excluded from the accessibility tree per the above rules, user agents SHOULD NOT include the following elements in the accessibility tree:

5.1.2. Including Elements in the Accessibility Tree

If not already excluded from the accessibility tree per the rules above in Excluding Elements in the Accessibility Tree, user agents MUST provide an accessible object in the accessibility tree for DOM elements that meet any of the following criteria:

5.1.3. Notification of State Changes

User agents notify assistive technologies of state and property changes as defined in Events.

5.2. Conflicts between native markup semantics and WAI-ARIA

WAI-ARIA roles, states, and properties are intended to add semantic information when native host language elements with these semantics are not available, and are generally used on elements that have no native semantics of their own. They can also be used on elements that have similar but not identical semantics to the intended object (for instance, a nested list could be used to represent a tree structure). This method can be part of a fallback strategy for older browsers that have no WAI-ARIA implementation, or because native presentation of the repurposed element reduces the amount of style and/or script needed. Except for the cases outlined below, user agents MUST always use the WAI-ARIA semantics to define how it exposes the element to accessibility APIs, rather than using the host language semantics.

Host languages can have features that have implicit WAI-ARIA semantics corresponding to roles. When a WAI-ARIA role is provided that has a corresponding role in the accessibility API, user agents MUST use the semantic of the WAI-ARIA role for processing, not the native semantic, unless the role requires WAI-ARIA states and properties whose attributes are explicitly forbidden on the native element by the host language. Values for roles do not conflict in the same way as values for states and properties, and because authors are expected to have a valid reason to provide a WAI-ARIA role even on elements that would not normally be repurposed. For example, spin buttons are typically constructed from text fields (<input type="text">) in order to get most of the default keyboard support. But, the native role, "text field", isn't correct because it doesn't properly communicate the additional features of a spin button. The author will add the WAI-ARIA role of spinbutton (<input type="text" role="spinbutton" ...>) so that the control gets properly mapped in the accessibility API. When a WAI-ARIA role is provided that does not have a corresponding role in the accessibility API, user agents MAY expose the native semantic in addition to the WAI-ARIA role.

Editorial Note: The above text differs slightly from the WAI-ARIA specification. The requirement for user agents to expose the WAI-ARIA role instead of the native role was intended to only apply in cases where there is a direct mapping from the WAI-ARIA role to a corresponding role in the accessibility API. The wording of the requirement is not clear in the WAI-ARIA specification, however, and has been interpreted differently by implementers. The requirement has been clarified here and an additional statement added to indicate that user agents may expose native semantics if there is not a direct mapping to a role in the accessibility API. Because there are differing implementations, authors will be advised against adding such WAI-ARIA roles to native elements that have their own semantics in the WAI-ARIA Authoring Practices Guide.

When WAI-ARIA states and properties correspond to host language features that have the same implicit WAI-ARIA semantic, it can be problematic if the values become out of sync. For example, the HTML checked attribute and the aria-checked attribute could have conflicting values. Therefore to prevent providing conflicting states and properties to assistive technologies, host languages will explicitly declare where the use of WAI-ARIA attributes on a host language element conflict with native attributes for that element. When a host language declares a WAI-ARIA attribute to be in direct semantic conflict with a native attribute for a given element, user agents MUST ignore the WAI-ARIA attribute and instead use the host language attribute with the same implicit semantic.

Host languages might also document features that cannot be overridden with WAI-ARIA (these are called "strong native semantics"). These can be features that have implicit WAI-ARIA semantics as well as features where the processing would be uncertain if the semantics were changed with WAI-ARIA. While conformance checkers might signal an error or warning when a WAI-ARIA role is used on elements with strong native semantics, user agents MUST still use the value of the semantic of the WAI-ARIA role when exposing the element to accessibility APIs.

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

Platform accessibility APIs might 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 mechanism in the API to expose the WAI-ARIA role, states, and properties and their values, user agents MUST expose the WAI-ARIA data using that mechanism as follows:

  • In IAccessible2 and ATK/AT-SPI, 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 where there is no specific interface in an accessibility API. 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 are in State and Property Mapping.
  • In Microsoft UIA Express, use the AriaRole and AriaProperties properties to expose semantics that are not directly supported in the control type.

Editorial Note: MSAA does not provide a mechanism for exposing attributes that do not map directly to the API and among implementers, there is no agreement on how to do it.

User agents MUST also expose the entire role string through this mechanism and MAY also expose WAI-ARIA attributes and values through this mechanism even when there is a direct mapping to an accessibility API.

Browser implementers are advised to publicly document their API methods for exposing any relevant information, so that assistive technology developers can use the API to support user features.

5.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.

The following rules describe how to expose WAI-ARIA roles using the accessibility API:

  1. The user agent MUST use the first token in the sequence of tokens in the role attribute value which matches, on comparison, the name of any non-abstract WAI-ARIA role according to rules that are specified in the Role Mapping Table below. See Conflicts between native markup semantics and WAI-ARIA for additional information. Note that when WAI-ARIA roles override host language semantics, there are no changes in the DOM, only in the accessibility tree. In the absence of author-supplied scripts, the presence of WAI-ARIA roles might not make sense. But user agents MUST map WAI-ARIA roles even in the absence of author-supplied scripts.

    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 a role attribute and to identify the attribute value string for it.
    2. Separate the attribute value string for that attribute into a sequence of whitespace-free substrings by separating on whitespace.
    3. Do a comparison of the substrings to all the names of the non-abstract WAI-ARIA roles. Case-sensitivity of the comparison inherits from the case-sensitivity of the host language.
    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. See the Role Mapping Table below for details.
  2. User agents MUST NOT map roles defined in the WAI-ARIA specification as "abstract" 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="foo"> use the element name table to determine what platform accessibility API role to use according to the host language's role mapping. For <input type="text" role="bar">, use the platform accessibility API for a text input.
  4. When an explicit or inherited role of presentation is applied to an element, the user agent MUST implement the rules for presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [ARIA].
  5. User agents MUST expose the WAI-ARIA role string if the API supports a mechanism to do so. This allows assistive technologies to do their own additional processing of roles.
    • MSAA: not supported
    • IAccessible2: expose as an object attribute pair (xml-roles:"string")
    • UIA Express: expose as AriaRole property. The AriaRole property can also support secondary roles using a space as a separator.
    • ATK/AT-SPI: expose as an object attribute pair (xml-roles:"string")
  6. 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, 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.

5.4.1. Role Mapping Table

Roles given in this document for ATK/AT-SPI were implemented at the time of publication. However, the maintainers of ATK and of AT-SPI have informed W3C that they have re-engineered several of the roles listed in this specification. Developers are, therefore, strongly urged to consult the most recent implementation specification draft for current, preferred values.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
WAI-ARIA roleMSAA + UIA Express roleMSAA + IAccessible2 role and other IAccessible2 featuresATK/AT-SPI role

Mac OS X

AXRole
AXSubrole
AXRoleDescription[Note 1]

alertROLE_SYSTEM_ALERT

The user agent SHOULD fire EVENT_SYSTEM_ALERT [Note 2]

ROLE_SYSTEM_ALERT

The user agent SHOULD fire EVENT_SYSTEM_ALERT [Note 2]

ROLE_ALERT

The user agent SHOULD fire a system alert event.[Note 2]

AXGroup
AXApplicationAlert
'alert'

The user agent SHOULD fire a system alert event.[Note 2]

alertdialogROLE_SYSTEM_DIALOG

The user agent SHOULD fire EVENT_SYSTEM_ALERT [Note 2]

ROLE_SYSTEM_DIALOG

The user agent SHOULD fire EVENT_SYSTEM_ALERT [Note 2]

ROLE_DIALOG

The user agent SHOULD fire a system alert event.[Note 2]

AXGroup
AXApplictionAlertDialog
'alert dialog'

The user agent SHOULD fire a system alert event.[Note 2]

applicationROLE_SYSTEM_APPLICATIONROLE_SYSTEM_APPLICATIONROLE_EMBEDDEDAXGroup
AXLandmarkApplication
'application'
articleROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLYROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY

IAccessible2: Object attribute xml-roles:article

ROLE_DOCUMENT_FRAME + do not expose STATE_EDITABLE

Object attribute xml-roles:article

AXGroup
AXDocumentArticle
'article'
bannerExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:bannerObject attribute xml-roles:bannerAXGroup
AXLandmarkBanner
'banner'
buttonROLE_SYSTEM_PUSHBUTTONROLE_SYSTEM_PUSHBUTTON

If aria-haspopup="true", expose as ROLE_SYSTEM_BUTTONMENU

IAccessible2: If aria-pressed is not undefined, it SHOULD be exposed as IA2_ROLE_TOGGLE_BUTTON

ROLE_PUSH_BUTTON

If aria-pressed (state) is not undefined, it SHOULD be exposed as ROLE_TOGGLE_BUTTON

If aria-pressed (state) is defined (true/false/mixed) use:

AXCheckBox
AXToggleButton
'toggle button'

If aria-pressed (state) is not defined use:

AXButton
<nil>
'button'
checkboxROLE_SYSTEM_CHECKBUTTONROLE_SYSTEM_CHECKBUTTON

IAccessible2: Object attribute checkable:true

ROLE_CHECK_BOX + object attribute checkable:trueAXCheckBox
<nil>
'check box'
columnheaderROLE_SYSTEM_COLUMNHEADERROLE_SYSTEM_COLUMNHEADER

IAccessible2: Used to help support AccessibleTable for the container grid role

ROLE_COLUMN_HEADER

AXCell or AXSortButton if using aria-sort
<nil>
'cell'

Parent table also implements
AXColumnHeaderUIElements property that is a
list of pointers to the column header cells.

Parent table also implements AXHeader property that is a pointer to the row or group containing the columnheader cells.

comboboxROLE_SYSTEM_COMBOBOX + STATE_SYSTEM_HASPOPUP.

If aria-expanded (state) is not "true", expose STATE_SYSTEM_COLLAPSED.

ROLE_SYSTEM_COMBOBOX + STATE_SYSTEM_HASPOPUP.

If aria-expanded (state) is not "true", expose STATE_SYSTEM_COLLAPSED.

ROLE_COMBO_BOX + STATE_EXPANDABLE + object attribute haspopup:trueAXComboBox
<nil>
'combo box'
complementaryExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:complementaryObject attribute xml-roles:complementaryAXGroup
AXLandmarkComplementary
'complementary'
contentinfoExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:contentinfoObject attribute xml-roles:contentinfoAXGroup
AXLandmarkContentInfo
'content'
definitionExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:definitionObject attribute xml-roles:definitionAXGroup
AXDefinition
'definition'
dialogROLE_SYSTEM_DIALOGROLE_SYSTEM_DIALOGROLE_DIALOGAXGroup
AXApplicationDialog
'dialog'
directoryROLE_SYSTEM_LISTROLE_SYSTEM_LISTROLE_LISTAXList
AXContentList
'content list'
documentROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLYROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLYROLE_DOCUMENT_FRAME + do not expose STATE_EDITABLEAXGroup
AXDocument
'document'
formExpose as text string in AriaRoleIAccessible2: IA2_ROLE_FORMROLE_FORMAXGroup
<nil>
'group'
gridROLE_SYSTEM_TABLEROLE_SYSTEM_TABLE

IAccessible2: Use IAccessibleTable2 interface

ROLE_TABLEAXTable
<nil>
'table'
gridcellROLE_SYSTEM_CELLROLE_SYSTEM_CELLROLE_TABLE_CELLAXCell
<nil>
'cell'
groupROLE_SYSTEM_GROUPINGROLE_SYSTEM_GROUPINGROLE_PANELAXGroup
<nil>
'group'
heading

The heading level is specified by the aria-level property.

ROLE_SYSTEM_TEXTExpose as object attribute xml-roles:heading.

Also, expose IAccessible2: IA2_ROLE_HEADING

ROLE_HEADINGAXHeading
<nil>
'heading'
imgROLE_SYSTEM_GRAPHICROLE_SYSTEM_GRAPHICROLE_IMAGEAXImage
<nil>
'image'
linkROLE_SYSTEM_LINK + STATE_LINKED

Also, expose STATE_LINKED on all descendants

ROLE_SYSTEM_LINK + STATE_LINKED

Also, expose STATE_LINKED on all descendants

IAccessible2: Use AccessibleHypertext interface
ROLE_LINKAXLink
<nil>
'link'
listROLE_SYSTEM_LIST + STATE_SYSTEM_READONLYROLE_SYSTEM_LIST + STATE_SYSTEM_READONLYROLE_LIST + do not expose STATE_EDITABLEAXList
AXContentList
'content list'

listbox

ROLE_SYSTEM_LISTROLE_SYSTEM_LISTROLE_LIST. Special case: if a listbox has a parent or is owned by (via aria-owns) a combobox, it SHOULD be exposed with ROLE_MENU.AXList
<nil>
'list'
listitemROLE_SYSTEM_LISTITEMROLE_SYSTEM_LISTITEM + STATE_SYSTEM_READONLYROLE_LISTITEM + do not expose STATE_EDITABLEAXGroup
<nil>
'group'
logControl type/role is group Localized Control Type is log. LiveSettingProperty = On (1).

IAccessible2: object attributes xml-roles:log;container-live:polite;live:polite;container-live-role:log

object attributes xml-roles:log;container-live:polite;live:polite;container-live-role:log

 

AXGroup
AXApplicationLog
'log'
mainExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:mainObject attribute xml-roles:mainAXGroup
AXLandmarkMain
'main'
marqueeROLE_SYSTEM_ANIMATION

ROLE_SYSTEM_ANIMATION +

IAccessible2: object attribute xml-roles:marquee;container-live:off;live:off

ROLE_ANIMATION + object attributes container-live:off;live:offAXGroup
AXApplicationMarquee
'marquee'
mathROLE_SYSTEM_EQUATIONROLE_SYSTEM_EQUATIONROLE_UNKNOWNAXGroup
AXDocumentMath
'math'
menuROLE_SYSTEM_MENUPOPUPROLE_SYSTEM_MENUPOPUPROLE_MENU

These objects are not exposed for a submenu if there is a parent menu item spawning the submenu. Since ATK/AT-SPI allows menuitems to have menuitem children, interposing menu objects are not exposed, except for the root parent.

AXMenu
<nil>
'menu'
menubarROLE_SYSTEM_MENUBARROLE_SYSTEM_MENUBARROLE_MENU_BARAXMenuBar
<nil>
'menu bar'
menuitemROLE_SYSTEM_MENUITEMROLE_SYSTEM_MENUITEMROLE_MENU_ITEM

If aria-checked (state) is not undefined, support object attribute checkable:true

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

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

AXMenuItem
<nil>
'menu item'

menuitemcheckboxROLE_SYSTEM_CHECKBUTTON or ROLE_SYSTEM_MENUITEMROLE_SYSTEM_CHECKBUTTON or ROLE_SYSTEM_MENUITEM

IAccessible2: IA2_ROLE_CHECK_MENU_ITEM + object attribute checkable:true

ROLE_CHECK_MENU_ITEM + object attribute checkable:true

AXMenuItem
<nil>
'menu item'

If aria-checked (state)="true": AXMenuItemMarkChar
Otherwise: AXMenuItemMarkChar <nil>

menuitemradioROLE_SYSTEM_RADIOBUTTON or ROLE_SYSTEM_MENUITEM

See "Special case" under aria-checked for mapping aria-checked (state) attribute for radio buttons.

ROLE_SYSTEM_RADIOBUTTON or ROLE_SYSTEM_MENUITEM

IAccessible2: IA2_ROLE_RADIO_MENU_ITEM + object attribute checkable:true

ROLE_RADIO_MENU_ITEM + object attribute checkable:true

AXMenuItem
<nil>
'menu item'

If aria-checked (state)="true": AXMenuItemMarkChar ✓.
Otherwise: AXMenuItemMarkChar <nil>

navigationExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:navigationObject attribute xml-roles:navigationAXGroup
AXLandmarkNavigation
'navigation'
noteExpose as text string in AriaRoleIAccessible2: IA2_ROLE_NOTEObject attribute xml-roles:noteAXGroup
AXDocumentNote
'note'
option

If aria-selected (state) is undefined treat as aria-selected = "false".

ROLE_SYSTEM_LISTITEMROLE_SYSTEM_LISTITEM

IAccessible2: If aria-checked (state) is not undefined, support object attribute checkable:true

ROLE_LIST_ITEM

If aria-checked (state) is not undefined, support object attribute checkable:true

Special case: if an option has a parent that was exposed as a ROLE_MENU, the option SHOULD be exposed as an ROLE_MENU_ITEM

AXStaticText
<nil>
'text'
presentation

See General rules for exposing WAI-ARIA semantics

If the object is in the accessibility tree, expose as ROLE_SYSTEM_PANE

See General rules for exposing WAI-ARIA semantics

If the object is in the accessibility tree, expose as ROLE_PANEL

See General rules for exposing WAI-ARIA semantics

Not mapped

See General rules for exposing WAI-ARIA semantics

progressbarROLE_SYSTEM_PROGRESSBAR + STATE_SYSTEM_READONLYROLE_SYSTEM_PROGRESSBAR + STATE_SYSTEM_READONLYROLE_PROGRESS_BAR + do not expose STATE_EDITABLEAXProgressIndicator
<nil>
'progress indicator'
radioROLE_SYSTEM_RADIOBUTTON

See "Special case" under aria-checked for mapping aria-checked (state) attribute for radio buttons.

ROLE_SYSTEM_RADIOBUTTONROLE_RADIO_BUTTONAXRadioButton
<nil>
'radio button'
radiogroupROLE_SYSTEM_GROUPINGROLE_SYSTEM_GROUPINGROLE_PANELAXRadioGroup
<nil>
'radio group'
regionROLE_SYSTEM_PANEROLE_SYSTEM_PANEROLE_PANELAXGroup
AXDocumentRegion
'region'
rowROLE_SYSTEM_ROW unless inside a tree or treegrid, in which case ROLE_SYSTEM_OUTLINEITEMROLE_SYSTEM_ROW unless inside a tree or treegrid, in which case ROLE_SYSTEM_OUTLINEITEM

IAccessible2: Used to help support: IAccessibleTable2 interface for the container grid role

ROLE_LIST_ITEMAXRow
<nil>
'row'
rowgroup

Expose as text string in AriaRole

Note: the rowgroup role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.

ROLE_SYSTEM_GROUP

Note: the rowgroup role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.

ROLE_PANEL

Note: the rowgroup role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.

Not mapped

Note: the rowgroup role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.

rowheaderROLE_SYSTEM_ROWHEADERROLE_SYSTEM_ROWHEADER

IAccessible2: Used to help support IAccessibleTable2 interface for the container grid role

ROLE_ROW_HEADER

AXCell
<nil>
'cell'

Parent table also implements AXRowHeaderUIElements property that is a list of pointers to the row header cells

scrollbarROLE_SYSTEM_SCROLLBARROLE_SYSTEM_SCROLLBARROLE_SCROLLBARAXScrollBar
<nil>
'scroll bar'
searchExpose as text string in AriaRole Object attribute xml-roles:searchAXGroup
AXLandmarkSearch
'search'
separatorROLE_SYSTEM_SEPARATORROLE_SYSTEM_SEPARATORROLE_SEPARATORAXSplitter
<nil>
'splitter'
sliderROLE_SYSTEM_SLIDERROLE_SYSTEM_SLIDERROLE_SLIDERAXSlider
<nil>
'slider'
spinbuttonROLE_SYSTEM_SPINBUTTONROLE_SYSTEM_SPINBUTTONROLE_SPIN_BUTTONAXIncrementor
<nil>
'stepper'
statusROLE_SYSTEM_STATUSBAR

ROLE_SYSTEM_STATUSBAR +

IAccessible2: object attributes container-live:polite;live:polite;container-live-role:status

ROLE_STATUSBAR + object attributes container-live:polite;live:polite;container-live-role:statusAXGroup
AXApplicationStatus
'status'
tab

If aria-selected (state) is undefined treat as aria-selected = "false".

ROLE_SYSTEM_PAGETAB.

Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby.

ROLE_SYSTEM_PAGETAB.

Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby.

ROLE_PAGE_TAB. Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby.AXRadioButton
<nil>
'tab'
tablistROLE_SYSTEM_PAGETABLIST

ROLE_SYSTEM_PAGETABLIST +

IAccessible2: object attributes container-live:polite;live:polite;container-live-role:tablist

ROLE_PAGE_TAB_LIST + object attributes container-live:polite;live:polite;container-live-role:tablistAXTabGroup
<nil>
'tabgroup'
tabpanelROLE_SYSTEM_PANE or ROLE_SYSTEM_PROPERTYPAGEROLE_SYSTEM_PANE or ROLE_SYSTEM_PROPERTYPAGEROLE_SCROLL_PANEAXGroup
TabPanel
'tab panel'
textboxROLE_SYSTEM_TEXTROLE_SYSTEM_TEXT

IAccessible2: IA2_STATE_SINGLE_LINE if aria-multiline is not "true"

ROLE_ENTRY + STATE_SINGLE_LINE if aria-multiline is not "true"

If aria-multiline="false" (default) use:
AXTextField
<nil>
'text field'

If aria-multiline="true" use:
AXTextArea
<nil>
'text entry area'

timerExpose as text string in AriaRoleIAccessible2: Object attribute xml-roles:timer;container-live:off;live:off;container-live-role:timerROLE_UNKNOWN + object attributes container-live:off;live:off;container-live-role:timerAXGroup
AXApplicationTimer
'timer'
toolbarROLE_SYSTEM_TOOLBARROLE_SYSTEM_TOOLBARROLE_TOOL_BARAXToolbar
<nil>
'toolbar'
tooltipROLE_SYSTEM_TOOLTIPROLE_SYSTEM_TOOLTIPROLE_TOOL_TIPAXGroup
AXUserInterfaceTooltip
'tooltip'
treeROLE_SYSTEM_OUTLINEROLE_SYSTEM_OUTLINEROLE_TREEAXOutline
<nil>
'outline'
treegridDataGridROLE_SYSTEM_OUTLINE

IAccessible2:

  • Use IAccessibleTable2 interface
  • Object attribute xml-roles:treegrid
ROLE_TREE_TABLEAXTable
<nil>
'table'
treeitemTreeItemROLE_SYSTEM_OUTLINEITEM

IAccessible2: If aria-checked (state) is not undefined, support object attribute checkable:true

ROLE_LIST_ITEM + if aria-checked is not undefined, support object attribute checkable:trueAXRow
AXOutlineRow
'outline row'

[Note 1] User agent should return a user-presentable, localized string value for the AXRoleDescription.

[Note 2] This specification does not currently contain guidance for when user agents should fire system alert events. Some guidance may be added to the specification at a later date but it will be a recommendation (SHOULD), not a requirement (MUST).

5.5. State and Property Mapping

This section describes how to expose WAI-ARIA states and object properties.

  1. User agents MUST compute managed states 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. User agents MUST continue to expose native semantics in addition to WAI-ARIA state and property semantics except where an explicit WAI-ARIA override is allowed by the host language. For example, an HTML checkbox may have an aria-labelledby attribute but the native HTML semantics must still be exposed.
  3. User agents MUST expose additional states for certain roles as defined in the Role Mapping Table.
  4. User agents MUST compute states for the relevant WAI-ARIA attributes and map to the accessibility API as specified in the State and Property Mapping Table. To determine the relevant WAI-ARIA attributes, refer to the Definition of Roles [ARIA]. Where the author has not provided values for required attributes, user agents SHOULD process as if the default value as indicated in column 1 was provided.
  5. For forward compatibility with new WAI-ARIA properties in future versions, user agents SHOULD expose all properties not in the table below as a text string, removing the "aria-" prefix from the name, if the API supports it. For example, aria-foo="bar" would be exposed with a text string foo=bar in UIA Express, since aria-foo is not a currently known WAI-ARIA property. The following list specifies the accessibility APIs for exposing properties as text strings.
    • MSAA: not supported
    • IAccessible2: expose as an object attribute pair ( property:string)
    • UIA Express: expose an object attribute pair in AriaProperties (property=string)
    • ATK/AT-SPI: expose as an object attribute pair (property:string)
  6. 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 NOT map the given WAI-ARIA property to the platform accessibility API. For example, if aria-checked="true" is specified on <div role="grid">, it should not be exposed in MSAA implementations as STATE_SYSTEM_CHECKED. User agents MAY expose non-relevant attributes as a text string if the API supports it as described above.
  7. When an explicit or inherited role of presentation is applied to an element, the user agent MUST implement the rules for presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [ARIA].

5.5.1. State and Property Mapping Table

5.5.1.1. Not Mapped

There are a number of occurrences in the table where a given state or property is declared "Not mapped". In some cases, this occurs for the default value of the state/property, and is equivalent to its absence. User agents might find it quicker to map the value than check to see if it is the default. For computational efficiency, user agents MAY expose the state or property value if doing so is equivalent to not mapping it. These cases are marked with an asterisk.

In other cases, it is mandatory that the state/property not be mapped, since exposing it implies a related affordance. An example is aria-grabbed (state). Its absence not only indicates that the accessible is not grabbed, but further defines it as not grab-able. These cases are marked as "Not mapped" without an asterisk.

WAI-ARIA state and property mapping rule table
WAI-ARIA State or PropertyMSAA + UIA ExpressMSAA + IAccessible2 ATK/AT-SPIMac OS X
aria-activedescendantSee Controlling focus with aria-activedescendant, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations.

In cases, however, the focus can be transparent in an accessibility tree as it may be 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, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations.See Controlling focus with aria-activedescendant, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations.

In cases, however, the focus can be transparent in an accessibility tree as it may be 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_FOCUSED state. When this happens, standard focus event and event handling should apply.

array AXSelectedRows contains pointer to active descendant node
aria-atomic="true"Expose atomic=true in AriaProperties

IAccessible2:

  • Expose as object attribute atomic:true and container-atomic:true
  • Expose as 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 as object attribute atomic:true and container-atomic:true.

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.

boolean AXARIAAtomic: YES
aria-atomic="false" (default)Expose atomic=false in AriaProperties

IAccessible2:

Not mapped*OPTIONAL — but if mapped:

  • Expose as object attribute atomic:false and container-atomic:false
  • Expose as object attribute container-atomic:false 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.

Not mapped*OPTIONAL — but if mapped:

Expose as object attribute atomic:false and container-atomic:false.

Expose object attribute container-atomic:false 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.

boolean AXARIAAtomic: NO
aria-autocomplete="inline", "list", or "both"Expose autocomplete=<value> in AriaProperties

IAccessible2:

  • Object attribute autocomplete:<value>
  • Expose the IA2_STATE_SUPPORTS_AUTOCOMPLETION equivalent state
Object attribute autocomplete:<value>

Expose the SUPPORTS_AUTOCOMPLETION equivalent state

Not mapped
aria-autocomplete="none" (default)Not mapped*Not mapped*Not mapped*Not mapped*
aria-busy="true" (state)Expose the STATE_SYSTEM_BUSY stateExpose the STATE_SYSTEM_BUSY stateExpose the STATE_BUSY stateboolean AXARIABusy: YES
aria-busy="false" (state) (default)Clear the STATE_SYSTEM_BUSY stateClear the STATE_SYSTEM_BUSY stateClear the STATE_BUSY stateboolean AXARIABusy: NO
aria-checked="true" (state)

Expose as ToggleState property in Toggle Control Pattern.

Toggle.ToggleState = On (1)

Special case: For menuitemradio and radio, expose as IsSelected property in SelectionItem Control Pattern.

SelectionItem.IsSelected = On (1)

Set the STATE_SYSTEM_CHECKED state

IAccessible2: Expose object attribute checkable:true

Expose object attribute checkable:true

Set the STATE_CHECKED state

AXValue: 1
aria-checked="false" (state)

Expose as ToggleState property in Toggle Control Pattern.

Toggle.ToggleState = Off (0)

Special case: For menuitemradio and radio, expose as IsSelected property in SelectionItem Control Pattern.

SelectionItem.IsSelected = Off (0)

Clear the STATE_SYSTEM_CHECKED state

IAccessible2: Expose object attribute checkable:true

Clear the STATE_CHECKED state

Expose object attribute checkable:true

 

AXValue: 0
aria-checked="mixed" (state)

Treat as "false" for radio and menuitemradio roles.

Expose as ToggleState property in Toggle Control Pattern.

Set the STATE_SYSTEM_MIXED state

Toggle.ToggleState = Indeterminate (2)

Set the STATE_SYSTEM_MIXED state

IAccessible2: Expose object attribute checkable:true

Expose STATE_INDETERMINATE, unless on a role of radio or menuitemradio (in those cases treat as "false")

Expose object attribute checkable:true

AXValue: 2
aria-checked is undefined (state)

Treat as "false" for checkbox, menuitemcheckbox, radio and menuitemradio roles.

Not mappedNot mappedNot mappedNot mapped
aria-controlsExpose pointer to the accessible object ControllerFor property

IAccessible2:

  • Expose pointer to the accessible object in IA2_RELATION_CONTROLLER_FOR
  • Expose reverse relations as described in Relations.
Expose pointer to the accessible object RELATION_CONTROLLER_FOR

Expose reverse relations as described in Relations.

array AXLinkedUIElements contains pointers to nodes matching IDREFs
aria-describedbyUse in calculating the accessible Description as described in Name Computation. Expose in accDescription property.Use in calculating the accessible Description as described in Name Computation. Expose in accDescription property.

IAccessible2:

If the referenced object is in the accessibility tree, expose pointer to it in IA2_RELATION_DESCRIBED_BY and expose reverse relations as described in Relations.

Use in calculating the accessible Description as described in Name Computation. Expose in the description property of the accessible object.

If the referenced object is in the accessibility tree, expose reverse relations as described in Relations.

Use in calculating the accessible description as described in Name Computation and expose value as string AXHelp.
aria-disabled="true" (state)Set IsEnabled to "false"

 

 

Set STATE_SYSTEM_UNAVAILABLE

Propagate to all descendants of the element with STATE_SYSTEM_FOCUSABLE

Not mappedboolean AXEnabled: NO
aria-disabled="false" (state) (default)Set IsEnabled to "true"Clear STATE_SYSTEM_UNAVAILABLEExpose STATE_ENABLEDboolean AXEnabled: YES
aria-dropeffect="copy", "move", "link", "execute", or "popup" (state)Expose dropeffect=<value> in AriaPropertiesIAccessible2: Expose as object attribute dropeffect:<value>Expose as object attribute dropeffect:<value>array AXDropEffects
aria-dropeffect="none" (state) (default)Not mapped*

IAccessible2: Expose as object attribute dropeffect:none if there are no other valid tokens.

Not mapped if not specified by the author.

Expose as object attribute dropeffect:none if there are no other valid tokens.

Not mapped if not specified by the author.

Not mapped*
aria-expanded="true" (state)Expose as "expanded" in ExpandCollapseState property of ExpandCollapse Control PatternSet STATE_SYSTEM_EXPANDEDExpose STATE_EXPANDABLE and STATE_EXPANDEDboolean AXExpanded: YES
aria-expanded="false" (state)Expose as "collapsed" in ExpandCollapseState property of ExpandCollapse Control PatternSet STATE_SYSTEM_COLLAPSEDExpose STATE_EXPANDABLEboolean AXExpanded: NO
aria-expanded is undefined (state) (default)Not mappedNot mappedNot mappedNot mapped
aria-flowtoExpose a reference to the accessible object in FlowsTo property

IAccessible2:

  • Expose reference to the accessible object in IA2_RELATION_FLOW_TO
  • Expose reverse relations as described in Relations.
Expose reference to the accessible object in RELATION_FLOWS_TO

Expose reverse relations as described in Relations.

array AXLinkedUIElements contains pointer to nodes matching IDREFs
aria-grabbed="true"(state)Expose as grabbed=true in AriaPropertiesIAccessible2: Object attribute grabbed:trueObject attribute grabbed:trueboolean AXGrabbed: YES
aria-grabbed="false"(state)Expose as grabbed=false in AriaPropertiesIAccessible2: Object attribute grabbed:falseObject attribute grabbed:falseboolean AXGrabbed: NO
aria-grabbed is undefined (state) (default)Not mappedNot mappedNot mappedNot mapped
aria-haspopup="true" (default for role combobox)Expose as STATE_SYSTEM_HASPOPUP. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU.Expose as STATE_SYSTEM_HASPOPUP. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU.Object attribute haspopup:trueExpose AXShowMenu and AXPress actions
aria-haspopup="false" (default)Clear the HASPOPUP state. If specified on a push button, change the role to ROLE_SYSTEM_BUTTONMENUClear the HASPOPUP state. If specified on a push button, change the role to ROLE_SYSTEM_BUTTONMENUNot mapped*Not mapped*
aria-hidden="true" (state)

See Including Elements in the Accessibility Tree.

If the object is in the accessibility tree, map all attributes as normal.

 

See Including Elements in the Accessibility Tree.

If the object is in the accessibility tree, map all attributes as normal.

IAccessible2: Expose object attribute hidden:true.

 

See Including Elements in the Accessibility Tree.

If the object is in the accessibility tree, map all attributes as normal. In addition, expose object attribute hidden:true.

Not exposed in AX API unless focused. If focused, expose as normal.
aria-hidden="false" (state) (default)Not mappedNot mappedNot mappedNot mapped
aria-invalid="true", "spelling", or "grammar" (state)
  • If aria-invalid="true", expose false in IsDataValidForForm property,
  • Otherwise expose <value> in IsDataValidForForm property

IAccessible2:

  • Set IA2_STATE_INVALID_ENTRY
  • Expose the value as a text attribute (not object attribute).
  • Set STATE_INVALID_ENTRY
  • Expose the value as a text attribute (not object attribute).
AXInvalid: <value>
aria-invalid=<unknown value>Expose <value> in IsDataValidForForm property

IAccessible2:

  • Set IA2_STATE_INVALID_ENTRY
  • Expose the value as a text attribute (not object attribute).
  • Set STATE_INVALID_ENTRY
  • Expose the value as a text attribute (not object attribute).
AXInvalid: <value>
aria-invalid="false" (state) (default)Expose true in IsDataValidForForm propertyIAccessible2: Clear IA2_STATE_INVALID_ENTRY or equivalent state.Not mapped*AXInvalid: "false"
aria-invalid="" (state) (default)Expose true in IsDataValidForForm propertyIAccessible2: Clear IA2_STATE_INVALID_ENTRY or equivalent state.Not mapped*AXInvalid: "false"
aria-labelUse in calculating the accessible name as described in Name Computation. Expose in accName property.Use in calculating the accessible name as described in Name Computation. Expose in accName property.Use in calculating the accessible name as described in Name Computation. Expose in the name property of the accessible object.

Calculate accessible name as described in Name Computation and expose value as string AXDescription.

Note: AXDescription is recommended for accessible name values that are not exposed visually, such as @alt and @aria-label. Accessible name values that are exposed visually, as in the case of a button, should be exposed as string AXTitle. For example, with <input type="button" value="Feb" aria-label="February">, expose both AXTitle:"Feb" and AXDescription:"February".

aria-labelledbyUse in calculating the accessible name as described in Name Computation. Expose in accName property.

Use in calculating the accessible name as described in Name Computation. Expose in accName property.

IAccessible2:

If the referenced object is in the accessibility tree expose a pointer to it in IA2_RELATION_LABELLED_BY and expose reverse relations as described in Relations.

Use in calculating the accessible name as described in Name Computation. Expose in the name property of the accessible object.

If the referenced object is in the accessibility tree, expose a pointer to it in RELATION_LABELLED_BY and expose reverse relations as described in Relations.

If aria-labelledby references a single element, expose the labeling relationship as element AXTitleUIElement.

If aria-labelledby references multiple elements, or if the labeling element is invisible or otherwise not exposed in the accessibility tree, use in calculating the accessible name as described in Name Computation and expose value as string AXDescription.

aria-level

Expose as level=<value> in AriaProperites.

IAccessible2:

Expose as object attribute level:<value>

When used on a heading, map to AXValue.

When used on an outline row (like a treeitem or group), map to AXDisclosureLevel.

aria-live="assertive" (default for role alert)

Set LiveSetting Property to "assertive"

IAccessible2:

Expose as object attribute live:assertive and container-live:assertive.

Expose as object attribute container-live:assertive on all descendants as described in Changes to document content or node visibility.

AXARIALive: "assertive"
aria-live="polite" (default for role types log and status)Set LiveSetting Property to "polite"

IAccessible2:

Expose as object attribute live:polite and container-live:polite.

Expose as object attribute container-live:polite on all descendants as described in Changes to document content or node visibility.

AXARIALive: "polite"
aria-live="off" (default)Set LiveSetting property to "off"

IAccessible2:

Expose as object attribute live:off and container-live:off.

Expose as object attribute container-live:off on all descendants as described in Changes to document content or node visibility.

AXARIALive: "off"
aria-multiline="true"Expose as multiline=true in AriaPropertiesIAccessible2: Set the IA2_MULTI_LINE state and clear IA2_SINGLE_LINESet STATE_MULTI_LINE and clear STATE_SINGLE_LINE

Not mapped

See textbox in the Role Mapping Table for more information.

aria-multiline="false" (default)Not mapped*IAccessible2: Clear the IA2_MULTI_LINE state, and set IA2_SINGLE_LINESet STATE_SINGLE_LINE and clear STATE_MULTI_LINE

Not mapped

See textbox in the Role Mapping Table for more information.

aria-multiselectable="true"

Set CanSelectMultiple property on the Selection Control Pattern.

See Selection for details.

Set the STATE_SYSTEM_MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match STATE_SYSTEM_MULTISELECTABLE.

IAccessible2: For text elements, support the selection methods defined on the IAccessibleText interface

See Selection for details.

Expose STATE_MULTISELECTABLE

See Selection for details.

Not mapped

See Selection for details.

aria-multiselectable="false" (default)Not mapped*Clear the STATE_SYSTEM_MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match STATE_SYSTEM_MULTISELECTABLE.

See Selection for details.

Not mapped*Not mapped*
aria-orientation="horizontal" (default)

Set Orientation property to "horizontal"

IAccessible2:
  • Set: IA2_STATE_HORIZONTAL
  • Clear: IA2_STATE_VERTICAL
Set STATE_HORIZONTALAXOrientation: AXHorizontalOrientation
aria-orientation="vertical" (default for role scrollbar)

Set Orientation Property to "vertical"

IAccessible2:
  • Set: IA2_STATE_VERTICAL
  • Clear: IA2_STATE_HORIZONTAL
Set STATE_VERTICALAXOrientation: AXVerticalOrientation
aria-ownsThe structure should be reflected in the accessibility tree as directed by aria-owns. Map the elements that are referenced by this property as children of the current element.

If multiple aria-owns relationships are found, use only the first one.

The accessibility tree is not modified.

IAccessible2:

  • Expose reverse relations as described in Relations

If multiple aria-owns relationships are found, use only the first one.

Expose reverse relations as described in Relations

If multiple aria-owns relationships are found, use only the first one.

array AXLinkedUIElements contains pointer to nodes matching IDREFs

aria-posinset

If not provided for relevant roles, user agents calculate aria-setsize and aria-posinset for each object in the container based on the number of objects in the DOM.

Expose as posinset=<value> in AriaProperties.

Additionally, user agents MAY update the LegacyIAccessible.Description property to take the form X of Y, where X is the aria-posinset value and Y is the aria-setsize value; and if X is less than one, or if X is greater than Y, LegacyIAccessible.Description will be empty.

IAccessible2: Expose as object attribute posinset:<value> and in groupPosition().

Expose as object attribute posinset:<value>.

AXARIAPosInSet: <value>
aria-pressed="true" (state)

Expose as ToggleState property of Toggle Control Pattern

Toggle.ToggleState = On (1)

Set the STATE_SYSTEM_PRESSED state.

IAccessible2:

  • If on a button, expose the role as IA2_ROLE_TOGGLE_BUTTON
  • Expose object attribute checkable:true
Expose STATE_PRESSED. If on a button, expose the role as ROLE_TOGGLE_BUTTON.

Expose object attribute checkable:true

AXValue: 1
aria-pressed="mixed" (state)

Expose as ToggleState property of Toggle Control Pattern

Toggle.ToggleState = Indeterminate (2)

Set the STATE_SYSTEM_PRESSED state.

IAccessible2:

  • If on a button, expose the role as IA2_ROLE_TOGGLE_BUTTON
  • Expose object attribute checkable:true
Expose STATE_INDETERMINATE/STATE_SYSTEM_MIXED. If on a button, expose the role as ROLE_TOGGLE_BUTTON.

Expose object attribute checkable:true

AXValue: 2
aria-pressed="false" (state)

Expose as ToggleState property of Toggle Control Pattern

Toggle.ToggleState = Off (3)

Clear the STATE_SYSTEM_PRESSED state

IAccessible2:

  • If on a button, expose the role as IA2_ROLE_TOGGLE_BUTTON
  • Expose object attribute checkable:true
If on a button, expose the role as ROLE_TOGGLE_BUTTON.

Expose object attribute checkable:true

AXValue: 0
aria-pressed is undefined (state) (default)Not mapped*Not mapped*Not mapped*Not mapped*
aria-readonly="true"Expose as STATE_SYSTEM_READONLYExpose as STATE_SYSTEM_READONLYNo mappingAXValue (not writable)
aria-readonly="false" (default)Not mappedIAccessible2: Expose IA2_STATE_EDITABLEExpose STATE_EDITABLEAXValue (writable)
aria-relevant="additions", "removals", "text", or "all"Expose as relevant=<value> in AriaProperties

IAccessible2:

Expose as object attribute relevant:<value> and container-relevant:<value>.

Expose as object attribute container-relevant:<value> on all descendants as described in Changes to document content or node visibility.

AXARIARelevant: <value>
aria-relevant="additions text" (Default)Expose as relevant=additions text in AriaProperties

IAccessible2:

  • Expose as object attribute relevant:additions text and container-relevant:additions text
  • Expose as object attribute container-relevant:additions text on all descendants as described in Changes to document content or node visibility.

Expose as object attribute relevant:additions text and container-relevant:additions text.

Expose as object attribute container-relevant:additions text on all descendants as described in Changes to document content or node visibility

AXARIARelevant: <value>
aria-required="true"Expose as IsrequiredForForm property.IAccessible2: Expose IA2_STATE_REQUIREDExpose STATE_REQUIREDboolean AXRequired: YES
aria-required="false" (default)Not mapped*Not mapped*Not mapped*Not mapped*
aria-selected="true" (state)

If role is radio or menuitemradio, mapping the value is OPTIONAL.

Expose STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

Expose STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

IAccessible2: If not DISABLED, toggle between "true" and "false" as appropriate when aria-multiselectable is used on an ancestor as described in Selection.

Expose STATE_SELECTED and STATE_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.

boolean AXSelected: YES
aria-selected="false" (state)

If role is radio or menuitemradio, mapping the value is OPTIONAL.

Clear STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

Clear STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

IAccessible2: 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.

Clear STATE_SELECTED and expose STATE_SELECTABLE.boolean AXSelected: NO
aria-selected is undefined (state) (default)

If role is option or tab treat as false.

Not mappedNot mappedNot mappedNot mapped

aria-setsize

If not provided for relevant roles, user agents calculate aria-setsize and aria-posinset for each object in the container based on the number of objects in the DOM.

Expose as setsize=<value> in AriaProperties

Additionally, user agents MAY update the LegacyIAccessible.Description property to take the form X of Y, where X is the aria-posinset value and Y is the aria-setsize value; and if X is less than one, or if X is greater than Y, LegacyIAccessible.Description will be empty.

IAccessible2: Expose object attribute setsize:<value> and groupPosition().

Expose object attribute setsize:<value>.

AXARIASetSize: <value>
aria-sort="ascending", "descending", or "other"

Expose as sort=<value> in AriaProperties.

If on an element that maps to HeaderItem controls (th elements, and elements that include the "columnheader" and "rowheader" role),  ItemStatus="<value>".

IAccessible2: Expose as object attribute sort:<value>Expose as object attribute sort:<value>AXSortDirection: AXAscendingSortDirection | AXDescendingSortDirection | AXUnknownSortDirection
aria-sort="none" (default)Not mapped*IAccessible2: If specified, expose as object attribute sort:<value>If specified, expose as object attribute sort:<value>Not mapped*
aria-valuemaxExpose the Maximum property in RangeValue Control Pattern

See Widget values for additional information

IAccessible2: Expose via AccessibleValue interface.

See Widget values for additional information

Expose the Maximum property in RangeValue Control Pattern

See Widget values for additional information

number AXMaxValue

See Widget values for additional information

aria-valueminExpose the Minimum property in RangeValue Control Pattern

See Widget values for additional information

IAccessible2: Expose via AccessibleValue interface

See Widget values for additional information

Expose via AccessibleValue interface

See Widget values for additional information

number AXMinValue

See Widget values for additional information

aria-valuenowIf aria-valuetext is not defined, expose via IAccessible::get_accValueIf aria-valuetext is not defined, expose via IAccessible::get_accValue

IAccessible2: Expose via AccessibleValue interface.

See Widget values for additional information

Expose via AccessibleValue interface.

See Widget values for additional information

number AXValue

See Widget values for additional information

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

See Widget values for additional information

Expose via IAccessible::get_accValue

IAccessible2: Expose as object attribute valuetext:<value>

See Widget values for additional information

Expose as object attribute valuetext:<value>

See Widget values for additional information

AXValueDescription: <value>

See Widget values for additional information

5.6. Special Processing Requiring Additional Computation

5.6.1. Name and Description

5.6.1.1. Name Computation

User agents MUST compute an accessible name using the rules outlined below in the section titled Text Alternative Computation.

Special Case: If the element is an img element that is exposed in the accessibility tree; and the computed text alternative is empty, then check for the presence of role presentation or any labeling attribute that specifies an empty label, 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 assistive technology to do its own heuristic processing to repair the missing accessible name.

5.6.1.2. Description Computation

If aria-describedby is present, user agents MUST compute the accessible description by concatenating the text alternatives for nodes referenced by an aria-describedby attribute on the current node. The text alternatives for the referenced nodes are computed using a number of methods, outlined below in the section titled Text Alternative Computation.

5.6.1.3. Text Alternative Computation

The text alternative is reused in both the name and description computation, as described above. 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 2C (which is recursive), using the full set of rules to retrieve text from its own children.

The text alternative for a given node is computed as follows:
  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 text alternative as part of the label string sent to the accessibility API.
  2. For any non-skipped elements:
    1. Authors specify an element's text alternative in content attributes, used in this order of preference:
      • The aria-labelledby attribute takes precedence as the element's text alternative unless this computation is already occurring as the result of a recursive aria-labelledby declaration (in other words, aria-labelledby is not recursive when referenced from another element, so it will not cause loops). However, the element's aria-labelledby attribute can reference the element's own IDREF in order to concatenate a string provided by the element's aria-label attribute or another feature lower in this preference list. 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).

        In the following example, the <span> elements would have text alternatives of "Delete Documentation.pdf" and "Delete HolidayLetter.pdf", respectively.

        <h1>Files</h1> <ul>
        <li>
        <a id="file_row1" href="./files/Documentation.pdf">Documentation.pdf</a>
        <span role="button" tabindex="0" id="del_row1" aria-label="Delete" aria-labelledby="del_row1 file_row1"></span>
        </li>
        <li>
        <a id="file_row2" href="./files/HolidayLetter.pdf">HolidayLetter.pdf</a>
        <span role="button" tabindex="0" id="del_row2" aria-label="Delete" aria-labelledby="del_row2 file_row2"></span>
        </li>
        </ul>

      • If aria-labelledby is empty or undefined, the aria-label attribute, which defines an explicit text string, is used. However, if this computation is already occurring as the result of a recursive text alternative computation and the current element is an embedded control as defined in rule 2B, ignore the aria-label attribute and skip directly to rule 2B.
      • If aria-labelledby and aria-label are both empty or undefined, and if the element is not marked as presentational (role="presentation", 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.

      See How to Specify Alternate Text ([HTML], section 13.8) and HTML5 Requirements for providing text to act as an alternative for images ([HTML5], section 4.8.1.1). In the case of HTML frame and iframe elements, the title element in the head element of the document inside a frame or iframe is used in this step of the calculation of the name of the frame or iframe.

      Editorial Note: We've asked the HTML5 WG to remove or reduce this section, so we may remove the reference to it.

    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 CSS rules, it is necessary for user agents to combine such content, as appropriate, with the text referenced by the text nodes to produce a complete text alternative. An example is the use of CSS :before and :after pseudo-elements, where the user agent combines the textual content specified in the style sheet with that given in the DOM.
    • When an image replaces text, then the UA should use the original text, since that text is presumably the equivalent.
    • When text replaces an image, then the UA should provide that text.
    • When new text replaces old, then the UA should include the new text, since that is what is rendered on screen.

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.

5.6.2. Widget Values

Some WAI-ARIA roles are widgets that have a particular value within a range of values. For example 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 user agents SHOULD return an error when the current value is requested.

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, user agents MUST expose the string value of aria-valuetext as specified in State and Property Mapping.

5.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: aria-controls, aria-describedby, aria-flowto, aria-labelledby, aria-owns, aria-posinset, and aria-setsize. Therefore, it is not important to check the role before computing them. User agents can simply map these relations to accessibility APIs as defined in the section titled State and Property Mapping.

5.6.3.1. ID Reference Error Processing

User agents SHOULD ignore ID references that do not 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. Any aria-activedescendant value that does not match an existing IDREF exactly is an author error and will not match any element in the DOM.

5.6.3.2. Reverse Relations

A reverse relation exists when an element's ID is referenced by a property in another element. For APIs that support reverse relations, user agents MUST use the mapping defined in the following table when an element's ID is referenced by a relation property of another element and the referenced element is in the accessibility tree according to the rules in General rules for exposing WAI-ARIA semantics. All WAI-ARIA references must point to an element that is exposed as an accessible object in the accessibility tree. When the referenced object is not exposed in the accessibility tree (e.g. because it is hidden), the reference is null. aria-labelledby and aria-described by have an additional feature, which allows them to pull a flattened string from the referenced element to populate the name or description fields of the accessibility API. This feature is described in the Name and Description section.

Reverse relation mapping table
WAI-ARIA RelationIAccessible2ATK/AT-SPI
aria-controls references the element's IDIA2_RELATION_CONTROLLED_BYRELATION_CONTROLLED_BY
aria-describedby references the element's IDIA2_RELATION_DESCRIPTION_FORRELATION_DESCRIPTION_FOR
aria-flowto references the element's IDIA2_RELATION_FLOW_FROMRELATION_FLOW-FROM
aria-labelledby references the element's IDIA2_RELATION_LABEL_FORRELATION_LABEL_FOR
aria-owns references the element's IDIA2_RELATION_NODE_CHILD_OF/IA2_RELATION_NODE_PARENT_OFRELATION_NODE_CHILD_OF/RELATION_NODE_PARENT_OF

Special Case: If both aria-labelledby and HTML <label for=> are used, the user agent MUST use the WAI-ARIA relation and MUST ignore the HTML label relation.

Note that aria-describedby may reference structured or interactive information where users would want to be able to navigate to different sections of content. User agents MAY provide a way for the user to navigate to structured information referenced by aria-describedby and assistive technology SHOULD provide such a method.

5.6.3.3. Implied reverse relations

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

In the case of role="treeitem", when aria-owns is not used, user agents SHOULD do the following where reverse relations are supported by the API:

  • 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, where reverse relations are supported by the API:

  • 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".

5.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 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.
  • Because these values are 1-based, include the current item in the computation. For aria-posinset, include the current item and other group items if they are before the current item in the DOM. For aria-setsize, add to that the number of items in the same group after the current item in the DOM.

MSAA/IAccessible2 API mappings involve an additional function, groupPosition() [IA2], when aria-level, aria-posinset, and/or aria-setsize are present on an element, or are computed by the user agent. When this occurs:

  • aria-level is exposed in the groupLevel parameter of groupPosition(),
  • aria-setsize is exposed in the similarItemsInGroup parameter, and
  • aria-posinset is exposed in the positionInGroup parameter.

5.7. Actions

As part of mapping roles to accessible objects as defined in Role Mapping, users agents expose a default action on the object.

  • MSAA: If an AT calls DoDefaultAction on an accessible object, the user agent SHOULD simulate a click on the DOM element which is mapped to that accessible object.
  • IAccessible2: If an AT calls the IAccessibleAction on an accessible object, the user agent SHOULD simulate a click on the DOM element which is mapped to that accessible object.
  • ATK/AT-SPI: If an AT calls an action on an accessible object, the user agent SHOULD simulate a click on the DOM element which is mapped to that accessible object.
  • Mac OS X: If an AT triggers an AXPress action on an accessible object, the user agent SHOULD simulate a click on the DOM element which is mapped to that accessible object.

Note: Authors will need to create handlers for those click events that update WAI-ARIA states and properties in the DOM accordingly, so that those updated states can be populated by the user agent in the Accessibility API.

5.8. Events

User agents fire events for user actions, WAI-ARIA state changes, changes to document content or node visibility, changes in selection and operation of menus as defined in the following sections.

5.8.1. State and Property Change Events

User agents MUST notify assistive technology of state changes as defined in the table below, SHOULD notify assistive technology of property changes if the accessibility API defines a change event for the property, and SHOULD NOT notify assistive technology of property changes if the accessibility API does not define a change event for the property. For example, IAccessible2 defines an event to be used when aria-activedescendant changes. WAI-ARIA properties that are expected to change include aria-activedescendant, aria-valuenow, and aria-valuetext.

Note: In some APIs, AT will only be notified of events to which it has subscribed.

For simplicity and performance the user agent MAY trim out change events for state or property changes that assistive technologies typically ignore, such as events that are happening in a window that does not currently have focus.

Table of events to be fired in each API for changes in WAI-ARIA states and properties
State or PropertyMSAA + UIA Express eventMSAA + IAccessible2 event ATK/AT-SPIeventMac OS X Notification
aria-activedescendantNot mapped

See Controlling focus with aria-activedescendant

In addition:

IAccessible2: IA2_EVENT_ACTIVE_DESCENDANT_CHANGED

See Controlling focus with aria-activedescendantSee Controlling focus with aria-activedescendant

In addition: AXSelectedChildrenChanged

aria-busy (state)EVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:busyNot mapped
aria-checked (state)EVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:checkedAXValueChanged
aria-disabled (state)EVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:enabled and object:state-changed:sensitiveNot mapped
aria-dropeffect (state)Not mappedIAccessible2: IA2_EVENT_OBJECT_ATTRIBUTE_CHANGEDobject:property-changeNot mapped
aria-expanded (state)EVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:expandedAXRowExpanded,
AXRowCollapsed,
AXRowCountChanged
aria-grabbed (state)EVENT_OBJECT_SELECTION

EVENT_OBJECT_SELECTION

IAccessible2: IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED

object:property-changeNot mapped
aria-hidden (state)EVENT_OBJECT_HIDE, EVENT_OBJECT_SHOWIAccessible2: IA2_EVENT_OBJECT_ATTRIBUTE_CHANGEDobject:property-changeAXUIElementDestroyed,
AXUIElementCreated
aria-invalid (state)EVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:invalid_entryAXInvalidStatusChanged
aria-pressed (state)EVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:pressedNot mapped
aria-readonlyEVENT_OBJECT_STATECHANGEEVENT_OBJECT_STATECHANGEobject:state-changed:readonlyNot mapped
aria-requiredNot mappedEVENT_OBJECT_STATECHANGEobject:state-changed:requiredNot mapped
aria-selected (state)See section Selection for details. See section Selection for details. See section Selection for details. See section Selection for details.
aria-valuenowEVENT_OBJECT_VALUECHANGEEVENT_OBJECT_VALUECHANGEobject:property-change:accessible-valueAXValueChanged
aria-valuetextNot mappedEVENT_OBJECT_VALUECHANGEobject:property-change:accessible-valueAXValueChanged

5.8.2. Changes to document content or node visibility

Processing document changes is important regardless of WAI-ARIA. The events described in the table below are used by user agents to inform AT of changes to the DOM via the accessibility tree. For the purposes of conformance with this standard, user agents MUST implement the behavior described in this section whenever WAI-ARIA attributes are applied to dynamic content on a Web page.

Table of document change scenarios and events to be fired in each API
ScenarioMSAA + UIA Express eventMSAA + IAccessible2 event ATK/AT-SPI eventMac OS X Notification
When text is removedEVENT_OBJECT_LIVEREGIONCHANGEDIAccessible2: IA2_EVENT_TEXT_REMOVEDtext_changed::deleteIf in a live region, AXLiveRegionChanged
When text is insertedEVENT_OBJECT_LIVEREGIONCHANGEDIAccessible2: IA2_EVENT_TEXT_INSERTEDtext_changed::insertIf in a live region, AXLiveRegionChanged
When text is changedEVENT_OBJECT_LIVEREGIONCHANGEDIAccessible2: IA2_EVENT_TEXT_REMOVE and IA2_EVENT_TEXT_INSERTEDtext_changed::delete and text_changed::insertIf in a live region, AXLiveRegionChanged

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
ScenarioMSAAATK/AT-SPI eventMac OS X Notification
When an accessibility subtree is hiddenEVENT_OBJECT_HIDE
The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and assistive technology avoids it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed.
children_changed::remove

AXUIElementDestroyed

If in a live region, AXLiveRegionChanged

When an accessibility subtree is removedEVENT_OBJECT_REORDER
The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and assistive technology avoids it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed.
children_changed::remove

AXUIElementDestroyed

If in a live region, AXLiveRegionChanged

When an accessibility subtree is shownEVENT_OBJECT_SHOWchildren_changed::add

AXUIElementCreated

If in a live region, AXLiveRegionChanged

When an accessibility subtree is insertedEVENT_OBJECT_REORDERchildren_changed::add

AXUIElementCreated

If in a live region, AXLiveRegionChanged

When an accessibility subtree is movedTreat it as a removal from one place and insertion in anotherTreat it as a removal from one place and insertion in another

AXUIElementDestroyed/ AXUIElementCreated

If in a live region, AXLiveRegionChanged

When an accessibility subtree is changed (e.g. replaceNode)Treat it as a removal and insertionTreat it as a removal and insertion

AXUIElementDestroyed/ AXUIElementCreated

If in a live region, AXLiveRegionChanged

In some cases, node changes may occur where the node is not an element or has no accessible object. For example, a numbered list bullet ("12.") may have a node in the accessibility tree but not in the DOM tree. For text within a paragraph marked in HTML as <strong>, the <strong> element has a node in the DOM tree but may not have one in the accessibility tree. The text itself will of course be in the accessibility tree along with the identification of the range of text that is formatted as strong. If any of the changes described in the table above occur on such a node, user agents SHOULD compute and fire relevant text change events as described above.

User agents SHOULD ensure that an assistive technology, running in process can receive notification of a node being removed prior to removal. This allows an assistive technology, such as a screen reader, to refer back to the corresponding DOM node being deleted. This is important for live regions where removals are important. For example, a screen reader would want to notify a user that another user has left a chat room. The event in MSAA would be EVENT_OBJECT_HIDE. For ATK/AT-SPI this would be children_changed::remove. And in Mac OS X, the event is AXLiveRegionChanged. This also requires the user agent to provide a unique ID in the accessibility API notification identifying the unique node being removed.

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 assistive technology 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/AT-SPI 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:

  • In ATK/AT-SPI and IAccessible2, the RELATION_MEMBER_OF relation on the accessible event's target accessible object SHOULD point to any ancestor with aria-atomic="true" (if any).
  • In ATK/AT-SPI and IAccessible2, 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 Special Events for Menus.

5.8.3. Selection

There are two cases for selection:

  • Single selection
  • Multiple selection

In the single selection case, selection follows focus. User agents MUST fire the following events when aria-selected (state) changes:

Single selection events
ScenarioMSAAATK/AT-SPIMac OS X
Focus changeEVENT_OBJECT_SELECTION and EVENT_OBJECT_STATECHANGE on newly focused item.object:selection_changed on the current container.AXSelectedChildrenChanged

The multiple selection case occurs when aria-multiselectable="true" on an element with a role that supports that property. User agents MUST fire the following events when aria-selected (state) changes on a descendant, as follows:

Multiple selection events
ScenarioMSAAATK/AT-SPIMac OS X
Toggle aria-selectedEVENT_OBJECT_SELECTIONADD/EVENT_OBJECT_SELECTIONREMOVE on the item.object:selection_changed on the current container.AXSelectedChildrenChanged
Selection follows focusEVENT_OBJECT_SELECTION and EVENT_OBJECT_STATECHANGE on newly focused item.object:selection_changed on the current container.AXSelectedChildrenChanged
Select or deselect many items at onceUser agent MAY fire an EVENT_OBJECT_SELECTIONWITHIN. If this event is fired the other events noted above MAY be trimmed out for performance.The user agent MAY fire a single object:selection_changed event on the container, vs. multiple events, for performance.AXSelectedChildrenChanged

5.8.4. Special Events for Menus

Some APIs, provide special events whenever a menu is opened or closed. User agents SHOULD provide the events as described in the table below. If provided, because menus can be made visible or hidden using a variety of techniques, a user agent MUST ensure that the events are nested and symmetrical.

Frequently, a menubar is used to organize a hierarchy of menus. In those cases, the menubar MUST be a DOM parent of the associated menuitems, or one defined by aria-owns. In other cases, no menubar is involved; for example, when the menu is associated with a toolbar button, or is a context menu. Nonetheless the relevant menu events are provided as described in the following table.

Menu events
ScenarioMSAAMac OS X

Menubar is currently not active, and user moves focus to the menubar from elsewhere thereby activating it. As a result, a menuitem in the menubar is focused.

Activate the menubar and fire EVENT_SYSTEM_MENUSTART on the accessible object for the menubar.AXMenuOpenedNotification

Focus a menuitem while menubar is activated, or focus a menuitem in a menu.

EVENT_OBJECT_FOCUSAXMenuItemSelectedNotification

Menu popup made visible (menu is opened).

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

EVENT_SYSTEM_MENUPOPUPSTARTAXMenuOpenedNotification
Menu popup hidden (menu is closed).EVENT_SYSTEM_MENUPOPUPEND once only for accessible menu object and only if EVENT_SYSTEM_MENUPOPUPSTART was fired for it.AXMenuClosedNotification
Any open menus are closed including sub-menus, and user moves focus away from the menubar; menubar is deactivated.EVENT_SYSTEM_MENUEND on the menubar and deactivate the menubar.AXMenuClosedNotification

6. Special Document Handling Procedures

This section is normative.

6.1. CSS Selectors

Editorial Note: This section might be removed in a future version.

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 property aria-haspopup with value of true. The presentation MUST be updated for dynamic changes to WAI-ARIA attributes. This allows authors to match styling with WAI-ARIA semantics.

6.2. Author Errors

In general, user agents do not do much validation of WAI-ARIA properties. User agents MAY do some minor validation 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 behavior of 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 another owned element.

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

  • When asked for the string version of the property, return the string if specified by the author.
  • When asked for the decimal version, return a default value of 0.0 for decimal value types and 0 for integer value types.

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

  • When exposing as an object attribute, expose the unknown value — do not vet it against possible values.
  • When exposing as a platform API Boolean state, treat "", "undefined" or no attribute present as false. Treat any other value as true.
  • Otherwise, ignore the value and treat the property as not present

Note: In UIA Express, the user agent might leave the corresponding property set to "unsupported."

User agent MUST NOT expose WAI-ARIA attributes that reference unresolved ID's. For example:

  • When the state or property has only one ID reference that cannot be resolved, treat as if the state or property is not present.
  • When the state or property has a list of ID references, ignore any that can't be resolved. If none in the list can be resolved, treat as if the state or property is not present.

If a required WAI-ARIA attribute for a given role is missing, user agents SHOULD process the attribute as if the values given in the following table were provided. User agents MAY report these errors via their console.

Default values for missing required attributes
WAI-ARIA roleRequired AttributeDefault value
checkboxaria-checkedSee aria-checked="false" in State and Property mapping table.
menuitemcheckboxaria-checkedSee aria-checked="false" in State and Property mapping table.
menuitemradioaria-checkedSee aria-checked="false" in State and Property mapping table.
radioaria-checkedSee aria-checked="false" in State and Property mapping table.
comboboxaria-expandedSee aria-expanded="false" in State and Property mapping table.
scrollbararia-controlsno mapping
scrollbararia-orientationSee aria-orientation="vertical" in State and Property mapping table.
scrollbararia-valuemax0
scrollbararia-valuemin0
scrollbararia-valuenow0
slideraria-valuemax0
slideraria-valuemin0
slideraria-valuenow0
spinbuttonaria-valuemax0
spinbuttonaria-valuemin0
spinbuttonaria-valuenow0

7. Appendices

7.1. References

This section is normative.

7.1.1. Normative References

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

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

7.1.2. Informative References

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

[ARIA-PRACTICES]
WAI-ARIA Authoring Practices. J. Scheuhammer, M. Cooper, L. Pappas, R. Schwerdtfeger, Editors, W3C Working Draft (work in progress), 7 March 2013. This version of WAI-ARIA 1.0 Authoring Practices is available at http://www.w3.org/TR/2013/WD-wai-aria-practices-20130307/. Latest version of WAI-ARIA Authoring Practices available at http://www.w3.org/TR/wai-aria-practices/.
[ARIA-PRIMER]
WAI-ARIA 1.0 Primer. L. Pappas, R. Schwerdtfeger, M. Cooper, Editors, W3C Working Draft (work in progress), 16 September 2010. This version of WAI-ARIA Primer is available at http://www.w3.org/TR/2010/WD-wai-aria-primer-20100916/. Latest version of WAI-ARIA Primer available at http://www.w3.org/TR/wai-aria-primer/.
[ARIA-ROADMAP]
Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap), R. Schwerdtfeger, Editor, W3C Working Draft (work in progress), 4 February 2008. This version of WAI-ARIA Roadmap is available at http://www.w3.org/TR/2008/WD-wai-aria-roadmap-20080204/. Latest version of WAI-ARIA Roadmap available at http://www.w3.org/TR/wai-aria-roadmap/.
[ATK]
Gnome Accessibility Toolkit 2.10.0. Available at https://developer.gnome.org/atk/2.10/.
[AT-SPI]
Assistive Technology-Service Provider Interface 2.10. Available at https://developer.gnome.org/libatspi/2.10/.
[AXAPI]
The Mac OS X Accessibility Protocol Mac OS 10.9. Available at: https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Protocols/NSAccessibility_Protocol/Reference/Reference.html.
[HTML]
HTML 4.01 Specification, I. Jacobs, A. Le Hors, D. Raggett, Editors, W3C Recommendation, 24 December 1999, http://www.w3.org/TR/1999/REC-html401-19991224/. Latest version of HTML 4.01 available at http://www.w3.org/TR/html401/.
[HTML5]
HTML 5, R. Berjon, S. Faulkner, T. Leithead, E. Doyle Navara, E. O'Connor, S. Pfeiffer, I. Hickson, Editors, W3C Candidate Recommendation (work in progress), 4 February 2014, http://www.w3.org/TR/2014/CR-html5-20140204/. Latest version of HTML 5 available at http://www.w3.org/TR/html5/.
[IA2]
IAccessible2 1.3. Available at http://www.linuxfoundation.org/collaborate/workgroups/accessibility/iaccessible2.
[MSAA]
Microsoft Active Accessibility (MSAA) 2.0. Available at http://msdn.microsoft.com/en-us/library/ms697707.aspx.
[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.
[UAAG]
User Agent Accessibility Guidelines 1.0, I. Jacobs, J. Gunderson, E. Hansen, Editors, W3C Recommendation, 17 December 2002, http://www.w3.org/TR/2002/REC-UAAG10-20021217/. Latest version available at http://www.w3.org/TR/UAAG10/.
[UIA-ARIA]
UI Automation for W3C Accessible Rich Internet Applications Specification. Available at http://msdn.microsoft.com/en-us/library/ee684013%28VS.85%29.aspx.
[WCAG20]
Web Content Accessibility Guidelines 2.0, B. Caldwell, G. Vanderheiden, L. Guarino Reid, M. Cooper, Editors, W3C Recommendation, 11 December 2008, http://www.w3.org/TR/2008/REC-WCAG20-20081211/. Latest version of WCAG 2.0 available at http://www.w3.org/TR/WCAG20/.

7.2. Acknowledgments

The following people contributed to the development of this document.

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

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

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

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

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

Other contributors:

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

7.2.3. Enabling funders

This publication has been funded in part with Federal funds from the U.S. Department of Education, National Institute on Disability and Rehabilitation Research (NIDRR) under contract number ED05CO0039 and ED-OSE-10-C-0067. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.