This document describes how user agents should expose semantics of web content languages to accessibility APIs. This helps users with disabilities to obtain and interact with information using assistive technologies. Documenting these mappings promotes interoperable exposure of roles, states, properties, and events implemented by accessibility APIs and helps to ensure that this information appears in a manner consistent with author intent.

This Core Accessibility API Mappings specification defines support that applies across multiple content technologies, including general keyboard navigation support and mapping of general-purpose roles, states, and properties provided in Web content via WAI-ARIA [[!WAI-ARIA]]. Other Accessibility API Mappings specifications depend on and extend this Core specification for specific technologies, including native technology features and WAI-ARIA extensions. This document updates and will eventually supercede the guidance in the WAI-ARIA 1.0 User Agent Implementation Guide [[!WAI-ARIA-IMPLEMENTATION]] W3C Recommendation. It is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

Introduction

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

This document includes information for user agents specifying how to map WAI-ARIA roles, states, and properties to platform accessibility APIs. It also includes host-language specific requirements where necessary to complete the accessibility model. Examples of host languages include HTML and SVG. However, in order to provide the basic, core mappings of WAI-ARIA, discussion of host-language features are generally avoided. How host languages modify or override the core mappings is specified in separate documents.

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. Accessibility APIs allow developers to express the function of controls and text to assistive technologies. Accessibility APIs include a tree of accessible objects (controls and text) and information about each of them:

  1. Descriptive properties (role, name, value, position, etc.),
  2. Transient states (pressed, focusable, etc.),
  3. Events (text changed, button was clicked, checkbox was toggled),
  4. Actions the user might take (click, check/toggle, drag, etc.),
  5. Relationships (parent/child in the tree, controls, flowsto, etc.), and
  6. Textual content.

In the case of 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. To interact with static Web content, assistive technologies, such as screen readers, have tended to rely on the DOM provided by the user agent. However, platform accessibility APIs provide a quicker and more comprehensive way for assistive technologies to learn about and interact with Web page content. Especially with UI elements that are known to be interactive, such as HTML form elements and desktop applications, accessibility APIs allow the more complex roles, properties, states, and relationships of those elements to be communicated to assistive technology in a way that the DOM cannot provide on its own.

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:

The WAI-ARIA 1.0 User Agent Implementation Guide included mappings for UIA Express, also known as IAccessibleEx, which was implemented in Microsoft Internet Explorer 8.0 - 11. New implementations are strongly encouraged to use User Interface Automation instead.

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.

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.

Comparing Accessibility APIs

For various technological and historical reasons, accessibility APIs do not all work in the same way. In many cases, there is no simple one-to-one relationship between how each of them names or exposes roles, states, and properties to user agents. The following subsections describe a few of the distinguising characteristics of some of the APIs.

ATK/AT-SPI

MSAA, IAccessible2, UIA, and AX API each define an API that is shared by both the software application exposing information about its content and interactive components, and the user agent (assistive technology) consuming that information. Conversely, Linux/GNOME separates that shared interface into its two aspects, each represented by a different accessibility API, ATK or AT-SPI.

ATK defines an interface that is implemented by software in order to expose accessibility information, whereas AT-SPI is a desktop service that gathers accessibility information from active applications and relays it to other interested applications, usually assistive technologies.

For example, the GNOME GUI toolkit [GTK], implements the relevant aspects of ATK for each widget (menu, comobox, checkbox, etc.) in order that GTK widgets expose accessibility information about themselves. AT-SPI then acquires the information from applications built with GTK and makes it available to interested parties.

ATK is most relevant to implementors, wherease AT-SPI is relevant to consumers. In the context of mapping WAI-ARIA roles, states and properties, user agents are implementors and use ATK. Asisstive Technologies are consumers, and use AT-SPI.

UIA (UI Automation)

UI Automation expresses every element of the application user interface as an automation element. Automation elements form the nodes of the application accessibility tree, that can be queried, traversed and interacted with by automation clients.

There are several concepts central to UI Automation:

  • Automation element - controls and some application content is presented as automation elements.
  • Element properties - Automation elements have several common properties describing native framework element characteristics in an agnostic way that all automation clients can understand. There are several ways to access element property values, described below.
  • Control Patterns - Some common interactivity in different frameworks is expressed as control patterns in UIA, allowing different automation client to interact with controls using common programmatic interfaces.
  • Events - Similarly to other accessibility APIs, automation elements support various events that allow automation providers notify clients on important state changes.

All automation elements inherit from the IUIAutomationElement interface and all properties that are not specific to a particular control pattern can be queried through that interface. There are several ways to access UI Automation element properties:

  • Direct property accessors to the current values - Current{PropertyName}, e.g. IUIAutomationElement::CurrentName for the Name property
  • Cached property accessors - Cached{PropertyName}, e.g. IUIAutomationElement::CachedName for the Name property. Using cached values is preferred when providers and clients are used in remote environments.
  • GetCurrentPropertyValue and passing the UIA Property ID enumeration value corresponding to that property to get the current value, e.g. IUIAutomationElement::GetCurrentPropertyValue(UIA_NamePropertyId) for the Name property.
  • GetCachedPropertyValue and passing the UIA Property ID enumeration value corresponding to that property to get the cached value, e.g. IUIAutomationElement::GetCachedPropertyValue(UIA_NamePropertyId) for the Name property.

Properties for specific UIA control patterns are queried the same way using relevant control pattern interfaces. Taking Toggle Pattern as an example, to query the ToggleState property clients can use IUIAutomationTogglePattern::CurrentToggleState or IUIAutomationTogglePattern::GetCurrentPropertyValue(UIA_ToggleToggleStatePropertyId) to get the current value.

The property mapping in this specification provide the {PropertyName} and do not specify all specific ways to access the property value. Automation clients can access current or cached values using conventions described above, depending on specific needs and coding style conventions.

Accessible Names and Descriptions

Each platform accessibility API includes a way to assign and retrieve accessible name and accessible description properties for each accessible object created in the accessibility tree. How these the relevant properties are implemented and what they are called vary depending on the API.

For instance, in MSAA, all accessible objects support the accName property, which stores the object's accessible name. Where the object also supports having an accessible description, MSAA stores this property in the object's accDescription property.

Software using ATK can read and write to an object's accessible-name and accessible-description properties. In turn, AT-SPI can query the values of those properties through its atspi_accessible_get_name and atspi_accessible_get_description functions.

Automation elements in the UIA accessibility tree have a Name property. Where the object also supports having an accessible description, UIA stores this property in the object's FullDescription property.

The approach to accessible names and accessible descriptions in AX API is somewhat different to the other platform APIs. Accessible names are exposed using the AXTitle property when the name is visually rendered, while the AXDescription property is used when the object's name is not rendered visually. An object's accessible description, where provided, should always be exposed in the AXHelp property.

For more detail, see the Accessible Name and Description Computation and API Mappings specification.

RFC-2119 Keywords

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.

Normative and Informative Sections

The indication whether a section is normative or non-normative (informative) applies to the entire section including sub-sections.

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.

Features Deprecated in WAI-ARIA

The WAI-ARIA specification lists some features as deprecated. Although this means authors are encouraged not to use such features, it is expected that the features could still be used in legacy content. Therefore, it is important that user agents continue to map these features to accessibility APIs, and doing so is part of conformance to this specification. When future versions of the WAI-ARIA specification change such features from deprecated to removed, they will be removed from the mappings as well and user agents will no longer be asked to continue support for those features.

Important Terms

Supporting Keyboard Navigation

Enabling keyboard navigation in web applications is a necessary step toward making them accessible. 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.

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 [[UAAG10]], 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 significantly complex widgets, such as a menu or spreadsheet, and uses the arrow keys to navigate within the widget. The changes that WAI-ARIA introduces to 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, 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.

Focus States and Events Table

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

Table of accessibility APIs for focus states and events
  MSAA Microsoft UIA ATK/AT-SPI AX API
Focusable state STATE_SYSTEM_FOCUSABLE Current state reflected in IUIAutomationElement::CurrentIsKeyboardFocusable, can be retrieved with IUIAutomationElement::GetCurrentPropertyValue method using UIA_IsKeyboardFocusablePropertyId property identifier. STATE_FOCUSABLE boolean AXFocused: the accessibilityIsAttributeSettable method returns YES.
Focused state STATE_SYSTEM_FOCUSED Current state reflected in IUIAutomationElement::CurrentHasKeyboardFocus, can be retrieved with IUIAutomationElement::GetCurrentPropertyValue method using UIA_HasKeyboardFocusPropertyId property identifier. STATE_FOCUSED boolean AXFocused
Focus event EVENT_OBJECT_FOCUS Clients can subscribe with IUIAutomation::AddFocusChangedEventHandler using callback interface is IUIAutomationFocusChangedEventHandler object:state-changed:focused and: AXFocusedUIElementChanged

Controlling focus with tabindex

User agents that support WAI-ARIA expand the usage of tabindex, focus, and blur to allow them on all 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 HTML4 specification but is in compliance with HTML5 and SVG2.

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.

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 element that supports the tabindex attribute.
  5. Support the focus() and blur() methods on element interfaces that support the tabindex attribute, e.g., HTMLElement and SVGElement. This allows scripts to move the focus to the 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.

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. User agents are not expected to validate that the active descendant is a descendant of the focused container, as noted in the Author Errors section. 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 (e.g., 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.

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

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:

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:

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

Mapping WAI-ARIA to Accessibility APIs

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 and 1.1, 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 and 1.1 do not define mechanisms for assistive technologies to directly modify WAI-ARIA information.

The terms "exposing", "mapping", and "including" refer to the creation of accessible object nodes within the accessibility tree, and populating these objects with Accessibility API specific states and properties. The accessibility tree is a sub-set of the DOM since not every DOM element is exposed as an accessible object. Whether or not a DOM element is exposed depends on whether it has any semantic import. If it has none, no accessible object is needed, and it is excluded from the accessibility tree. For example, authors might create a nested set of DOM elements solely for visual layout. Those DOM elements are not included as they contain no semantic information. In addtion, some host markup langauges elements have no semantics and are excluded from the accessibility tree. For example, the HTML <base> element is used to define a base URL for all relative URLs within the document. It is important to the browser, which uses the information to resolve relative URLs. But, it has no meaning to end users, is not rendered on screen by the browser, and is excluded from the accessibility tree.

A DOM element is included if it has semantic significance. As a first approximation, it is significant if it has an explicit or implicit WAI-ARIA role, state, or property, is focusable or interactive, or bears a relationship with some other element (e.g., controller-for). It is not semantically significant if it is purely presentational, or is not rendered in any medium. The details and exceptions are described below, but a procedure that provides the gist of how to build the accessibility tree is as follows:

  1. Include elements based on host language rules. These rules are documented in the host language mapping specification for those elements.
  2. Include elements with WAI-ARIA roles and other WAI-ARIA attributes.
  3. Exclude hidden elements and their descendants.
  4. Exclude presentational elements, but include their descendent elements where presentation is not inherited, and include their textual content.
    • In some cases, the presentation/none role is inherited and the descendent elements are excluded.
  5. Include, and possibly add back focusable or otherwise interactive elements.
    • For example, an element marked with both role="presentation" and tabindex="0" is focusable. The presentation role is ignored, and the element is included.
    • In instances where the host language elements support CSS display:none, the element is not focusable even if it has tabindex="0" since there is nothing rendered on screen to focus, and users cannot interact with the element. The tabindex attribute is ignored, and the element is excluded.

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 none or presentation as the first mappable role in the role attribute. However, their exclusion is conditional and depends on other factors. In addition, the element's descendants and text content are generally included. These exceptions and conditions are documented in the section "Presentational Roles Conflict Resolution" in Accessible Rich Internet Applications (WAI-ARIA) 1.1 [[!WAI-ARIA]].
  • Elements, including their descendent elements, that have host language semantics specifying that the element is not displayed, such as CSS display:none, visibility:hidden, or the 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:

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:

Notification of State Changes

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

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", is not correct because it does not properly communicate the additional features of a spin button. The author adds the WAI-ARIA role of spinbutton (<input type="text" role="spinbutton" ...>) so that the control is 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. If the host language element is overridden by a WAI-ARIA role whose semantics or structure is not equivalent to the native host language semantics or to a subclsss of those semantics, then treat any required owned elements of the native role as having role presentation or none.

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.

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:

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.

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.

General rules

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 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. Use the fallback procedure specified in the next rule if only an abstract role is provided. 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. For example, for <table role="foo"> use the HTML table element to determine the platform accessibility API role mapping. For <input type="text" role="bar">, use the mapping for an HTML text input.
  4. When an explicit or inherited role of none or presentation is applied to an element, the user agent MUST implement the rules for the none or the presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [[!WAI-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. User agents SHOULD NOT expose a custom role in MSAA's accRole property.
    • IAccessible2: expose as an object attribute pair (xml-roles:"string")
    • UIA: 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.

Role Mapping Table

Translators: For label text associated with the following table and its toggle buttons, see the mappingTableLabels object in the <head> section of this document.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
WAI-ARIA Role MSAA + IAccessible2 Role + Other IAccessible2 Features UIA Control Type + Other Features ATK/AT-SPI Role AX API[Note 1]
alert ROLE_SYSTEM_ALERT

The user agent SHOULD fire EVENT_SYSTEM_ALERT [Note 2]

 Text

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

 ROLE_ALERT

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

 AXRole: AXGroup
AXSubrole: AXApplicationAlert
AXRoleDescription: 'alert'

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

The user agent SHOULD fire EVENT_SYSTEM_ALERT [Note 2]

 Pane

The user agent SHOULD fire a system alert event.[Note 2]
  • ROLE_DIALOG
  • Interface Window

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

 AXRole: AXGroup
AXSubrole: AXApplictionAlertDialog
AXRoleDescription: 'web alert dialog'

The user agent SHOULD fire a system alert event.[Note 2]
application ROLE_SYSTEM_APPLICATION
  • Control Type is Pane.
  • Localized Control Type is application.
 ROLE_EMBEDDED AXRole: AXGroup
AXSubrole: AXWebApplication
AXRoleDescription: 'web application'
article ROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY

Object attribute xml-roles:article

  • Control Type is Group.
  • Localized Control Type is article.
 ROLE_ARTICLE + do not expose STATE_EDITABLE

Object attribute xml-roles:article

AXRole: AXGroup
AXSubrole: AXDocumentArticle
AXRoleDescription: 'article'
banner [ARIA 1.1] IA2_ROLE_LANDMARK and object attribute xml-roles:banner
  • Control Type is Group.
  • Localized Control Type is banner.
  • Landmark Type is Custom.
  • Localized Landmark Type is banner.
 ROLE_LANDMARK and object attribute xml-roles:banner AXRole: AXGroup
AXSubrole: AXLandmarkBanner
AXRoleDescription: 'banner'
button ROLE_SYSTEM_PUSHBUTTON

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

If aria-pressed is not undefined, expose as IA2_ROLE_TOGGLE_BUTTON		 Button ROLE_PUSH_BUTTON

If aria-pressed is not undefined, expose as ROLE_TOGGLE_BUTTON

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

AXRole: AXCheckBox
AXSubrole: AXToggleButton
AXRoleDescription: 'toggle button'

If aria-pressed is not defined use:

AXRole: AXButton
AXSubrole: <nil>
AXRoleDescription: 'button'
cell [ARIA 1.1]
  • ROLE_SYSTEM_CELL
  • Interface IAccessibleTableCell
  • Control Type is TableItem
  • Supports the selection pattern
  • MUST NOT support the invoke pattern
  • ROLE_TABLE_CELL
  • Interface TableCell
 AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'
checkbox ROLE_SYSTEM_CHECKBUTTON

Object attribute checkable:true

 Checkbox ROLE_CHECK_BOX + STATE_CHECKABLE AXRole: AXCheckBox
AXSubrole: <nil>
AXRoleDescription: 'check box'
columnheader
  • ROLE_SYSTEM_COLUMNHEADER
  • Interface IAccessibleTableCell
  • Interface IAccessibleTable2 for the container grid role
 HeaderItem
  • ROLE_COLUMN_HEADER
  • Interface TableCell
 AXRole: AXCell or AXSortButton if using aria-sort
AXSubrole: <nil>
AXRoleDescription: '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.
combobox ROLE_SYSTEM_COMBOBOX + STATE_SYSTEM_HASPOPUP.

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

 Combobox ROLE_COMBO_BOX + STATE_EXPANDABLE + STATE_HAS_POPUP AXRole: AXComboBox
AXSubrole: <nil>
AXRoleDescription: 'combo box'
complementary [ARIA 1.1] IA2_ROLE_LANDMARK and object attribute xml-roles:complementary
  • Control Type is Group.
  • Localized Control Type is complementary.
  • Landmark Type is Custom.
  • Localized Landmark Type is complementary.
 ROLE_LANDMARK and object attribute xml-roles:complementary AXRole: AXGroup
AXSubrole: AXLandmarkComplementary
AXRoleDescription: 'complementary'
contentinfo [ARIA 1.1] IA2_ROLE_LANDMARK and object attribute xml-roles:contentinfo
  • Control Type is Group.
  • Localized Control Type is content information.
  • Landmark Type is Custom.
  • Localized Landmark Type is content information.
 ROLE_LANDMARK and object attribute xml-roles:contentinfo AXRole: AXGroup
AXSubrole: AXLandmarkContentInfo
AXRoleDescription: 'content'
definition Object attribute xml-roles:definition
  • Control Type is Group.
  • Localized Control Type is definition.
 Object attribute xml-roles:definition AXRole: AXGroup
AXSubrole: AXDefinition
AXRoleDescription: 'definition'
dialog ROLE_SYSTEM_DIALOG Pane
  • ROLE_DIALOG
  • Interface Window
 AXRole: AXGroup
AXSubrole: AXApplicationDialog
AXRoleDescription: 'web dialog'
directory ROLE_SYSTEM_LIST List ROLE_LIST AXRole: AXList
AXSubrole: AXContentList
AXRoleDescription: 'content list'
document ROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY Document ROLE_DOCUMENT_FRAME + do not expose STATE_EDITABLE AXRole: AXGroup
AXSubrole: AXDocument
AXRoleDescription: 'document'
feed [ARIA 1.1] ROLE_SYSTEM_GROUPING + object attribute xml-roles:feed
  • Control Type is Group
  • Localized Control Type is "feed"
 ROLE_PANEL + object attribute xml-roles:feed Need to verify. AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
figure [ARIA 1.1] ROLE_SYSTEM_GROUPING + object attribute xml-roles:figure
  • Control Type is Group
  • Localized Control Type is "figure"
 ROLE_PANEL + object attribute xml-roles:figure AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'figure'
form [ARIA 1.1] IA2_ROLE_FORM + object attribute xml-roles:form
  • Control Type is Group.
  • Localized Control Type is form.
  • Landmark Type is Form.
  • Localized Landmark Type is form (default for this Landmark Type).
 ROLE_LANDMARK + object attribute xml-roles:form AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
grid
  • ROLE_SYSTEM_TABLE + object attribute xml-roles:grid
  • Implement Interface IAccessibleTable2
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 DataGrid with selection pattern
  • ROLE_TABLE + object attribute xml-roles:grid
  • Implement Interfaces Table and Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

 AXRole: AXTable
AXSubrole: <nil>
AXRoleDescription: 'grid'
gridcell
  • ROLE_SYSTEM_CELL
  • Interface IAccessibleTableCell
 DataItem

Also requires selectionitem pattern; selectionContainer property must reference the parent grid object
  • ROLE_TABLE_CELL
  • Interface TableCell
 AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'
group ROLE_SYSTEM_GROUPING Group ROLE_PANEL AXRole: AXGroup
AXSubrole: AXApplicationGroup [ARIA 1.1]
AXRoleDescription: 'group'
heading – The heading level is specified by the aria-level property. Expose as object attribute xml-roles:heading.

Also, expose IA2_ROLE_HEADING
  • Control Type is Text.
  • Localized Control Type is heading.
 ROLE_HEADING AXRole: AXHeading
AXSubrole: <nil>
AXRoleDescription: 'heading'
img
  • ROLE_SYSTEM_GRAPHIC
  • Interface IAccessibleImage
 Image
  • ROLE_IMAGE
  • Interface Image
 AXRole: AXImage
AXSubrole: <nil>
AXRoleDescription: 'image'
list ROLE_SYSTEM_LIST + STATE_SYSTEM_READONLY

List

When the list contains listitems, it must implement the selection pattern.

 ROLE_LIST + do not expose STATE_EDITABLE AXRole: AXList
AXSubrole: AXContentList
AXRoleDescription: 'content list'
listbox
  • ROLE_SYSTEM_LIST
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 List
  • ROLE_LIST_BOX
  • Implement Interface Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

Special case: if a listbox has a parent or is owned by (via aria-owns) a combobox, expose as ROLE_MENU.

AXRole: AXList
AXSubrole: <nil>
AXRoleDescription: 'list'
listitem ROLE_SYSTEM_LISTITEM + STATE_SYSTEM_READONLY

ListItem

Also requires selectionitem pattern; selectionContainer property must reference the parent list object

 ROLE_LIST_ITEM + do not expose STATE_EDITABLE AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
log Object attributes xml-roles:log;container-live:polite;live:polite;container-live-role:log.
  • Control Type is Group.
  • Localized Control Type is log.
  • LiveSettingProperty = Polite (1).
 ROLE_LOG and object attributes xml-roles:log;container-live:polite;live:polite;container-live-role:log. AXRole: AXGroup
AXSubrole: AXApplicationLog
AXRoleDescription: 'log'
main [ARIA 1.1] IA2_ROLE_LANDMARK and object attribute xml-roles:main
  • Control Type is Group.
  • Localized Control Type is main.
  • Landmark Type is Main.
  • Localized Landmark Type is main (default for this Landmark Type).
 ROLE_LANDMARK and object attribute xml-roles:main AXRole: AXGroup
AXSubrole: AXLandmarkMain
AXRoleDescription: 'main'
marquee ROLE_SYSTEM_ANIMATION + object attributes xml-roles:marquee;container-live:off;live:off Text ROLE_MARQUEE + object attributes container-live:off;live:off AXRole: AXGroup
AXSubrole: AXApplicationMarquee
AXRoleDescription: 'marquee'
math ROLE_SYSTEM_EQUATION
  • Control Type is Group.
  • Localized Control Type is math.
 ROLE_MATH AXRole: AXGroup
AXSubrole: AXDocumentMath
AXRoleDescription: 'math'
menu
  • ROLE_SYSTEM_MENUPOPUP
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 Menu
  • ROLE_MENU
  • Implement Interface Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

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.

AXRole: AXMenu
AXSubrole: <nil>
AXRoleDescription: 'menu'
menubar
  • ROLE_SYSTEM_MENUBAR
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 MenuBar
  • ROLE_MENU_BAR
  • Implement Interface Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

 AXRole: AXMenuBar
AXSubrole: <nil>
AXRoleDescription: 'menu bar'
menuitem ROLE_SYSTEM_MENUITEM MenuItem ROLE_MENU_ITEM 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

AXRole: AXMenuItem
AXSubrole: <nil>
AXRoleDescription: 'menu item'
menuitemcheckbox ROLE_SYSTEM_CHECKBUTTON or ROLE_SYSTEM_MENUITEM

IA2_ROLE_CHECK_MENU_ITEM + object attribute checkable:true

 MenuItem + Toggle Pattern ROLE_CHECK_MENU_ITEM + STATE_CHECKABLE AXRole: AXMenuItem
AXSubrole: <nil>
AXRoleDescription: 'menu item'

If aria-checked="true": AXMenuItemMarkChar ✓
Otherwise: AXMenuItemMarkChar <nil>
menuitemradio ROLE_SYSTEM_RADIOBUTTON or ROLE_SYSTEM_MENUITEM

IA2_ROLE_RADIO_MENU_ITEM + object attribute checkable:true

 MenuItem + Toggle Pattern + SelectionItem Pattern

If aria-checked="true":

  1. Toggle.ToggleState = On (1)
  2. SelectionItem.IsSelected = True

If aria-checked="false":

  1. Toggle.ToggleState = Off (0)
  2. SelectionItem.IsSelected = False

If aria-checked="mixed" or is undefined: treat as false

 ROLE_RADIO_MENU_ITEM + STATE_CHECKABLE AXRole: AXMenuItem
AXSubrole: <nil>
AXRoleDescription: 'menu item'

If aria-checked="true": AXMenuItemMarkChar ✓.
Otherwise: AXMenuItemMarkChar <nil>
navigation [ARIA 1.1] IA2_ROLE_LANDMARK and object attribute xml-roles:navigation
  • Control Type is Group.
  • Localized Control Type is navigation.
  • Landmark Type is Navigation.
  • Localized Landmark Type is navigation (default for this Landmark Type).
 ROLE_LANDMARK and object attribute xml-roles:navigation AXRole: AXGroup
AXSubrole: AXLandmarkNavigation
AXRoleDescription: 'navigation'
none [ARIA 1.1]

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it as IA2_ROLE_TEXTFRAME. User agents SHOULD prune empty descendants from the accessibility tree.

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it using the text pattern. User agents SHOULD prune empty descendants from the accessibility tree.

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it as ROLE_SECTION. User agents SHOULD prune empty descendants from the accessibility tree.

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it as AXGroup. User agents SHOULD prune empty descendants from the accessibility tree.

note IA2_ROLE_NOTE
  • Control Type is Group.
  • Localized Control Type is note.
 ROLE_COMMENT AXRole: AXGroup
AXSubrole: AXDocumentNote
AXRoleDescription: 'note'
option – If aria-selected is undefined treat as aria-selected = "false". ROLE_SYSTEM_LISTITEM

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

 ListItem + Invoke pattern ROLE_LIST_ITEM

If aria-checked is not undefined, support STATE_CHECKABLE

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

AXRole: AXStaticText
AXSubrole: <nil>
AXRoleDescription: 'text'
presentation

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it as IA2_ROLE_TEXTFRAME. User agents SHOULD prune empty descendants from the accessibility tree.

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it using the text pattern. User agents SHOULD prune empty descendants from the accessibility tree.

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it as ROLE_SECTION. User agents SHOULD prune empty descendants from the accessibility tree.

See General rules for exposing WAI-ARIA semantics.

For objects that have required owned descendants (e.g., a grid owns gridcells, a list owns listitems), and the descendant is in the accessibility tree, expose it as AXGroup. User agents SHOULD prune empty descendants from the accessibility tree.

progressbar
  • ROLE_SYSTEM_PROGRESSBAR + STATE_SYSTEM_READONLY
  • Interface IAcesssibleValue

ProgressBar

If any of the aria-valuenow, aria-valuemax, or aria-valuemin properties are present, also implement the RangeValue pattern.
  • ROLE_PROGRESS_BAR + do not expose STATE_EDITABLE
  • Interface Value

Because WAI-ARIA does not support modifying the value via the accessibility API, user agents MUST return false for all Value methods that provide a means to modify the value.

 AXRole: AXProgressIndicator
AXSubrole: <nil>
AXRoleDescription: 'progress indicator'
radio ROLE_SYSTEM_RADIOBUTTON RadioButton + Toggle Pattern + SelectionItem Pattern

If aria-checked="true":

  1. Toggle.ToggleState = On (1)
  2. SelectionItem.IsSelected = True

If aria-checked="false":

  1. Toggle.ToggleState = Off (0)
  2. SelectionItem.IsSelected = False

If aria-checked="mixed" or is undefined: treat as false

 ROLE_RADIO_BUTTON AXRole: AXRadioButton
AXSubrole: <nil>
AXRoleDescription: 'radio button'
radiogroup ROLE_SYSTEM_GROUPING List ROLE_GROUPING AXRole: AXRadioGroup
AXSubrole: <nil>
AXRoleDescription: 'radio group'
region [ARIA 1.1]

IA2_ROLE_LANDMARK and object attribute xml-roles:region

Special case: if the region does not have an accessible name, do not expose the element as a landmark. Use the native host language role of the element instead.
  • Control Type is Group.
  • Localized Control Type is region.
  • Landmark Type is Custom.
  • Localized Landmark Type is region.

Special case: if the region does not have an accessible name, do not expose the element as a landmark. Use the native host language role of the element instead.

ROLE_LANDMARK and object attribute xml-roles:region

Special case: if the region does not have an accessible name, do not expose the element as a landmark. Use the native host language role of the element instead.

 AXRole: AXGroup
AXSubrole: AXLandmarkRegion
AXRoleDescription: 'region'

Special case: if the region does not have an accessible name, do not expose the element as a landmark. Use the native host language role of the element instead.
row
  • ROLE_SYSTEM_ROW unless inside a tree or treegrid, in which case ROLE_SYSTEM_OUTLINEITEM
  • Interface IAccessibleTable2 for the container grid role

DataItem

Also requires selectionitem pattern

 ROLE_TABLE_ROW AXRole: AXRow
AXSubrole: <nil>
AXRoleDescription: 'row'
rowgroup – 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_GROUPING group ROLE_PANEL Not mapped
rowheader
  • ROLE_SYSTEM_ROWHEADER
  • Interface IAccessibleTableCell
  • Interface IAccessibleTable2 for the container grid role
 HeaderItem
  • ROLE_ROW_HEADER
  • Interface TableCell
 AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'

Parent table also implements AXRowHeaderUIElements property that is a list of pointers to the row header cells
scrollbar
  • ROLE_SYSTEM_SCROLLBAR
  • Interface IAcesssibleValue
  • Control Type is ScrollBar
  • Implement Range Control Pattern
  • ROLE_SCROLLBAR
  • Interface Value

Because WAI-ARIA does not support modifying the value via the accessibility API, user agents MUST return false for all Value methods that provide a means to modify the value.

 AXRole: AXScrollBar
AXSubrole: <nil>
AXRoleDescription: 'scroll bar'
separator
  • If a static separator: ROLE_SYSTEM_SEPARATOR
  • [ARIA 1.1] If a focusable splitter, also expose:
    • IAccessibleValue interface
  • If a static separator: Separator
  • [ARIA 1.1] If a focusable splitter, also expose:
    • Control Type: Thumb
  • If a static separator: ROLE_SEPARATOR
  • [ARIA 1.1] If a focusable splitter, also expose:
    • Value interface
 AXRole: AXSplitter
AXSubrole: <nil>
AXRoleDescription: 'splitter'
slider
  • ROLE_SYSTEM_SLIDER
  • Interface IAcesssibleValue
  • Control Type is Slider
  • Implement Range Control Pattern
  • ROLE_SLIDER
  • Interface Value

Because WAI-ARIA does not support modifying the value via the accessibility API, user agents MUST return false for all Value methods that provide a means to modify the value.

 AXRole: AXSlider
AXSubrole: <nil>
AXRoleDescription: 'slider'
spinbutton
  • ROLE_SYSTEM_SPINBUTTON
  • Interface IAcesssibleValue
  • Control Type is Spinner
  • Implement Range Control Pattern
  • ROLE_SPIN_BUTTON
  • Interface Value

Because WAI-ARIA does not support modifying the value via the accessibility API, user agents MUST return false for all Value methods that provide a means to modify the value.

 AXRole: AXIncrementor
AXSubrole: <nil>
AXRoleDescription: 'stepper'
status

ROLE_SYSTEM_STATUSBAR + object attributes container-live:polite;live:polite;container-live-role:status
  • Control Type: Group
  • Localized Control Type: status
  • LiveSettingProperty = Polite (1)
 ROLE_STATUSBAR + object attributes container-live:polite;live:polite;container-live-role:status AXRole: AXGroup
AXSubrole: AXApplicationStatus
AXRoleDescription: 'status'
switch [ARIA 1.1] IA2_ROLE_TOGGLE_BUTTON + object attribute xml-roles:switch Control Type is Button + Toggle Pattern. Localized Control Type is "toggleswitch". ROLE_TOGGLE_BUTTON AXRole: AXCheckBox
AXSubrole: AXSwitch
AXRoleDescription: 'switch'
tab – If aria-selected is undefined treat as aria-selected = "false". ROLE_SYSTEM_PAGETAB.

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

 TabItem ROLE_PAGE_TAB. Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby. AXRole: AXRadioButton
AXSubrole: <nil>
AXRoleDescription: 'tab'
table [ARIA 1.1]
  • ROLE_SYSTEM_TABLE + object attribute xml-roles:table
  • Interface IAccessibleTable2
  • Control Type is Table.
  • Implements the grid and table patterns
  • ROLE_TABLE + object attribute xml-roles:table
  • Interface Table
 AXRole: AXTable
AXSubrole: <nil>
AXRoleDescription: 'grid'
tablist
  • ROLE_SYSTEM_PAGETABLIST
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 Tab

Also requires selection pattern
  • ROLE_PAGE_TAB_LIST
  • Implement Interface Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

 AXRole: AXTabGroup
AXSubrole: <nil>
AXRoleDescription: 'tab group'
tabpanel ROLE_SYSTEM_PANE or ROLE_SYSTEM_PROPERTYPAGE Pane ROLE_SCROLL_PANE AXRole: AXGroup
AXSubrole: TabPanel
AXRoleDescription: 'tab panel'
term [ARIA 1.1]
  • ROLE_SYSTEM_LISTITEM
  • STATE_SYSTEM_READONLY
 Control Type is ListItem
  • ROLE_DESCRIPTION_TERM
  • Interfaces: AtkText; AtkHypertext
 AXRole: AXGroup
AXSubrole: AXTerm
AXRoleDescription: 'term'
textbox
  • ROLE_SYSTEM_TEXT
  • IA2_STATE_SINGLE_LINE if aria-multiline is not "true"
 Control Type is Edit

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

If aria-multiline="true" use:
AXRole: AXTextArea
AXSubrole: <nil>
AXRoleDescription: 'text entry area'
timer Object attribute xml-roles:timer;container-live:off;live:off;container-live-role:timer Expose as text string in AriaRole ROLE_TIMER + object attributes container-live:off;live:off;container-live-role:timer AXRole: AXGroup
AXSubrole: AXApplicationTimer
AXRoleDescription: 'timer'
toolbar ROLE_SYSTEM_TOOLBAR ToolBar ROLE_TOOL_BAR AXRole: AXToolbar
AXSubrole: <nil>
AXRoleDescription: 'toolbar'
tooltip ROLE_SYSTEM_TOOLTIP ToolTip ROLE_TOOL_TIP AXRole: AXGroup
AXSubrole: AXUserInterfaceTooltip
AXRoleDescription: 'tooltip'
tree
  • ROLE_SYSTEM_OUTLINE
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 Tree
  • ROLE_TREE
  • Implement Interface Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

 AXRole: AXOutline
AXSubrole: <nil>
AXRoleDescription: 'outline'
treegrid
  • ROLE_SYSTEM_OUTLINE
  • Implement Interface IAccessibleTable2
  • Implement Methods IAccessible::accSelect() and IAccessible::get_accSelection()
 DataGrid
  • ROLE_TREE_TABLE
  • Implement Interfaces Table and Selection

Because WAI-ARIA does not support modifying the selection via the accessibility API, user agents MUST return false for all Selection methods that provide a means to modify the selection.

 AXRole: AXTable
AXSubrole: <nil>
AXRoleDescription: 'table'
treeitem ROLE_SYSTEM_OUTLINEITEM + if aria-checked is not undefined, support object attribute checkable:true TreeItem ROLE_TREE_ITEM + if aria-checked is not undefined, support STATE_CHECKABLE AXRole: AXRow
AXSubrole: AXOutlineRow
AXRoleDescription: '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).

State and Property Mapping

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

General rules

  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 [[!WAI-ARIA]]]. Where the author has not provided values for required attributes, user agents SHOULD process as if the default value 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, 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: 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 none or presentation is applied to an element, the user agent MUST implement the rules for the none or the presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [[!WAI-ARIA]]].

State and Property Mapping Table

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. Its absence not only indicates that the accessible object is not grabbed, but further defines it as not grab-able. These cases are marked as "Not mapped" without an asterisk.

Translators: For label text associated with the following table and its toggle buttons, see the mappingTableLabels object in the <head> section of this document.

WAI-ARIA state and property mapping rule table
WAI-ARIA State or Property MSAA + IAccessible2 UIA ATK/AT-SPI AX API
aria-activedescendant 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_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 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 atomic=true in AriaProperties

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)

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.
 Expose atomic=false in AriaProperties

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"

Object attribute autocomplete:<value>

Expose the IA2_STATE_SUPPORTS_AUTOCOMPLETION equivalent state

 Expose autocomplete=<value> in AriaProperties

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 state Expose busy=true in AriaProperties Expose the STATE_BUSY state boolean AXElementBusy: YES
aria-busy="false" (state) (default) Clear the STATE_SYSTEM_BUSY state Expose busy=false in AriaProperties Clear the STATE_BUSY state boolean AXElementBusy: NO
aria-checked="true" (state)

Set the STATE_SYSTEM_CHECKED state

Expose object attribute checkable:true

Expose as ToggleState property in Toggle Control Pattern.

Toggle.ToggleState = On (1)

Expose STATE_CHECKABLE

Set the STATE_CHECKED state

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

Clear the STATE_SYSTEM_CHECKED state

Expose object attribute checkable:true

Expose as ToggleState property in Toggle Control Pattern.

Toggle.ToggleState = Off (0)

Clear the STATE_CHECKED state

Expose STATE_CHECKABLE

 

 AXValue: 0
aria-checked="mixed" (state) – Treat as "false" for radio, menuitemradio, and switch roles. Set the STATE_SYSTEM_MIXED state

Expose object attribute checkable:true

Expose as ToggleState property in Toggle Control Pattern.

Toggle.ToggleState = Indeterminate (2)

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

Expose STATE_CHECKABLE

 AXValue: 2
aria-checked is undefined (state) – Treat as "false" for checkbox, menuitemcheckbox, radio, menuitemradio, and switch roles. Not mapped Not mapped Not mapped Not mapped
aria-colcount [ARIA 1.1]
  • Expose the value of aria-colcount in object attribute colcount:<value>.
  • Expose via groupPosition() on cell and gridcell
  • Implement Grid Control Pattern
  • Set ColumnCount property
  • Expose the value of aria-colcount in object attribute colcount:<value>.
  • Expose via AccessibleTable interface method atk_table_get_n_columns()
 AXARIAColumnCount: <value>
aria-colindex [ARIA 1.1]
  • Expose the value of aria-colindex in object attribute colindex:<value>.
  • Expose via groupPosition() on cell and gridcell
  • Implement GridItem Control Pattern
  • Set Column property
  • Note: UIA values are zero-based
  • Expose the value of aria-colindex in object attribute colindex:<value>.
  • Expose via AccessibleTableCell interface method atk_table_cell_get_position()
 AXARIAColumnIndex: <value>, 0-based (aria-colindex is 1-based).
aria-colspan [ARIA 1.1]
  • Expose the value of aria-colspan in object attribute colspan:<value>.
  • Expose via IAccessibleTableCell::columnExtent
  • Implement GridItem Control Pattern
  • Set ColumnSpan property
  • Expose the value of aria-colspan in object attribute colspan:<value>.
  • Expose via AccessibleTableCell interface method atk_table_cell_get_row_column_span()
 AXColumnIndexRange:
location=<column index>
length=<colspan value>,
where location is 0-based.
aria-controls

Expose pointer to the accessible object in IA2_RELATION_CONTROLLER_FOR

Expose reverse relations as described in Relations.

 Expose pointer to the accessible object using ControllerFor property

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-current (state) [ARIA 1.1]
  • Expose the value of aria-current in object attribute current:<value>.
 Expose current=<value> in AriaProperties.
  • Set STATE_ACTIVE.
  • Expose the value of aria-current in object attribute current:<value>.
 AXARIACurrent: <value>.
aria-current is undefined (state) [ARIA 1.1] Not mapped*. Not mapped*. Not mapped*. Not mapped*.
aria-describedby

Use in calculating the accessible Description as described in Name Computation. Expose in accDescription property.

If the referenced objects are in the accessibility tree, expose pointers to them using 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 FullDescription property.

If the referenced objects are in the accessibility tree, expose pointers to the referenced accessible objects using the DescribedBy property.

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

If the referenced objects are 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 1.1] aria-details

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

If the referenced object is in the accessibility tree, the DescribedBy array property contains an entry pointing to the accessible object.

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

 TBD.
aria-disabled="true" (state) Set STATE_SYSTEM_UNAVAILABLE

Propagate to all descendants of the element with STATE_SYSTEM_FOCUSABLE

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

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

Not mapped if not specified by the author.

 Not mapped*

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

Not mapped if not specified by the author.

 Not mapped*
[ARIA 1.1] aria-errormessage

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

 Expose pointer to the target accessible object using ControllerFor property.

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

 TBD.
aria-expanded="true" (state) Set STATE_SYSTEM_EXPANDED Expose as "expanded" in ExpandCollapseState property of ExpandCollapse Control Pattern Expose STATE_EXPANDABLE and STATE_EXPANDED boolean AXExpanded: YES
aria-expanded="false" (state) Set STATE_SYSTEM_COLLAPSED Expose as "collapsed" in ExpandCollapseState property of ExpandCollapse Control Pattern Expose STATE_EXPANDABLE boolean AXExpanded: NO
aria-expanded is undefined (state) (default) Not mapped Not mapped Not mapped Not mapped
aria-flowto Expose reference to the accessible object in IA2_RELATION_FLOW_TO

Expose reverse relations as described in Relations.

 Expose a reference to the accessible object in FlowsTo property Expose reference to the accessible object in RELATION_FLOWS_TO

Expose reverse relations as described in Relations.

 array AXLinkedUIElements contains pointers to nodes matching IDREFs
aria-grabbed="true"(state) Object attribute grabbed:true Expose as grabbed=true in AriaProperties Object attribute grabbed:true boolean AXGrabbed: YES
aria-grabbed="false"(state) Object attribute grabbed:false Expose as grabbed=false in AriaProperties Object attribute grabbed:false boolean AXGrabbed: NO
aria-grabbed is undefined (state) (default) Not mapped Not mapped Not mapped Not mapped
aria-haspopup="true"
  • Expose as STATE_SYSTEM_HASPOPUP. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU
  • Expose as object attribute haspopup:true
 Implement ExpandCollapse Control Pattern. If the element has aria-expanded (state), set the ExpandCollapseState property to match it.
  • Expose STATE_HAS_POPUP
  • Expose as object attribute haspopup:true
 Expose AXShowMenu and AXPress actions
aria-haspopup="false" (default)
  • Clear the HASPOPUP state. If specified on a push button, change the role to ROLE_SYSTEM_BUTTONMENU
  • Expose as object attribute haspopup:false
 Not mapped* Not mapped* Not mapped*
[ARIA 1.1] aria-haspopup="dialog"
  • Expose as STATE_SYSTEM_HASPOPUP
  • Expose as object attribute haspopup:dialog
 Implement ExpandCollapse Control Pattern. If the element has aria-expanded (state), set the ExpandCollapseState property to match it.
  • Expose STATE_HAS_POPUP
  • Expose as object attribute haspopup:dialog
 Expose AXShowMenu and AXPress actions
[ARIA 1.1] aria-haspopup="listbox" (default for role combobox)
  • Expose as STATE_SYSTEM_HASPOPUP
  • Expose as object attribute haspopup:listbox
 Implement ExpandCollapse Control Pattern. If the element has aria-expanded (state), set the ExpandCollapseState property to match it.
  • Expose STATE_HAS_POPUP
  • Expose as object attribute haspopup:listbox
 Expose AXShowMenu and AXPress actions
[ARIA 1.1] aria-haspopup="menu"
  • Expose as STATE_SYSTEM_HASPOPUP. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU
  • Expose as object attribute haspopup:menu
 Implement ExpandCollapse Control Pattern. If the element has aria-expanded (state), set the ExpandCollapseState property to match it.
  • Expose STATE_HAS_POPUP
  • Expose as object attribute haspopup:menu
 Expose AXShowMenu and AXPress actions
[ARIA 1.1] aria-haspopup="tree"
  • Expose as STATE_SYSTEM_HASPOPUP
  • Expose as object attribute haspopup:tree
 Implement ExpandCollapse Control Pattern. If the element has aria-expanded (state), set the ExpandCollapseState property to match it.
  • Expose STATE_HAS_POPUP
  • Expose as object attribute haspopup:tree
 Expose AXShowMenu and AXPress actions
aria-hidden="true" (state)

See Including Elements in the Accessibility Tree.

Element SHOULD NOT be exposed, unless it is focused or fires an accessibility event. If the object is exposed in the accessibility tree, map all attributes as normal, and expose object attribute hidden:true.

See Including Elements in the Accessibility Tree.

Element SHOULD NOT be exposed, unless it is focused or fires an accessibility event. If the object is exposed in the accessibility tree, map all attributes as normal, and expose hidden=true in AriaProperties.

See Including Elements in the Accessibility Tree.

Element SHOULD NOT be exposed, unless it is focused or fires an accessibility event. If the object is exposed in the accessibility tree, map all attributes as normal, and expose object attribute hidden:true.

Not exposed in AX API unless focused. If focused, expose as normal.
aria-hidden="false" (state) (default) Not mapped Not mapped Not mapped Not mapped
aria-invalid="true", "spelling", or "grammar" (state)
  • Set IA2_STATE_INVALID_ENTRY
  • Expose invalid:<value> as a text attribute (not an object attribute).
  • If aria-invalid="true", expose false in IsDataValidForForm property,
  • Otherwise expose <value> in IsDataValidForForm property
  • Set STATE_INVALID_ENTRY
  • Expose invalid:<value> as a text attribute (not an object attribute).
 AXInvalid: <value>
aria-invalid=<unknown value>
  • Set IA2_STATE_INVALID_ENTRY
  • Expose invalid:true as a text attribute (not an object attribute).
 Expose false in IsDataValidForForm property
  • Set STATE_INVALID_ENTRY
  • Expose invalid:true as a text attribute (not an object attribute).
 AXInvalid: true
aria-invalid="false" (state) (default) Clear IA2_STATE_INVALID_ENTRY or equivalent state. Expose true in IsDataValidForForm property Not mapped* AXInvalid: "false"
[ARIA 1.1] aria-keyshortcuts Expose in accKeyboardShortcut property AcceleratorKey = the contents of aria-keyshortcuts Expose the value of aria-keyshortcuts in object attribute keyshortcuts:<value>. Not mapped
aria-label 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 Name 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-labelledby

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

If the referenced objects are in the accessibility tree expose pointers to them using 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 Name property.

If the referenced objects are in the accessibility tree, expose pointers to them using the LabeledBy property.

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

If the referenced objects are in the accessibility tree, expose pointers to them using 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 AriaProperties.

When used on a heading, expose StyleId_Headingn where n is the heading level. UIA supports up to heading level 9.

 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)

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.

 Set LiveSetting Property to "assertive" 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) 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.

 Set LiveSetting Property to "polite" 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) 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.

 Set LiveSetting property to "off" 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-modal="true" Set IA2_STATE_MODAL Set IsModal property of Window control pattern to "true" Set STATE_MODAL Prune the accessibility tree such that the background content is no longer exposed. No specific property is set on the accessible object that corresponds to the element with aria-modal="true". Only the tree whose root is that modal accessible object is exposed.
aria-modal="false" Clear IA2_STATE_MODAL Set IsModal property of Window control pattern to "false" Clear STATE_MODAL Grow the accessibility tree such that the background content is exposed. No specific property is set on the accessible object that corresponds to the element with aria-modal="false".
aria-multiline="true" Set the IA2_MULTI_LINE state and clear IA2_SINGLE_LINE Expose as multiline=true in AriaProperties Set STATE_MULTI_LINE and clear STATE_SINGLE_LINE

Not mapped

See textbox in the Role Mapping Table for more information.
aria-multiline="false" (default) Clear the IA2_MULTI_LINE state, and set IA2_SINGLE_LINE Not mapped* Set STATE_SINGLE_LINE and clear STATE_MULTI_LINE

Not mapped

See textbox in the Role Mapping Table for more information.
aria-multiselectable="true"

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

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

See Selection for details.

Set CanSelectMultiple property on the Selection Control Pattern.

See Selection for details.

Expose STATE_MULTISELECTABLE

See Selection for details.

Not mapped

See Selection for details.
aria-multiselectable="false" (default) Clear the STATE_SYSTEM_MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match STATE_SYSTEM_MULTISELECTABLE.

See Selection for details.

 Not mapped* Not mapped* Not mapped*
aria-orientation="horizontal" (default)
  • Set: IA2_STATE_HORIZONTAL
  • Clear: IA2_STATE_VERTICAL
 Set Orientation property to "horizontal" Set STATE_HORIZONTAL AXOrientation: AXHorizontalOrientation
aria-orientation="vertical" (default for role scrollbar)
  • Set: IA2_STATE_VERTICAL
  • Clear: IA2_STATE_HORIZONTAL
 Set Orientation Property to "vertical" Set STATE_VERTICAL AXOrientation: AXVerticalOrientation
aria-owns

The accessibility tree is not modified. [ARIA 1.1: no longer true?]

Expose reverse relations as described in Relations

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

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

Expose reverse relations as described in Relations

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

array AXOwns contains pointers to nodes matching IDREFs
[ARIA 1.1] aria-placeholder

Expose as object attribute placeholder-text:<value>.

Expose as placeholder=<value> in AriaProperties.

Expose as object attribute placeholder-text:<value>.

AXPlaceholderValue: <value>.

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 object attribute posinset:<value> and in groupPosition().

Expose as posinset=<value> in AriaProperties.

Expose as object attribute posinset:<value>.

 AXARIAPosInSet: <value>
aria-pressed="true" (state) Set the STATE_SYSTEM_PRESSED state.

If on a button, expose the role as IA2_ROLE_TOGGLE_BUTTON.

Expose as ToggleState property of Toggle Control Pattern

Toggle.ToggleState = On (1)

 Expose STATE_PRESSED.

If on a button, expose the role as ROLE_TOGGLE_BUTTON.

AXValue: 1
aria-pressed="mixed" (state) Set the STATE_SYSTEM_PRESSED state.

If on a button, expose the role as IA2_ROLE_TOGGLE_BUTTON.

Expose as ToggleState property of Toggle Control Pattern

Toggle.ToggleState = Indeterminate (2)

 Expose STATE_INDETERMINATE/STATE_SYSTEM_MIXED.

If on a button, expose the role as ROLE_TOGGLE_BUTTON.

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

If on a button, expose the role as IA2_ROLE_TOGGLE_BUTTON.

Expose as ToggleState property of Toggle Control Pattern

Toggle.ToggleState = Off (3)

 If on a button, expose the role as ROLE_TOGGLE_BUTTON. AXValue: 0
aria-pressed is undefined (state) (default) Not mapped* Not mapped* Not mapped* Not mapped*
aria-readonly="true"

Expose as STATE_SYSTEM_READONLY

For elements with role='gridcell', and no aria-readonly property, the grid cell MUST inherit any author aria-readonly='true' property from the containing grid or treegrid and expose STATE_SYSTEM_READONLY.

Set Value.IsReadOnly="true"

For elements with role='gridcell', and no aria-readonly property, the grid cell MUST inherit any author aria-readonly='true' property from the containing grid or treegrid and expose Value.IsReadOnly="true".

[ARIA 1.1]

  • STATE_READ_ONLY
  • Clear STATE_EDITABLE if on a textbox

For elements with role='gridcell', and no aria-readonly property, the grid cell MUST inherit any author aria-readonly='true' property from the containing grid or treegrid and expose STATE_READ_ONLY.

AXValue: the accessibilityIsAttributeSettable method returns NO.

For elements with role='gridcell', and no aria-readonly property, the grid cell MUST inherit any author aria-readonly='true' property from the containing grid or treegrid and expose AXValue such that the accessibilityIsAttributeSettable method returns NO.
aria-readonly="false" (default) Expose IA2_STATE_EDITABLE Set Value.IsReadOnly="false"

[ARIA 1.1] Expose STATE_EDITABLE if role is textbox; otherwise, not mapped

 AXValue: the accessibilityIsAttributeSettable method returns YES.
aria-relevant="additions", "removals", "text", or "all"

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.

 Expose as relevant=<value> in AriaProperties

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 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 relevant=additions text in AriaProperties

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 IA2_STATE_REQUIRED Expose as IsrequiredForForm property. Expose STATE_REQUIRED boolean AXRequired: YES
aria-required="false" (default) Not mapped* Not mapped* Not mapped* Not mapped*
[ARIA 1.1] aria-roledescription Expose the description string in IAccessible2 localizedExtendedRole property. Localized Control Type is <value>. Expose the description string in object attribute roledescription:<value>. AXRoleDescription: '<value>'.
[ARIA 1.1] aria-roledescription=""(empty or whitespace characters) Not mapped Localized Control Type is defined as that specified for the role of the element:
  • based on the explicit role if the role attribute is provided; otherwise,
  • based on the implicit role for the host language.
 Not mapped AXRoleDescription is defined as that specified for the role of the element:
  • based on the explicit role if the role attribute is provided; otherwise,
  • based on the implicit role for the host language.
aria-rowcount [ARIA 1.1]
  • Expose the value of aria-rowcount in object attribute rowcount:<value>.
  • Expose via groupPosition() interface on row
  • Implement Grid Control Pattern
  • Set RowCount property
  • Expose the value of aria-rowcount in object attribute rowcount:<value>.
  • Expose via AccessibleTable interface method atk_table_get_n_rows()
 AXARIARowCount: <value>
aria-rowindex [ARIA 1.1]
  • Expose the value of aria-rowindex in object attribute rowindex:<value>.
  • Expose via groupPosition() on row
  • Implement GridItem Control Pattern
  • Set Row property
  • Note: UIA values are zero-based
  • Expose the value of aria-rowindex in object attribute rowindex:<value>.
  • Expose via AccessibleTableCell interface method atk_table_cell_get_position()
 AXARIARowIndex: <value>, 0-based (aria-rowindex is 1-based).
aria-rowspan [ARIA 1.1]
  • Expose the value of aria-rowspan in object attribute rowspan:<value>.
  • Expose via IAccessibleTableCell::rowExtent
  • Implement GridItem Control Pattern
  • Set RowSpan property
  • Expose the value of aria-rowspan in object attribute rowspan:<value>.
  • Expose via AccessibleTableCell interface method atk_table_cell_get_row_column_span()
 AXRowIndexRange:
location=<row index>
length=<rowspan value>, where location is 0-based.
aria-selected="true" (state) Expose STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

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

 Expose IsSelected property on SelectionItem Control Pattern.

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

 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) Clear STATE_SYSTEM_SELECTED

Expose STATE_SYSTEM_SELECTABLE

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

 Not mapped 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 mapped Not mapped Not mapped Not 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 object attribute setsize:<value> and groupPosition().

Expose as setsize=<value> in AriaProperties.

Expose object attribute setsize:<value>.

AXARIASetSize: <value>
aria-sort="ascending", "descending", or "other" Expose as object attribute sort:<value>

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

 Expose as object attribute sort:<value> AXSortDirection: AXAscendingSortDirection | AXDescendingSortDirection | AXUnknownSortDirection
aria-sort="none" (default) If specified, expose as object attribute sort:<value> Not mapped* If specified, expose as object attribute sort:<value> Not mapped*
aria-valuemax Expose via AccessibleValue interface.

See Widget values for additional information

 Expose the Maximum property in RangeValue Control Pattern

See Widget values for additional information

 Expose via Value interface

See Widget values for additional information

 number AXMaxValue

See Widget values for additional information
aria-valuemin Expose via AccessibleValue interface

See Widget values for additional information

 Expose the Minimum property in RangeValue Control Pattern

See Widget values for additional information

 Expose via Value interface

See Widget values for additional information

 number AXMinValue

See Widget values for additional information
aria-valuenow If aria-valuetext is not defined, expose via IAccessible::get_accValue

Expose via AccessibleValue interface.

See Widget values for additional information

 Expose Value property in RangeValue Control Pattern

See Widget values for additional information

 Expose via Value interface

See Widget values for additional information

 number AXValue

See Widget values for additional information
aria-valuetext Expose via IAccessible::get_accValue

Expose as object attribute valuetext:<value>

See Widget values for additional information

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

See Widget values for additional information

 Expose as object attribute valuetext:<value>

See Widget values for additional information

 AXValueDescription: <value>

See Widget values for additional information

Special Processing Requiring Additional Computation

Name and Description

When computing an accessible name or accessible description, user agents MUST conform to the section titled Text Alternative Computation of the Accessible Name and Description Computation and API Mappings specification.

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.

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.

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.

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 Relation IAccessible2 ATK/AT-SPI
aria-controls references the element's ID IA2_RELATION_CONTROLLED_BY RELATION_CONTROLLED_BY
aria-describedby references the element's ID IA2_RELATION_DESCRIPTION_FOR RELATION_DESCRIPTION_FOR
aria-details references the element's ID IA2_RELATION_DETAILS_FOR RELATION_DETAILS_FOR
aria-errormessage references the element's ID IA2_RELATION_ERROR_FOR RELATION_ERROR_FOR
aria-flowto references the element's ID IA2_RELATION_FLOW_FROM RELATION_FLOW-FROM
aria-labelledby references the element's ID IA2_RELATION_LABEL_FOR RELATION_LABEL_FOR
aria-owns references the element's ID IA2_RELATION_NODE_CHILD_OF/IA2_RELATION_NODE_PARENT_OF RELATION_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.

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

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-level is not provided or inherited for an element of role treeitem, user agents implementing IAccessible2 or ATK/AT-SPI MUST compute it by following the explicit or computed RELATION_NODE_CHILD_OF relations.

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

  • for role="treeitem", walk the tree backward and forward until the explicit or computed level becomes less than the current item's level. Count items only if they are at the same level as the current item.
  • Otherwise, if the role supports aria-posinset and aria-setsize, process the parent (DOM parent or parent defined by aria-owns), counting items that have the same role.
  • Because these value 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.

If the author provides one or more of aria-setsize and aria-posinset, it is the author's responsibility to supply them for all elements in the set. User agent correction of missing values in this case is not defined.

MSAA/IAccessible2 API mappings involve an additional function, groupPosition() [[IAccessible2]], 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.

Actions

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

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.

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.

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.

See the Name and Description Change Events section of the Accessible Name and Description Computation document regarding how different accessibility APIs expose changes to accessible name and accessible description properties.

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.

Translators: For label text associated with the following table and its toggle buttons, see the mappingTableLabels object in the <head> section of this document.

Table of events to be fired in each API for changes in WAI-ARIA states and properties
State or Property MSAA + IAccessible2 event UIA event ATK/AT-SPI event AX API Notification
aria-activedescendant See Controlling focus with aria-activedescendant

In addition:

IA2_EVENT_ACTIVE_DESCENDANT_CHANGED

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

In addition: AXSelectedChildrenChanged
aria-busy (state) EVENT_OBJECT_STATECHANGE PropertyChangedEvent object:state-changed:busy AXElementBusyChanged
aria-checked (state) EVENT_OBJECT_STATECHANGE ToggleStateProperty as part of toggle pattern object:state-changed:checked AXValueChanged
[ARIA 1.1] aria-current (state) IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED PropertyChangedEvent object:state-changed:active No notification
aria-disabled (state) EVENT_OBJECT_STATECHANGE No event object:state-changed:enabled and object:state-changed:sensitive No notification
aria-describedby See the Name and Description Change Events section in [[!ACCNAME-AAM]]. See the Name and Description Change Events section in [[!ACCNAME-AAM]]. See the Name and Description Change Events section in [[!ACCNAME-AAM]]. See the Name and Description Change Events section in [[!ACCNAME-AAM]].
aria-dropeffect (property) IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED No event object:property-change No notification
aria-expanded (state) EVENT_OBJECT_STATECHANGE expand/collapse pattern events object:state-changed:expanded AXRowExpanded,
AXRowCollapsed,
AXRowCountChanged
aria-grabbed (state)

EVENT_OBJECT_SELECTION

IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED

 No event object:property-change No notification
aria-hidden (state) IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED StructureChangedEvent object:property-change AXUIElementDestroyed,
AXUIElementCreated
aria-invalid (state) EVENT_OBJECT_STATECHANGE No event object:state-changed:invalid_entry AXInvalidStatusChanged
aria-label and aria-labelledby See the Name and Description Change Events section in [[!ACCNAME-AAM]]. See the Name and Description Change Events section in [[!ACCNAME-AAM]]. See the Name and Description Change Events section in [[!ACCNAME-AAM]]. See the Name and Description Change Events section in [[!ACCNAME-AAM]].
aria-pressed (state) EVENT_OBJECT_STATECHANGE No event object:state-changed:pressed No notification
aria-readonly EVENT_OBJECT_STATECHANGE No event object:state-changed:readonly No notification
aria-required EVENT_OBJECT_STATECHANGE No event object:state-changed:required No notification
aria-selected (state) See section Selection for details. See section Selection for details. See section Selection for details. See section Selection for details.
aria-valuenow EVENT_OBJECT_VALUECHANGE ValueProperty property change as part of value pattern object:property-change:accessible-value AXValueChanged
aria-valuetext EVENT_OBJECT_VALUECHANGE No event object:property-change:accessible-value AXValueChanged

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
Scenario MSAA + IAccessible2 event UIA event ATK/AT-SPI event AX API Notification
When text is removed IA2_EVENT_TEXT_REMOVED EVENT_OBJECT_LIVEREGIONCHANGED text_changed::delete If in a live region, AXLiveRegionChanged
When text is inserted IA2_EVENT_TEXT_INSERTED EVENT_OBJECT_LIVEREGIONCHANGED text_changed::insert If in a live region, AXLiveRegionChanged
When text is changed IA2_EVENT_TEXT_REMOVE and IA2_EVENT_TEXT_INSERTED EVENT_OBJECT_LIVEREGIONCHANGED text_changed::delete and text_changed::insert If 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
Scenario MSAA Microsoft UIA event ATK/AT-SPI event AX API Notification
When an accessibility subtree is hidden EVENT_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. 		AutomationElement..::.StructureChangedEvent children_changed::remove

AXUIElementDestroyed

If in a live region, AXLiveRegionChanged
When an accessibility subtree is removed EVENT_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. 		AutomationElement..::.StructureChangedEvent children_changed::remove

AXUIElementDestroyed

If in a live region, AXLiveRegionChanged
When an accessibility subtree is shown EVENT_OBJECT_SHOW   children_changed::add

AXUIElementCreated

If in a live region, AXLiveRegionChanged
When an accessibility subtree is inserted EVENT_OBJECT_REORDER   children_changed::add

AXUIElementCreated

If in a live region, AXLiveRegionChanged
When an accessibility subtree is moved Treat it as a removal from one place and insertion in another Treat it as a removal from one place and insertion in another Treat 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 insertion Treat it as a removal and insertion Treat 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 macOS, 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.

Selection

There are two cases for selection:

  • Single selection
  • Multiple selection

In the single selection case, selection follows focus (see the section "Focus States and Events Table" for information about focus events). User agents MUST fire the following events when aria-selected changes:

Single selection events
Scenario MSAA Microsoft UIA ATK/AT-SPI AX API
Focus change EVENT_OBJECT_SELECTION and EVENT_OBJECT_STATECHANGE on newly focused item. UIA_SelectionItem_ElementSelectedEventId on the newly focused element.

If on a gridcell, row, option, or tab, fire UIA_SelectionItem_ElementSelectedEventId.
  • object:selection-changed on the current container,
  • object:state-changed:selected on the descendant accessible object whose selection has changed:
    • detail1 = 1 for the descendant which just became selected.
    • detail1 = 0 for the descendant which just became unselected.
 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 changes on a descendant, as follows:

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

  1. In Microsoft UIA, the Selection and SelectionItem Control Patterns expose the selection availability, state, and methods.
  2. User agents MUST fire the following events when aria-selected changes on a descendant, as follows:
Multiple selection events
Scenario MSAA Microsoft UIA ATK/AT-SPI AX API
Toggle aria-selected EVENT_OBJECT_SELECTIONADD/EVENT_OBJECT_SELECTIONREMOVE on the item. SelectionItem Control Pattern:UIA_SelectionItem_ElementAddedToSelectionEventId or UIA_SelectionItem_ElementRemovedFromSelectionEventId on the current container.
  • object:selection-changed on the current container,
  • object:state-changed:selected on any descendant accessible object whose selection has changed:
    • detail1 = 1 for any descendant which just became selected.
    • detail1 = 0 for any descendant which just became unselected.
 AXSelectedChildrenChanged
Selection follows focus EVENT_OBJECT_SELECTION and EVENT_OBJECT_STATECHANGE on newly focused item. FocusChangedEvent should be fired but individual selection event may not happen, to avoid redundancy.
  • object:selection-changed on the current container,
  • object:state-changed:selected on any descendant accessible object whose selection has changed:
AXSelectedChildrenChanged
Select or deselect many items at once User agent MAY fire an EVENT_OBJECT_SELECTIONWITHIN. If this event is fired the other events noted above MAY be trimmed out for performance. For each element selected or deselected, fire SelectionItem Control Pattern: UIA_SelectionItem_ElementAddedToSelectionEventId or UIA_SelectionItem_ElementRemovedFromSelectionEventId on the current container. User agents MAY choose to fire the Selection Control Pattern Invalidated event, which indicates that the selection in a container has changed significantly and requires sending more addition and removal events than the InvalidateLimit constant permits.
  • the user agent MAY fire a single object:selection-changed event on the container, vs. multiple events, for performance,
  • object:state-changed:selected on any descendant accessible object whose selection has changed:
AXSelectedChildrenChanged

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
Scenario MSAA Microsoft UIA AX API

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. MenuModeStartEvent on the accessible object for the menu. AXMenuOpenedNotification

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

 EVENT_OBJECT_FOCUS AutomationFocusChangedEvent AXMenuItemSelectedNotification

Menu popup made visible (menu is opened).

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

 EVENT_SYSTEM_MENUPOPUPSTART MenuOpenedEvent, then a focus event on a menuitem. AXMenuOpenedNotification
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. MenuClosedEvent 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. MenuClosedEvent, then MenuModeEndEvent AXMenuClosedNotification

Special Document Handling Procedures

CSS Selectors

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.

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.
  6. Determining implicit values of aria-setsize and aria-posinset when they are specified on some but not all the elements of the set.

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

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

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

User agents MUST NOT expose WAI-ARIA attributes that reference unresolved IDs. For example:

User Agents MUST NOT expose aria-roledescription when:

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.

Default values for missing required attributes
WAI-ARIA role Required Attribute Default value
checkbox aria-checked See aria-checked="false" in State and Property mapping table.
menuitem aria-haspopup See aria-haspopup="false" in State and Property mapping table.
menuitemcheckbox aria-checked See aria-checked="false" in State and Property mapping table.
menuitemradio aria-checked See aria-checked="false" in State and Property mapping table.
radio aria-checked See aria-checked="false" in State and Property mapping table.
switch aria-checked See aria-checked="false" in State and Property mapping table.
combobox aria-expanded See aria-expanded="false" in State and Property mapping table.
combobox aria-haspopup See aria-haspopup="listbox" in State and Property mapping table.
heading aria-level 2
scrollbar aria-controls no mapping
scrollbar aria-orientation See aria-orientation="vertical" in State and Property mapping table.
scrollbar aria-valuemax 100
scrollbar aria-valuemin 0
scrollbar aria-valuenow (aria-valuemax - aria-valuemin) / 2
slider aria-valuemax 100
slider aria-valuemin 0
slider aria-valuenow (aria-valuemax - aria-valuemin) / 2
spinbutton aria-valuemax A value indicating that the spinbutton has no upper bound (Accessibility API dependent).
spinbutton aria-valuemin A value indicating that the spinbutton has no lower bound (Accessibility API dependent).
spinbutton aria-valuenow 0

Appendices

Change Log

Substantive changes since the last public working draft

  • 13-Apr-2017: Changed AX API AXSubrole for role="group" from "<nil>" to "AXApplicationGroup".
  • 28-Mar-2017: Changed MSAA/IA2 and ATK/AT-SPI object attribute for aria-current mapping from "active" to "current".
  • 20-Mar-2017: Modified AX API AXRoleDescription mappings of roles dialog and alertdialog to be "web dialog" and "web alert dialog", respectively.
  • 14-Mar-2017: Undid the 1.1 addition of RELATION_POPUP_FOR to ATK/AT-SPI mappings of aria-haspopup. While the addition is correct in terms of platform expectations, the ARIA spec provides no means through which user agents could reliably implement this.
  • 20-Jan-2017: Added AX API mappings for aria-colcount, aria-colspan, aria-colindex, aria-rowcount, aria-rowindex, and aria-rowspan.
  • 07-Dec-2016: Added UIA mappings for roles feed, figure, and term, and for aria-colcount, aria-colspan, aria-colindex, aria-rowcount, aria-rowindex, aria-rowspan, and aria-details. Added UIA Range Value Pattern for range related roles scrollbar, slider, and spinbutton.
  • 24-Oct-2016: Changed name of IA2 object property name for aria-placeholder to "placeholder-text" (was "placeholder").
  • 04-Oct-2016: Add reverse relationships for aria-details and aria-errormessage on platforms MSAA/IA2 and ATK/ATSPI
  • 03-Oct-2016: Added aria-roledescription mappings for empty and whitespace strings as well as error handling text.
  • 12-Sep-2016: Added RELATION_POPUP_FOR to ATK/AT-SPI mappings of aria-haspopup, for ARIA 1.1. N.B. This change has subsequently been undone. See entry for 14-Mar-2017.
  • 08-Sep-2016: Added figure role, term role, feed role, aria-colspan, and aria-rowspan mappings. Updated table properties for row and column for MSAA/IA2 and ATK/AT-SPI. Added MSAA+IA2 and ATK/AT-SPI mappings of aria-details and aria-errormessage.
  • 08-Aug-2016: Modified ATK/AT-SPI mappings of aria-readonly.
  • 04-Jul-2016: Added AX API mapping for aria-keyshortcuts.
  • 27-Jun-2016: For MSAA+IA2, UIA, and ATK/AT-SPI, modified mappings of role="separator" when it is a window splitter.
  • 27-Jun-2016: Added ATK/AT-SPI mapping for aria-keyshortcuts.
  • 08-Jun-2016: Removed role text.
  • 06-Jun-2016: Added MSAA+IA2, UIA, and ATK/AT-SPI mappings for the new values of aria-haspopup added for ARIA 1.1.
  • 03-Jun-2016: Added MSAA+IA2 mapping of aria-keyshortcuts.
  • 20-May-2016: Added UIA mapping of aria-keyshortcuts.
  • 05-May-2016: Updated AX API mapping of role region to reflect its inheritance from the landmark role.
  • 02-May-2016: Modified MSAA+IA2 and ATK/AT-SPI mappings of 'form' role to use IA2_ROLE_LANDMARK and ROLE_LANDMARK, respectively, plus the xml-roles object attribute set to 'form'.
  • 11-Apr-2016: Added AX API mappings for aria-modal="true" and aria-modal="false".
  • 11-Apr-2016: For role="application", replaced AX API subrole AXLandmarkAppliction with AXWebAppliction, and role description 'application' with 'web application'.
  • 04-Apr-2016: Added new UIA FullDescription property for mapping aria-describedby.
  • 06-May-2016: Added changes for revised values for aria-haspopup for ATK/AT-SPI and MSAA+IA2 along with error handling

Other substantive changes since the WAI-ARIA 1.0 User Agent Implementation Guide Recommendation

  • 11-Mar-2016: Added details to UIA mappings of radio and menuitemradio roles reqarding how aria-checked values are exposed in the Toggle and SelectionItem patterns; removed aria-describedat from states and properties mapping table.
  • 10-Mar-2016: Updated default values for aria-valuemin, aria-valuemax, and aria-valuenow for spinbutton role. Default for aria-valuenow is 0 (zero), default for aria-valuemin is no lower bound, and for aria-valuemax, no upper bound.
  • 07-Mar-2016: Updated all UIA mappings for landmark roles to include Landmark Type and Localized Landmark Type.
  • 22-Feb-2016: IA2 mapping of role="text" changed to ROLE_SYSTEM_STATICTEXT from IA2_TEXT_FRAME.
  • 02-Feb-2016: Modified UIA mapping of main role to include a Landmark Type and a Localized Landmark Type. Added UIA mapping for aria-errormessage.
  • 25-Jan-2016: Added AX API mappings for aria-current.
  • 15-Jan-2016: Added UIA mappings for aria-current.
  • 11-Jan-2016: Modified UIA mapping for roles article and application. Finalized IA2 mapping of aria-current.
  • 03-Jan-2016: Added UIA mappings for aria-colindex and aria-rowindex. Added placeholders for the other AAPIs.
  • 27-Nov-2015: Added UIA mapping of role="text" as a Text control pattern; and ATK/AT-SPI mapping as ROLE_STATIC.
  • 03-Oct-2015: Modified UIA role mappings of application, banner, complementary, contentinfo, main, search, navigation, article, definition, log, math, and note.
  • 28-Sep-2015: Added IA2 mapping of role="text".
  • 28-Sep-2015: Removed all MSAA+UIA Express mappings.
  • 24-Aug-2015: Modified mappings of region role in light of its new status as a landmark.
  • 18-Aug-2015: Added mappings of aria-roledescription for MSAA+IA2, UIA, ATK/AT-SPI and AX API.
  • 31-Jul-2015: Finalized all mappings of aria-placeholder.
  • 02-Jul-2015: Modified default values for missing required attributes table for aria-level with heading role, aria-checked with switch, and aria-valuemin, aria-valuemax, and aria-valuenow with scrollbar, slider, and spinbutton.
  • 02-Jul-2015: Added special case of switch role to mappings of aria-checked="mixed" and undefined aria-checked.
  • 25-Jun-2015: ATK/AT-SPI mapping for aria-current.
  • 16-Jun-2015: Modified MSAA+UIA Express and ATK/AT-SPI mappings of rowgroup role.
  • 15-Jun-2015: Modified MSAA+IA2 mappings of presentation / none roles for required owned descendants.
  • 02-Jun-2015: Modified ATK/AT-SPI and UIA mappings of presentation / none roles for required owned descendants.
  • 02-Jun-2015: MSAA+UIA Express and UIA mappings for aria-placeholder.
  • 28-Apr-2015: ATK/AT-SPI mappings for aria-placeholder.
  • 31-Mar-2015: AX API mappings for aria-owns.
  • 11-Mar-2015: Mappings for searchbox.
  • 04-Mar-2015: Additional mappings for switch.
  • 23-Feb-2015: Mappings for presentation / none.
  • 23-Feb-2015: Mappings for switch.
  • 14-Jan-2015: Mappings for rowgroup.
  • 19-Dec-2015: Modify mappings to convey grid role beyond table.
  • 27-Nov-2014: Added mappings for role text and aria-modal property.
  • 14-Nov-2014: Fixed mappings of aria-invalid=<unknown value>.
  • 11-Nov-2014: Added informative section on relationship between ATK and AT-SPI.
  • 03-Nov-2014: Specified UIA mappings of aria-level when used in conjunction with role heading.
  • 27-Oct-2014: Moved text alternative computation section to its own document.
  • 29-Aug-2014: Modified mappings of grid role to differentiate a grid from a table.
  • 05-Jun-2014: Modified ATK/AT-SPI mappings for article, checkbox, menuitemcheckbox, menuitemradio, and aria-checked.
  • 30-May-2014: Modified ATK/AT-SPI mappings for focus event, banner, listbox, log, marquee, math, navigation, note, radiogroup, row, timer, and treeitem.
  • 21-May-2014: Added additional AX API mapping for aria-busy.
  • 15-May-2014: Provided IA2 and ATK/AT-SPI mappings of aria-pressed and tablist.
  • 15-May-2014: Change AX API mapping for aria-busy.
  • 25-March-2014: Added text to Group Position section about computing implicit level information for a tree.
  • 24-March-2014: Updated mapping of aria-hidden=true to indicate that user agents should not expose unless the accessible object is focused or fires an accessibility event.
  • 21-March-2014: Added back UIA columns to all mapping tables that were removed after the 1.0 Candidate Recommendation.