Core Accessibility API Mappings 1.2

W3C Working Draft

This version:
https://www.w3.org/TR/2018/WD-core-aam-1.2-20181218/
Latest published version:
https://www.w3.org/TR/core-aam-1.2/
Latest editor's draft:
https://w3c.github.io/core-aam/
Previous version:
https://www.w3.org/TR/2018/WD-core-aam-1.2-20180719/
Latest Recommendation:
https://www.w3.org/TR/core-aam-1.1/
Editors:
Joanmarie Diggs (Igalia, S.L.)
Michael Cooper (W3C)
Former editors:
Richard Schwerdtfeger (Knowbility) (Editor until October 2017)
Joseph Scheuhammer (Inclusive Design Research Centre, OCAD University) (Editor until May 2017)
Andi Snow-Weaver (IBM) (Editor until December 2012)
Aaron Leventhal (IBM) (Editor until January 2009)
Authors:
Melanie Richards (Microsoft Corp.) (UIA)
James Craig (Apple, Inc.) (AX API)
Joanmarie Diggs (Igalia, S.L.) (ATK / AT-SPI)
Alexander Surkov (Mozilla Foundation) (MSAA, IAccessible2)

Copyright © 2014-2018 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.

Abstract

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-1.2]. 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 supersede the guidance in the Core Accessibility API Mappings 1.1 [CORE-AAM-1.1] W3C Recommendation. It is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

Status of This Document

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

This is a Working Draft of Core Accessibility API Mappings (Core-AAM) 1.2 by the Accessible Rich Internet Applications (ARIA) Working Group. Succeeding Core-AAM 1.1 [CORE-AAM-1.1], it provides new mappings for WAI-ARIA 1.2 [WAI-ARIA-1.2]. The primary focus of WAI-ARIA 1.2 is to add roles that correspond to HTML 5 [HTML5] semantics. This version adds mappings for new ARIA roles and updates some existing mappings. A history of changes to Core-AAM 1.2 is available.

The Accessible Rich Internet Applications Working Group seeks feedback on any aspect of the specification. When submitting feedback, please consider issues in the context of the companion documents. To comment, file an issue in the W3C core-aam GitHub repository. If this is not feasible, send email to public-aria@w3.org (comment archive). In-progress updates to the document may be viewed in the publicly visible editors' draft.

This document was published by the Accessible Rich Internet Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

Comments regarding this document are welcome. Please send them to public-aria@w3.org (archives).

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

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

This document is governed by the 1 February 2018 W3C Process Document.

1. Introduction

This section is non-normative.

The Core Accessibility API Mappings specifies how WAI-ARIA roles, states, and properties are expected to be exposed by user agents via platform accessibility APIs. It is part of a set of resources that define and support the WAI-ARIA specification which includes the following documents:

For an introduction to WAI-ARIA, see the WAI-ARIA Overview.

1.1 Accessibility APIs

Accessibility APIs make it possible to communicate accessibility information about user interfaces to assistive technologies. This information includes:

  1. Descriptive properties (role, name, value, position, etc.)
  2. Transient states (pressed, focused, 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, description/described object, previous object/next object, etc.)
  6. Textual content

Accessibility APIs covered by this specification 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.

1.2 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 distinguishing characteristics of some of the APIs.

1.2.1 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, combobox, 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, whereas AT-SPI is relevant to consumers. In the context of mapping WAI-ARIA roles, states and properties, user agents are implementors and use ATK. Assistive Technologies are consumers, and use AT-SPI.

1.2.2 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 are 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 clients to interact with controls using common programmatic interfaces.
  • Events - Similar to other accessibility APIs, automation elements support various events that allow automation providers to 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 mappings 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.

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

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, OPTIONAL, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

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

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

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

3. Important Terms

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

Accessibility API

Operating systems and other platforms provide a set of interfaces that expose information about objects and events to assistive technologies. Assistive technologies use these interfaces to get information about and interact with those widgets. Examples of accessibility APIs are Microsoft Active Accessibility [MSAA], Microsoft User Interface Automation [UI-AUTOMATION], MSAA with UIA Express [UIA-EXPRESS], the Mac OS X Accessibility Protocol [AXAPI], the Linux/Unix Accessibility Toolkit [ATK] and Assistive Technology Service Provider Interface [AT-SPI], and IAccessible2 [IAccessible2].

Accessibility Subtree

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

Accessibility Tree

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

Accessible Description

An accessible description provides additional information, related to an interface element, that complements the accessible name. The accessible description might or might not be visually perceivable.

Accessible Name

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

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

Accessible object

A node in the accessibility tree of a platform accessibility API. Accessible objects expose various states, properties, and events for use by assistive technologies. In the context of markup languages (e.g., HTML and SVG) in general, and of WAI-ARIA in particular, markup elements and their attributes are represented as accessible objects.

Assistive Technologies

Hardware and/or software that:

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

This definition may differ from that used in other documents.

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

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

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

Class

A set of instance objects that share similar characteristics.

Element

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

Event

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

Hidden

Indicates that the element is not visible, perceivable, or interactive to any user. An element is considered hidden if it or any one of its ancestor elements is not rendered or is explicitly hidden.

Informative

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

Live Region

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

Managed State

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

Node

Basic type of object in the DOM tree or accessibility tree. DOM nodes are further specified as Element or Text nodes, among other types. The nodes of an accessibility tree are accessible objects.

Normative

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

Object

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

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

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

Perceivable

Presentable to users in ways they can sense. References in this document relate to WCAG 2.1 Principle 1: Content must be perceivable [WCAG21].

Property

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

Relationship

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

Role

Main indicator of type. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.

Semantics

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

State

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

Text node

Type of DOM node that represents the textual content of an attribute or an element. A Text node has no child nodes.

User Agent

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

Widget

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

4. Mapping WAI-ARIA to Accessibility APIs

4.1 General rules for exposing WAI-ARIA semantics

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

With respect to WAI-ARIA 1.0 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.

4.2 Conflicts between native markup semantics and WAI-ARIA

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

Host languages can have features that have implicit WAI-ARIA semantics corresponding to roles. When a WAI-ARIA role is provided that has a corresponding role in the accessibility API, user agents MUST use the semantic of the WAI-ARIA role for processing, not the native semantic, unless the role requires WAI-ARIA states and properties whose attributes are explicitly forbidden on the native element by the host language. Values for roles do not conflict in the same way as values for states and properties, and because authors are expected to have a valid reason to provide a WAI-ARIA role even on elements that would not normally be repurposed. For example, spin buttons are typically constructed from text fields (<input type="text">) in order to get most of the default keyboard support. But, the native role, "text field", 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 subclass of those semantics, then treat any required owned elements of the native role as having role presentation or none.

Note

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

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

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

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

Platform accessibility APIs might have features that are not in WAI-ARIA. Likewise, WAI-ARIA exposes capabilities that are not supported by accessibility APIs at the time of publication. There typically is not a one to one relationship between all WAI-ARIA attributes and platform accessibility APIs. When WAI-ARIA roles, states and properties do not directly map to an accessibility API, and there is a mechanism in the API to expose the WAI-ARIA role, states, and properties and their values, user agents MUST expose the WAI-ARIA data using that mechanism as follows:

Note

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

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

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

4.4 Role mapping

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

4.4.1 General rules

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

4.4.2 Role Mapping Table

Note

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 UIA ATK/AT-SPI AX API[Note 1]
alert Role: ROLE_SYSTEM_ALERT
Event: The user agent SHOULD fire EVENT_SYSTEM_ALERT. [Note 2] 		Control Type: Group
Localized Control Type: alert
LiveSetting: Assertive (2)
Event: The user agent SHOULD fire a system alert event. [Note 2] 		Role: ROLE_ALERT
Event: The user agent SHOULD fire a system alert event. [Note 2] 		AXRole: AXGroup
AXSubrole: AXApplicationAlert
AXRoleDescription: 'alert'
Event: The user agent SHOULD fire a system alert event. [Note 2]
alertdialog Role: ROLE_SYSTEM_DIALOG
Event: The user agent SHOULD fire EVENT_SYSTEM_ALERT. [Note 2] 		Control Type: Pane
Event: The user agent SHOULD fire a system alert event. [Note 2] 		Role: ROLE_DIALOG
Interface: Window
Event: The user agent SHOULD fire a system alert event. [Note 2] 		AXRole: AXGroup
AXSubrole: AXApplicationAlertDialog
AXRoleDescription: 'web alert dialog'
Event: The user agent SHOULD fire a system alert event. [Note 2]
application Role: ROLE_SYSTEM_APPLICATION Control Type: Pane
Localized Control Type: application 		Role: ROLE_EMBEDDED AXRole: AXGroup
AXSubrole: AXWebApplication
AXRoleDescription: 'web application'
article Role: ROLE_SYSTEM_DOCUMENT
State: STATE_SYSTEM_READONLY
Object Attribute: xml-roles:article 		Control Type: Group
Localized Control Type: article 		Role: ROLE_ARTICLE
Object Attribute: xml-roles:article 		AXRole: AXGroup
AXSubrole: AXDocumentArticle
AXRoleDescription: 'article'
banner Role: IA2_ROLE_LANDMARK
Object Attribute: xml-roles:banner 		Control Type: Group
Localized Control Type: banner
Landmark Type: Custom
Localized Landmark Type: banner 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:banner 		AXRole: AXGroup
AXSubrole: AXLandmarkBanner
AXRoleDescription: 'banner'
blockquote Role: ROLE_SYSTEM_GROUPING
Role: IA2_ROLE_SECTION 		Control Type: Group
Localized Control Type: blockquote 		Role: ROLE_BLOCK_QUOTE
 AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
button with default values for aria-pressed and aria-haspopup Role: ROLE_SYSTEM_PUSHBUTTON Control Type: Button Role: ROLE_PUSH_BUTTON AXRole: AXButton
AXSubrole: <nil>
AXRoleDescription: 'button'
button with non-false value for aria-haspopup Role: ROLE_SYSTEM_BUTTONMENU Control Type: Button Role: ROLE_PUSH_BUTTON AXRole: AXPopUpButton
AXSubrole: <nil>
AXRoleDescription: 'pop up button'
button with defined value for aria-pressed Role: ROLE_SYSTEM_PUSHBUTTON
Role: IA2_ROLE_TOGGLE_BUTTON 		Control Type: Button Role: ROLE_TOGGLE_BUTTON AXRole: AXCheckBox
AXSubrole: AXToggle
AXRoleDescription: 'toggle button'
caption Role: ROLE_SYSTEM_TEXT
Role: IA2_ROLE_CAPTION 		Control Type: Text Role: ROLE_CAPTION AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
cell Role: ROLE_SYSTEM_CELL
Interface: IAccessibleTableCell 		Control Type: DataItem
Localized Control Type: cell
Control Pattern: TableItem 		Role: ROLE_TABLE_CELL
Interface: TableCell 		AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'
checkbox Role: ROLE_SYSTEM_CHECKBUTTON
See also: aria-checked in the State and Property Mapping Table 		Control Type: Checkbox
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_CHECK_BOX
See also: aria-checked in the State and Property Mapping Table 		AXRole: AXCheckBox
AXSubrole: <nil>
AXRoleDescription: 'checkbox'
See also: aria-checked in the State and Property Mapping Table
columnheader Role: ROLE_SYSTEM_COLUMNHEADER
Interface: IAccessibleTableCell 		Control Type: HeaderItem Role: ROLE_COLUMN_HEADER
Interface: TableCell 		AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'
combobox Role: ROLE_SYSTEM_COMBOBOX
State: STATE_SYSTEM_HASPOPUP
State: STATE_SYSTEM_COLLAPSED if aria-expanded is not "true" 		Control Type: Combobox Role: ROLE_COMBO_BOX
State: STATE_EXPANDABLE
State: STATE_HAS_POPUP 		AXRole: AXComboBox
AXSubrole: <nil>
AXRoleDescription: 'combo box'
complementary Role: IA2_ROLE_LANDMARK
Object Attribute: xml-roles:complementary 		Control Type: Group
Localized Control Type: complementary
Landmark Type: Custom
Localized Landmark Type: complementary 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:complementary 		AXRole: AXGroup
AXSubrole: AXLandmarkComplementary
AXRoleDescription: 'complementary'
contentinfo Role: IA2_ROLE_LANDMARK
Object Attribute: xml-roles:contentinfo 		Control Type: Group
Localized Control Type: content information
Landmark Type: Custom
Localized Landmark Type: content information 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:contentinfo 		AXRole: AXGroup
AXSubrole: AXLandmarkContentInfo
AXRoleDescription: 'content information'
definition Object Attribute: xml-roles:definition Control Type: Group
Localized Control Type: definition 		Role: ROLE_DESCRIPTION_VALUE
Object Attribute: xml-roles:definition 		AXRole: AXGroup
AXSubrole: AXDefinition
AXRoleDescription: 'definition'
dialog Role: ROLE_SYSTEM_DIALOG Control Type: Pane Role: ROLE_DIALOG
Interface: Window 		AXRole: AXGroup
AXSubrole: AXApplicationDialog
AXRoleDescription: 'web dialog'
directory Role: ROLE_SYSTEM_LIST Control Type: List Role: ROLE_LIST AXRole: AXList
AXSubrole: AXContentList
AXRoleDescription: 'content list'
document Role: ROLE_SYSTEM_DOCUMENT
State: STATE_SYSTEM_READONLY 		Control Type: Document Role: ROLE_DOCUMENT_FRAME AXRole: AXGroup
AXSubrole: AXDocument
AXRoleDescription: 'document'
feed Role: ROLE_SYSTEM_GROUPING
Object Attribute: xml-roles:feed 		Control Type: Group
Localized Control Type: feed 		Role: ROLE_PANEL
Object Attribute: xml-roles:feed 		AXRole: AXGroup
AXSubrole: AXApplicationGroup
AXRoleDescription: 'feed'
figure Role: ROLE_SYSTEM_GROUPING
Object Attribute: xml-roles:figure 		Control Type: Group
Localized Control Type: figure 		Role: ROLE_PANEL
Object Attribute: xml-roles:figure 		AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'figure'
form Role: IA2_ROLE_FORM
Object Attribute: xml-roles:form 		Control Type: Group
Localized Control Type: form
Landmark Type: Form 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:form 		AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
grid Role: ROLE_SYSTEM_TABLE
Object Attribute: xml-roles:grid
Interface: IAccessibleTable2
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: DataGrid
Control Pattern: Selection 		Role: ROLE_TABLE
Object Attribute: xml-roles:grid
Interface: Table
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: AXTable
AXSubrole: <nil>
AXRoleDescription: 'table'
AXColumnHeaderUIElements: a list of pointers to the columnheader elements
AXHeader: a pointer to the row or group containing those columnheader elements
AXRowHeaderUIElements: a list of pointers to the rowheader elements
gridcell Role: ROLE_SYSTEM_CELL
Interface: IAccessibleTableCell 		Control Type: DataItem
Localized Control Type: gridcell
Control Pattern: SelectionItem
SelectionItem.SelectionContainer: the containing grid 		Role: ROLE_TABLE_CELL
Interface: TableCell 		AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'
group Role: ROLE_SYSTEM_GROUPING Control Type: Group Role: ROLE_PANEL AXRole: AXGroup
AXSubrole: AXApplicationGroup
AXRoleDescription: 'group'
heading Role: IA2_ROLE_HEADING
Object Attribute: xml-roles:heading 		Control Type: Text
Localized Control Type: heading 		Role: ROLE_HEADING AXRole: AXHeading
AXSubrole: <nil>
AXRoleDescription: 'heading'
img Role: ROLE_SYSTEM_GRAPHIC
Interface: IAccessibleImage 		Control Type: Image Role: ROLE_IMAGE
Interface: Image 		AXRole: AXImage
AXSubrole: <nil>
AXRoleDescription: 'image'
list Role: ROLE_SYSTEM_LIST
State: STATE_SYSTEM_READONLY 		Control Type: List Role: ROLE_LIST AXRole: AXList
AXSubrole: AXContentList
AXRoleDescription: 'content list'
listbox not owned by or child of combobox Role: ROLE_SYSTEM_LIST
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: List
Control Pattern: Selection 		Role: ROLE_LIST_BOX
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: AXList
AXSubrole: <nil>
AXRoleDescription: 'list'
listbox owned by or child of combobox Role: ROLE_SYSTEM_LIST
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: List
Control Pattern: Selection 		Role: ROLE_MENU
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: AXList
AXSubrole: <nil>
AXRoleDescription: 'list'
listitem Role: ROLE_SYSTEM_LISTITEM
State: STATE_SYSTEM_READONLY 		Control Type: ListItem
Control Pattern: SelectionItem
SelectionItem.SelectionContainer: the containing list 		Role: ROLE_LIST_ITEM AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
log Object Attribute: xml-roles:log
Object Attribute: container-live:polite
Object Attribute: live:polite
Object Attribute: container-live-role:log 		Control Type: Group
Localized Control Type: log
LiveSetting: Polite (1) 		Role: ROLE_LOG
Object Attribute: xml-roles:log
Object Attribute: container-live:polite
Object Attribute: live:polite
Object Attribute: container-live-role:log 		AXRole: AXGroup
AXSubrole: AXApplicationLog
AXRoleDescription: 'log'
main Role: IA2_ROLE_LANDMARK
Object Attribute: xml-roles:main 		Control Type: Group
Localized Control Type: main
Landmark Type: Main 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:main 		AXRole: AXGroup
AXSubrole: AXLandmarkMain
AXRoleDescription: 'main'
marquee Role: ROLE_SYSTEM_ANIMATION
Object Attribute: xml-roles:marquee
Object Attribute: container-live:off
Object Attribute: live:off 		Control Type: Group
Localized Control Type: marquee
LiveSetting: Off (0) 		Role: ROLE_MARQUEE
Object Attribute: container-live:off
Object Attribute: live:off 		AXRole: AXGroup
AXSubrole: AXApplicationMarquee
AXRoleDescription: 'marquee'
math Role: ROLE_SYSTEM_EQUATION Control Type: Group
Localized Control Type: math 		Role: ROLE_MATH AXRole: AXGroup
AXSubrole: AXDocumentMath
AXRoleDescription: 'math'
menu Role: ROLE_SYSTEM_MENUPOPUP
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: Menu Role: ROLE_MENU
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: AXMenu
AXSubrole: <nil>
AXRoleDescription: 'menu'
menubar Role: ROLE_SYSTEM_MENUBAR
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: MenuBar Role: ROLE_MENU_BAR
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 not owned by or child of group Role: ROLE_SYSTEM_MENUITEM Control Type: MenuItem Role: ROLE_MENU_ITEM AXRole: AXMenuItem
AXSubrole: <nil>
AXRoleDescription: 'menu item'
menuitem owned by or child of group Role: ROLE_SYSTEM_MENUITEM Control Type: MenuItem Role: ROLE_MENU_ITEM AXRole: AXMenuButton
AXSubrole: <nil>
AXRoleDescription: 'menu button'
menuitemcheckbox Role: ROLE_SYSTEM_CHECKBUTTON or ROLE_SYSTEM_MENUITEM
Role: IA2_ROLE_CHECK_MENU_ITEM
See also: aria-checked in the State and Property Mapping Table 		Control Type: MenuItem
Control Pattern: Toggle
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_CHECK_MENU_ITEM
See also: aria-checked in the State and Property Mapping Table 		AXRole: AXMenuItem
AXSubrole: <nil>
AXRoleDescription: 'menu item'
See also: aria-checked in the State and Property Mapping Table
menuitemradio Role: ROLE_SYSTEM_RADIOBUTTON or ROLE_SYSTEM_MENUITEM
Role: IA2_ROLE_RADIO_MENU_ITEM
See also: aria-checked in the State and Property Mapping Table 		Control Type: MenuItem
Control Pattern: Toggle
Control Pattern: SelectionItem
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_RADIO_MENU_ITEM
See also: aria-checked in the State and Property Mapping Table 		AXRole: AXMenuItem
AXSubrole: <nil>
AXRoleDescription: 'menu item'
See also: aria-checked in the State and Property Mapping Table
navigation Role: IA2_ROLE_LANDMARK
Object Attribute: xml-roles:navigation 		Control Type: Group
Localized Control Type: navigation
Landmark Type: Navigation 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:navigation 		AXRole: AXGroup
AXSubrole: AXLandmarkNavigation
AXRoleDescription: 'navigation'
none

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_TEXT_FRAME. User agents SHOULD prune empty descendants from the accessibility tree.

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.

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.

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 Role: IA2_ROLE_NOTE Control Type: Group
Localized Control Type: note 		Role: ROLE_COMMENT AXRole: AXGroup
AXSubrole: AXDocumentNote
AXRoleDescription: 'note'
option not inside combobox Role: ROLE_SYSTEM_LISTITEM
See also: aria-checked in the State and Property Mapping Table 		Control Type: ListItem
Control Pattern: Invoke
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_LIST_ITEM
See also: aria-checked in the State and Property Mapping Table
 		AXRole: AXStaticText
AXSubrole: <nil>
AXRoleDescription: 'text'
See also: aria-checked in the State and Property Mapping Table
option inside combobox Role: ROLE_SYSTEM_LISTITEM
See also: aria-checked in the State and Property Mapping Table 		Control Type: ListItem
Control Pattern: Invoke
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_MENU_ITEM
See also: aria-checked in the State and Property Mapping Table
 		AXRole: AXStaticText
AXSubrole: <nil>
AXRoleDescription: 'text'
See also: aria-checked in the State and Property Mapping Table
paragraph Role: ROLE_SYSTEM_TEXT
Role: IA2_ROLE_PARAGRAPH 		Control Type: Text Role: ROLE_PARAGRAPH AXRole: AXGroup
AXSubrole: <nil>
AXRoleDescription: 'group'
presentation

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_TEXT_FRAME. User agents SHOULD prune empty descendants from the accessibility tree.

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.

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.

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: ROLE_SYSTEM_PROGRESSBAR
State: STATE_SYSTEM_READONLY
Interface: IAcesssibleValue 		Control Type: ProgressBar
Control Pattern: RangeValue if aria-valuenow, aria-valuemax, or aria-valuemin is present 		Role: ROLE_PROGRESS_BAR
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: ROLE_SYSTEM_RADIOBUTTON
See also: aria-checked in the State and Property Mapping Table 		Control Type: RadioButton
Control Pattern: Toggle
Control Pattern: SelectionItem
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_RADIO_BUTTON
See also: aria-checked in the State and Property Mapping Table 		AXRole: AXRadioButton
AXSubrole: <nil>
AXRoleDescription: 'radio button'
See also: aria-checked in the State and Property Mapping Table
radiogroup Role: ROLE_SYSTEM_GROUPING Control Type: List Role: ROLE_PANEL AXRole: AXRadioGroup
AXSubrole: <nil>
AXRoleDescription: 'radio group'
region with an accessible name Role: IA2_ROLE_LANDMARK
Object Attribute: xml-roles:region 		Control Type: Group
Localized Control Type: region
Landmark Type: Custom
Localized Landmark Type: region 		Role: ROLE_LANDMARK
Object Attribute: xml-roles:region 		AXRole: AXGroup
AXSubrole: AXLandmarkRegion
AXRoleDescription: 'region'
region without an accessible name Do not expose the element as a landmark. Use the native host language role of the element instead. Do not expose the element as a landmark. Use the native host language role of the element instead. Do not expose the element as a landmark. Use the native host language role of the element instead. Do not expose the element as a landmark. Use the native host language role of the element instead.
row not inside treegrid Role: ROLE_SYSTEM_ROW Control Type: DataItem
Localized Control Type: row
Control Pattern: SelectionItem 		Role: ROLE_TABLE_ROW AXRole: AXRow
AXSubrole: <nil>
AXRoleDescription: 'row'
row inside treegrid Role: ROLE_SYSTEM_OUTLINEITEM Control Type: DataItem
Localized Control Type: row
Control Pattern: SelectionItem 		Role: ROLE_TABLE_ROW AXRole: AXRow
AXSubrole: <nil>
AXRoleDescription: 'row'
rowgroup Role: ROLE_SYSTEM_GROUPING Control Type: Group Role: ROLE_PANEL Not mapped
rowheader Role: ROLE_SYSTEM_ROWHEADER
Interface: IAccessibleTableCell 		Control Type: HeaderItem Role: ROLE_ROW_HEADER
Interface: TableCell 		AXRole: AXCell
AXSubrole: <nil>
AXRoleDescription: 'cell'
scrollbar Role: ROLE_SYSTEM_SCROLLBAR
Interface: IAcesssibleValue 		Control Type: ScrollBar
Control Pattern: RangeValue 		Role: ROLE_SCROLL_BAR
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 (non-focusable) Role: ROLE_SYSTEM_SEPARATOR Control Type: Separator Role: ROLE_SEPARATOR AXRole: AXSplitter
AXSubrole: <nil>
AXRoleDescription: 'splitter'
separator (focusable) Role: ROLE_SYSTEM_SEPARATOR
Interface: IAccessibleValue 		Control Type: Thumb
Control Pattern: RangeValue 		Role: ROLE_SEPARATOR
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: AXSplitter
AXSubrole: <nil>
AXRoleDescription: 'splitter'
slider Role: ROLE_SYSTEM_SLIDER
Interface: IAcesssibleValue 		Control Type: Slider
Control Pattern: RangeValue 		Role: 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: ROLE_SYSTEM_SPINBUTTON
Interface: IAcesssibleValue 		Control Type: Spinner
Control Pattern: RangeValue 		Role: 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: ROLE_SYSTEM_STATUSBAR
Object Attribute: container-live:polite
Object Attribute: live:polite
Object Attribute: container-live-role:status 		Control Type: Group
Localized Control Type: status
LiveSetting: Polite (1) 		Role: ROLE_STATUSBAR
Object Attribute: container-live:polite
Object Attribute: live:polite
Object Attribute: container-live-role:status 		AXRole: AXGroup
AXSubrole: AXApplicationStatus
AXRoleDescription: 'application status'
switch Role: ROLE_SYSTEM_CHECKBUTTON
Role: IA2_ROLE_TOGGLE_BUTTON
Object Attribute: xml-roles:switch
See also: aria-checked in the State and Property Mapping Table 		Control Type: Button
Localized Control Type: toggleswitch
Control Pattern: Toggle
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_TOGGLE_BUTTON
Object Attribute: xml-roles:switch
See also: aria-checked in the State and Property Mapping Table 		AXRole: AXCheckBox
AXSubrole: AXSwitch
AXRoleDescription: 'switch'
See also: aria-checked in the State and Property Mapping Table
tab Role: ROLE_SYSTEM_PAGETAB
State: STATE_SYSTEM_SELECTED if focus is inside tabpanel associated with aria-labelledby 		Control Type: TabItem Role: ROLE_PAGE_TAB
State: STATE_SELECTED if focus is inside tabpanel associated with aria-labelledby 		AXRole: AXRadioButton
AXSubrole: <nil>
AXRoleDescription: 'tab'
table Role: ROLE_SYSTEM_TABLE
Object Attribute: xml-roles:table
Interface: IAccessibleTable2 		Control Type: Table
Control Pattern: Grid
Control Pattern: Table 		Role: ROLE_TABLE
Object Attribute: xml-roles:table
Interface: Table 		AXRole: AXTable
AXSubrole: <nil>
AXRoleDescription: 'table'
AXColumnHeaderUIElements: a list of pointers to the columnheader elements
AXHeader: a pointer to the row or group containing those columnheader elements
AXRowHeaderUIElements: a list of pointers to the rowheader elements
tablist Role: ROLE_SYSTEM_PAGETABLIST
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: Tab
Control Pattern: Selection 		Role: ROLE_PAGE_TAB_LIST
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: ROLE_SYSTEM_PANE or ROLE_SYSTEM_PROPERTYPAGE Control Type: Pane Role: ROLE_SCROLL_PANE AXRole: AXGroup
AXSubrole: AXTabPanel
AXRoleDescription: 'tab panel'
term Role: IA2_ROLE_TEXT_FRAME
Object Attribute: xml-roles:term 		Control Type: Text
Localized Control Type: term 		Role: ROLE_DESCRIPTION_TERM AXRole: AXGroup
AXSubrole: AXTerm
AXRoleDescription: 'term'
textbox when aria-multiline is false Role: ROLE_SYSTEM_TEXT
State: IA2_STATE_SINGLE_LINE 		Control Type: Edit Role: ROLE_ENTRY
State: STATE_SINGLE_LINE
Interface: EditableText if aria-readonly is not "true" 		AXRole: AXTextField
AXSubrole: <nil>
AXRoleDescription: 'text field'
textbox when aria-multiline is true Role: ROLE_SYSTEM_TEXT
State: IA2_STATE_MULTI_LINE 		Control Type: Edit Role: ROLE_ENTRY
State: STATE_MULTI_LINE
Interface: EditableText if aria-readonly is not "true" 		AXRole: AXTextArea
AXSubrole: <nil>
AXRoleDescription: 'text entry area'
timer Object Attribute: xml-roles:timer
Object Attribute: container-live:off
Object Attribute: live:off
Object Attribute: container-live-role:timer 		Control Type: Group
Localized Control Type: timer
LiveSetting: Off (0) 		Role: ROLE_TIMER
Object Attribute: container-live:off
Object Attribute: live:off
Object Attribute: container-live-role:timer 		AXRole: AXGroup
AXSubrole: AXApplicationTimer
AXRoleDescription: 'timer'
toolbar Role: ROLE_SYSTEM_TOOLBAR Control Type: ToolBar Role: ROLE_TOOL_BAR AXRole: AXToolbar
AXSubrole: <nil>
AXRoleDescription: 'toolbar'
tooltip Role: ROLE_SYSTEM_TOOLTIP Control Type: ToolTip Role: ROLE_TOOL_TIP AXRole: AXGroup
AXSubrole: AXUserInterfaceTooltip
AXRoleDescription: 'tooltip'
tree Role: ROLE_SYSTEM_OUTLINE
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: Tree Role: ROLE_TREE
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: ROLE_SYSTEM_OUTLINE
Interface: IAccessibleTable2
Method: IAccessible::accSelect()
Method: IAccessible::get_accSelection() 		Control Type: DataGrid Role: ROLE_TREE_TABLE
Interface: Table
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: AXTable
AXSubrole: <nil>
AXRoleDescription: 'table'
treeitem Role: ROLE_SYSTEM_OUTLINEITEM
See also: aria-checked in the State and Property Mapping Table 		Control Type: TreeItem
See also: aria-checked in the State and Property Mapping Table 		Role: ROLE_TREE_ITEM
See also: aria-checked in the State and Property Mapping Table 		AXRole: AXRow
AXSubrole: AXOutlineRow
AXRoleDescription: 'outline row'
See also: aria-checked in the State and Property Mapping Table
Note

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

Note

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

4.5 State and Property Mapping

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

4.5.1 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.
  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-1.2]]. Where the author has not provided values for required attributes, user agents SHOULD process as if the default value was provided.
  5. 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.
  6. 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.2 [WAI-ARIA-1.2]].

4.5.2 State and Property Mapping Table

4.5.2.1 Not Mapped

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

In other cases, it is mandatory that the state/property not be mapped, since exposing it implies a related affordance. An example is aria-grabbed. 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.

Note

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 Focus Changes. See Focus Changes. See Focus Changes. See Focus Changes.
Property: AXSelectedRows: pointer to active descendant node
aria-atomic=true Object Attribute: atomic:true
Object Attribute: container-atomic:true
Object Attribute: container-atomic:true on all descendants
Relation: IA2_RELATION_MEMBER_OF pointing to this element (the atomic root)
See also: Changes to document content or node visibility 		Property: AriaProperties.atomic: true
See also: Changes to document content or node visibility 		Object Attribute: atomic:true
Object Attribute: container-atomic:true
Object Attribute: container-atomic:true on all descendants
Relation: RELATION_MEMBER_OF pointing to this element (the atomic root)
See also: Changes to document content or node visibility 		Property: AXARIAAtomic: YES
See also: Changes to document content or node visibility
aria-atomic=false Not mapped* — OPTIONAL — but if mapped:
Object Attribute: atomic:false
Object Attribute: container-atomic:false
Object Attribute: container-atomic:false on all descendants
Relation: IA2_RELATION_MEMBER_OF pointing to this element (the atomic root)
See also: Changes to document content or node visibility 		Property: AriaProperties.atomic: false
See also: Changes to document content or node visibility 		Not mapped* — OPTIONAL — but if mapped:
Object Attribute: atomic:false
Object Attribute: container-atomic:false
Object Attribute: container-atomic:false on all descendants
Relation: RELATION_MEMBER_OF pointing to this element (the atomic root)
See also: Changes to document content or node visibility 		Property: AXARIAAtomic: NO
See also: Changes to document content or node visibility
aria-autocomplete=inline, list, or both Object Attribute: autocomplete:<value>
State: IA2_STATE_SUPPORTS_AUTOCOMPLETION 		Not mapped Object Attribute: autocomplete:<value>
State: STATE_SUPPORTS_AUTOCOMPLETION 		Not mapped
aria-autocomplete=none Not mapped* Not mapped* Not mapped* Not mapped*
aria-busy=true State: STATE_SYSTEM_BUSY Property: AriaProperties.busy: true State: STATE_BUSY Property: AXElementBusy: YES
aria-busy=false State: STATE_SYSTEM_BUSY not exposed Property: AriaProperties.busy: false State: STATE_BUSY not exposed Property: AXElementBusy: NO
aria-checked=true State: STATE_SYSTEM_CHECKED
Object Attribute: checkable:true 		Property: Toggle.ToggleState: On (1)
Property: SelectionItem.IsSelected: True for radio and menuitemradio 		State: STATE_CHECKABLE
State: STATE_CHECKED 		Property: AXValue: 1
Property: AXMenuItemMarkChar: ✓ for menuitemcheckbox and menuitemradio
aria-checked=false State: STATE_SYSTEM_CHECKED not exposed
Object Attribute: checkable:true 		Property: Toggle.ToggleState: Off (0)
Property: SelectionItem.IsSelected: False for radio and menuitemradio 		State: STATE_CHECKABLE
State: STATE_CHECKED not exposed 		Property: AXValue: 0
Property: AXMenuItemMarkChar: <nil> for menuitemcheckbox and menuitemradio
aria-checked=mixed State: STATE_SYSTEM_MIXED
Object Attribute: checkable:true 		Property: Toggle.ToggleState: Indeterminate (2) State: STATE_INDETERMINATE
State: STATE_CHECKABLE
State: STATE_CHECKED not exposed 		Property: AXValue: 2
Property: AXMenuItemMarkChar: <nil> for menuitemcheckbox and menuitemradio
aria-checked is undefined Not mapped Not mapped Not mapped Not mapped
aria-colcount Object Attribute: colcount:<value>
Method: IAccessible2::groupPosition(): similarItemsInGroup=<value> on cells and headers 		Property: Grid.ColumnCount: <value>

If the value of aria-colcount is -1, calculate the column count based on the number of columns in the DOM and expose that value as described below along with STATE_INDETERMINATE.

Object Attribute: colcount:<value>
Method: atk_table_get_n_columns(): <value> 		Property: AXARIAColumnCount: <value>
aria-colindex Object Attribute: colindex:<value>
Method: IAccessible2::groupPosition(): positionInGroup=<value> on cells and headers 		Property: GridItem.Column: <value> (zero-based) Object Attribute: colindex:<value>
Method: atk_table_cell_get_position(): column=<value> 		Property: AXARIAColumnIndex: <value>
aria-colspan Object Attribute: colspan:<value>
Method: IAccessibleTableCell::columnExtent(): <value> 		Property: GridItem.ColumnSpan: <value> Object Attribute: colspan:<value>
Method: atk_table_cell_get_row_column_span(): column_span=<value> 		Property: AXColumnIndexRange.length: <value>
aria-controls Relation: IA2_RELATION_CONTROLLER_FOR points to accessible nodes matching IDREFs
Reverse Relation: IA2_RELATION_CONTROLLED_BY points to element
See also: Mapping Additional Relations 		Property: ControllerFor: pointers to accessible nodes matching IDREFs Relation: RELATION_CONTROLLER_FOR points to accessible nodes matching IDREFs
Reverse Relation: RELATION_CONTROLLED_BY points to element
See also: Mapping Additional Relations 		Property: AXLinkedUIElements: pointers to accessible nodes matching IDREFs
aria-current with non-false allowed value Object Attribute: current:<value> Property: AriaProperties.current: <value> Object Attribute: current:<value>
State: STATE_ACTIVE 		Property: AXARIACurrent: <value>
aria-current with unrecognized value Object Attribute: current:true Property: AriaProperties.current: true Object Attribute: current:true
State: STATE_ACTIVE 		Property: AXARIACurrent: true
aria-current is false or undefined Not mapped* Not mapped* Not mapped* Not mapped*
aria-describedby Property: accDescription: <value>
Relation: IA2_RELATION_DESCRIBED_BY points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: IA2_RELATION_DESCRIPTION_FOR points to element
See also: Name Computation and Mapping Additional Relations 		Property: FullDescription: <value>
Property: DescribedBy: points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
See also: Name Computation 		Property: Description: <value>
Relation: RELATION_DESCRIBED_BY points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: RELATION_DESCRIPTION_FOR points to element
See also: Name Computation and Mapping Additional Relations 		Property: AXHelp: <value>
See also: Name Computation
aria-details Relation: IA2_RELATION_DETAILS points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: IA2_RELATION_DETAILS_FOR points to element
See also: Mapping Additional Relations 		Property: DescribedBy: points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree Relation: RELATION_DETAILS points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: RELATION_DETAILS_FOR points to element
See also: Mapping Additional Relations 		Not mapped*
aria-disabled=true State: STATE_SYSTEM_UNAVAILABLE
State: STATE_SYSTEM_UNAVAILABLE on all descendants with STATE_SYSTEM_FOCUSABLE 		Property: IsEnabled: false State: STATE_ENABLED not exposed Property: AXEnabled: NO
aria-disabled=false State: STATE_SYSTEM_UNAVAILABLE not exposed Property: IsEnabled: true State: STATE_ENABLED Property: AXEnabled: YES
aria-dropeffect=copy, move, link, execute, or popup Object Attribute: dropeffect:<value> Property: AriaProperties.dropeffect: <value> Object Attribute: dropeffect:<value> array AXDropEffects
aria-dropeffect=none Object Attribute: dropeffect:none if there are no other valid tokens
Not mapped if not specified by the author 		Not mapped* Object Attribute: dropeffect:none if there are no other valid tokens
Not mapped if not specified by the author 		Not mapped*
aria-errormessage Relation: IA2_RELATION_ERROR points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: IA2_RELATION_ERROR_FOR points to element
See also: Mapping Additional Relations 		Property: ControllerFor: pointer to the target accessible object Relation: RELATION_ERROR_MESSAGE points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: RELATION_ERROR_FOR points to element
See also: Mapping Additional Relations 		Property: AXValidationError: textual content of the referenced element
aria-expanded=true State: STATE_SYSTEM_EXPANDED Property: ExpandCollapse.ExpandCollapseState: Expanded State: STATE_EXPANDABLE
State: STATE_EXPANDED 		Property: AXExpanded: YES
aria-expanded=false State: STATE_SYSTEM_COLLAPSED Property: ExpandCollapse.ExpandCollapseState: Collapsed State: STATE_EXPANDABLE
State: STATE_EXPANDED not exposed 		Property: AXExpanded: NO
aria-expanded is undefined Not mapped Not mapped Not mapped Not mapped
aria-flowto Relation: IA2_RELATION_FLOW_TO points to accessible nodes matching IDREFs
Reverse Relation: IA2_RELATION_FLOW_FROM points to element
See also: Mapping Additional Relations 		Property: FlowsTo: pointers to accessible nodes matching IDREFs Relation: RELATION_FLOWS_TO points to accessible nodes matching IDREFs
Reverse Relation: RELATION_FLOWS_FROM points to element
See also: Mapping Additional Relations 		Property: AXLinkedUIElements: pointers to accessible nodes matching IDREFs
aria-grabbed=true Object Attribute: grabbed:true Property: AriaProperties.grabbed: true Object Attribute: grabbed:true Property: AXGrabbed: YES
aria-grabbed=false Object Attribute: grabbed:false Property: AriaProperties.grabbed: false Object Attribute: grabbed:false Property: AXGrabbed: NO
aria-grabbed is undefined Not mapped Not mapped Not mapped Not mapped
aria-haspopup=true State: STATE_SYSTEM_HASPOPUP
Object Attribute: haspopup:true 		Control Pattern: ExpandCollapse See also: aria-expanded State: STATE_HAS_POPUP
Object Attribute: haspopup:true 		Property: Action: AXShowMenu
aria-haspopup=false State: STATE_SYSTEM_HASPOPUP not exposed
Object Attribute: haspopup:false 		Not mapped* Not mapped* Not mapped*
aria-haspopup=dialog State: STATE_SYSTEM_HASPOPUP
Object Attribute: haspopup:dialog 		Control Pattern: ExpandCollapse
See also: aria-expanded 		State: STATE_HAS_POPUP
Object Attribute: haspopup:dialog 		Action: AXShowMenu
aria-haspopup=listbox State: STATE_SYSTEM_HASPOPUP
Object Attribute: haspopup:listbox 		Control Pattern: ExpandCollapse
See also: aria-expanded 		State: STATE_HAS_POPUP
Object Attribute: haspopup:listbox 		Action: AXShowMenu
aria-haspopup=menu State: STATE_SYSTEM_HASPOPUP
Object Attribute: haspopup:menu 		Control Pattern: ExpandCollapse
See also: aria-expanded 		State: STATE_HAS_POPUP
Object Attribute: haspopup:menu 		Action: AXShowMenu
aria-haspopup=tree State: STATE_SYSTEM_HASPOPUP
Object Attribute: haspopup:tree 		Control Pattern: ExpandCollapse
See also: aria-expanded 		State: STATE_HAS_POPUP
Object Attribute: haspopup:tree 		Action: AXShowMenu
aria-hidden=true on unfocused element Element SHOULD NOT be exposed
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification 		Element SHOULD NOT be exposed
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification 		Element SHOULD NOT be exposed
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification 		Element SHOULD NOT be exposed
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification
aria-hidden=true when element is focused or fires an accessibility event Object Attribute: hidden:true
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification 		Property: AriaProperties.hidden: true
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification 		Object Attribute: hidden:true
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification 		Not mapped
See also: Including Elements in the Accessibility Tree in the WAI-ARIA specification
aria-hidden=false Not mapped Not mapped Not mapped Not mapped
aria-invalid=true State: IA2_STATE_INVALID_ENTRY
Text Attribute: invalid:true 		Property: IsDataValidForForm: false State: STATE_INVALID_ENTRY
Text Attribute: invalid:true 		Property: AXInvalid: true
aria-invalid=false State: IA2_STATE_INVALID_ENTRY not exposed Property: IsDataValidForForm: true State: STATE_INVALID_ENTRY not exposed Property: AXInvalid: false
aria-invalid=spelling or grammar State: IA2_STATE_INVALID_ENTRY
Text Attribute: invalid:<value> 		Property: IsDataValidForForm: <value> State: STATE_INVALID_ENTRY
Text Attribute: invalid:<value> 		Property: AXInvalid: <value>
aria-invalid with unrecognized value State: IA2_STATE_INVALID_ENTRY
Text Attribute: invalid:true 		Property: IsDataValidForForm: false State: STATE_INVALID_ENTRY
Text Attribute: invalid:true 		Property: AXInvalid: true
aria-keyshortcuts Property: accKeyboardShortcut: <value> Property: AcceleratorKey: <value> Object Attribute: keyshortcuts:<value> Not mapped*
aria-label Property: accName: <value>
See also: Name Computation 		Property: Name: <value>
See also: Name Computation 		Property: Name: <value>
See also: Name Computation 		Property: AXDescription: <value>
See also: Name Computation
aria-labelledby Property: accName: <value>
Relation: IA2_RELATION_LABELLED_BY points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: IA2_RELATION_LABEL_FOR points to element
See also: Name Computation and Mapping Additional Relations 		Property: Name: <value>
Property: LabeledBy: points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
See also: Name Computation 		Property: Name: <value>
Relation: RELATION_LABELLED_BY points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: RELATION_LABEL_FOR points to element
See also: Name Computation and Mapping Additional Relations 		Property: AXDescription: <value> if the value is not exposed visually
Property: AXTitle: <value> if the value is exposed visually
Property: AXTitleUIElement points to accessible node matching IDREF, if there is a single referenced element that is in the accessibility tree
See also: Name Computation
aria-level on non-heading Object Attribute: level:<value>
Method: IAccessible2::groupPosition(): groupLevel=<value> on roles that support aria-posinset and aria-setsize
See also: groupPosition() 		Property: AriaProperties.level: <value> Object Attribute: level:<value> Property: AXDisclosureLevel: <value> (zero-based), when used on an outline row (like a treeitem or group)
aria-level on heading Object Attribute: level:<value> Property: AriaProperties.level: <value>
Property: StyleId_Heading: <value> 		Object Attribute: level:<value> Property: AXValue: <value>
aria-live=assertive Object Attribute: live:assertive
Object Attribute: container-live:assertive
Object Attribute: container-live:assertive on all descendants
See also: Changes to document content or node visibility 		Property: LiveSetting: "assertive"
See also: Changes to document content or node visibility 		Object Attribute: live:assertive
Object Attribute: container-live:assertive
Object Attribute: container-live:assertive on all descendants
See also: Changes to document content or node visibility 		Property: AXARIALive: "assertive"
See also: Changes to document content or node visibility
aria-live=polite Object Attribute: live:polite
Object Attribute: container-live:polite
Object Attribute: container-live:polite on all descendants
See also: Changes to document content or node visibility 		Property: LiveSetting: "polite"
See also: Changes to document content or node visibility 		Object Attribute: live:polite
Object Attribute: container-live:polite
Object Attribute: container-live:polite on all descendants
See also: Changes to document content or node visibility 		Property: AXARIALive: "polite"
See also: Changes to document content or node visibility
aria-live=off Object Attribute: live:off
Object Attribute: container-live:off
Object Attribute: container-live:off on all descendants 		Property: LiveSetting: "off" Object Attribute: live:off
Object Attribute: container-live:off
Object Attribute: container-live:off on all descendants
 Property: AXARIALive: "off"
aria-modal=true State: IA2_STATE_MODAL Property: Window.IsModal: true
 State: 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 State: IA2_STATE_MODAL not exposed Property: Window.IsModal: false
 State: STATE_MODAL not exposed 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 State: IA2_STATE_MULTI_LINE
State: IA2_STATE_SINGLE_LINE not exposed 		Property: AriaProperties.multiline: true State: STATE_MULTI_LINE
State: STATE_SINGLE_LINE not exposed 		Not mapped
See also: textbox in the Role Mapping Table
aria-multiline=false State: IA2_STATE_SINGLE_LINE
State: IA2_STATE_MULTI_LINE not exposed 		Not mapped* State: STATE_SINGLE_LINE
State: STATE_MULTI_LINE not exposed 		Not mapped
See also: textbox in the Role Mapping Table
aria-multiselectable=true State: STATE_SYSTEM_MULTISELECTABLE
State: STATE_SYSTEM_EXTSELECTABLE
See also: Selection for details on accessibility events 		Property: Selection.CanSelectMultiple: true
See also: Selection for details on accessibility events 		State: STATE_MULTISELECTABLE
See also: Selection for details on accessibility events 		Not mapped*
See also: Selection for details on accessibility events
aria-multiselectable=false State: STATE_SYSTEM_MULTISELECTABLE not exposed
State: STATE_SYSTEM_EXTSELECTABLE not exposed
See also: Selection for details on accessibility events 		Not mapped* State: STATE_MULTISELECTABLE not exposed Not mapped*
aria-orientation=horizontal State: IA2_STATE_HORIZONTAL
State: IA2_STATE_VERTICAL not exposed 		Property: Orientation: horizontal State: STATE_HORIZONTAL
State: STATE_VERTICAL not exposed 		Property: AXOrientation: AXHorizontalOrientation
aria-orientation=vertical State: IA2_STATE_VERTICAL
State: IA2_STATE_HORIZONTAL not exposed 		Property: Orientation: vertical State: STATE_VERTICAL
State: STATE_HORIZONTAL not exposed 		Property: AXOrientation: AXVerticalOrientation
aria-orientation is undefined Not mapped* Not mapped* State: STATE_VERTICAL not exposed
State: STATE_HORIZONTAL not exposed 		Property: AXOrientation: AXUnknownOrientation
aria-owns

User agents MAY expose the elements that are referenced by this property as children of the current element. In which case, if multiple aria-owns relationships are found, use only the first one. If the accessibility tree is not modified, expose as:

Relation: IA2_RELATION_NODE_PARENT_OF points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: IA2_RELATION_NODE_CHILD_OF points to element
See also: Mapping Additional Relations 		Expose 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.

User agents MAY expose the elements that are referenced by this property as children of the current element. In which case, if multiple aria-owns relationships are found, use only the first one. If the accessibility tree is not modified, expose as:

Relation: RELATION_NODE_PARENT_OF points to accessible nodes matching IDREFs, if the referenced objects are in the accessibility tree
Reverse Relation: RELATION_NODE_CHILD_OF points to element
See also: Mapping Additional Relations 		Property: AXOwns: pointers to accessible nodes matching IDREFs
aria-placeholder Object Attribute: placeholder-text:<value> Property: HelpText: <value> Object Attribute: placeholder-text:<value> Property: AXPlaceholderValue: <value>
aria-posinset Object Attribute: posinset:<value>
See also: Group Position 		Property: AriaProperties.posinset: <value>
See also: Group Position 		Object Attribute: posinset:<value>
See also: Group Position 		Property: AXARIAPosInSet: <value>
See also: Group Position
aria-pressed=true State: STATE_SYSTEM_PRESSED
See also: button with defined value for aria-pressed 		Property: Toggle.ToggleState: On (1) State: STATE_PRESSED
See also: button with defined value for aria-pressed 		Property: AXValue: 1
See also: button with defined value for aria-pressed
aria-pressed=mixed State: STATE_SYSTEM_MIXED
See also: button with defined value for aria-pressed 		Property: Toggle.ToggleState: Indeterminate (2) State: STATE_INDETERMINATE
See also: button with defined value for aria-pressed 		Property: AXValue: 2
See also: button with defined value for aria-pressed
aria-pressed=false State: STATE_SYSTEM_PRESSED not exposed
See also: button with defined value for aria-pressed 		Property: Toggle.ToggleState: Off (3) State: STATE_PRESSED not exposed
See also: button with defined value for aria-pressed 		Property: AXValue: 0
See also: button with defined value for aria-pressed
aria-pressed is undefined Not mapped* Not mapped* Not mapped* Not mapped*
aria-readonly=true State: STATE_SYSTEM_READONLY Property: Value.IsReadOnly: true State: STATE_READ_ONLY
State: STATE_EDITABLE not exposed on text input roles
State: STATE_CHECKABLE not exposed on roles supporting aria-checked
State: STATE_CHECKABLE not exposed on radio descendants when used on a radiogroup 		Method: AXUIElementIsAttributeSettable(AXValue): NO
aria-readonly=false State: STATE_SYSTEM_READONLY not exposed
State: IA2_STATE_EDITABLE 		Property: Value.IsReadOnly: false State: STATE_READ_ONLY not exposed Method: AXUIElementIsAttributeSettable(AXValue): YES
aria-readonly is unspecified on gridcell The gridcell MUST inherit any author-provided value for aria-readonly from the containing grid or treegrid. Expose the inherited value on the gridcell as described for aria-readonly="true" and aria-readonly="false". The gridcell MUST inherit any author-provided value for aria-readonly from the containing grid or treegrid. Expose the inherited value on the gridcell as described for aria-readonly="true" and aria-readonly="false". The gridcell MUST inherit any author-provided value for aria-readonly from the containing grid or treegrid. Expose the inherited value on the gridcell as described for aria-readonly="true" and aria-readonly="false". The gridcell MUST inherit any author-provided value for aria-readonly from the containing grid or treegrid. Expose the inherited value on the gridcell as described for aria-readonly="true" and aria-readonly="false".
aria-relevant Object Attribute: relevant:<value>
Object Attribute: container-relevant:<value>
Object Attribute: container-relevant:<value> on all descendants
See also: Changes to document content or node visibility 		Property: AriaProperties.relevant: <value>
See also: Changes to document content or node visibility 		Object Attribute: relevant:<value>
Object Attribute: container-relevant:<value>
Object Attribute: container-relevant:<value> on all descendants
See also: Changes to document content or node visibility 		Property: AXARIARelevant: <value>
See also: Changes to document content or node visibility
aria-required=true State: IA2_STATE_REQUIRED Property: IsRequiredForForm: true State: STATE_REQUIRED Property: AXRequired: YES
aria-required=false Not mapped* Not mapped* Not mapped* Not mapped*
aria-roledescription Method: localizedExtendedRole(): <value> Localized Control Type: <value> Object Attribute: roledescription:<value> Property: AXRoleDescription: <value>
aria-roledescription is 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 Object Attribute: rowcount:<value>
Method: IAccessible2::groupPosition(): similarItemsInGroup=<value> on rows 		Property: Grid.RowCount: <value>

If the value of aria-rowcount is -1, calculate the row count based on the number of rows in the DOM and expose that value as described below along with STATE_INDETERMINATE.

Object Attribute: rowcount:<value>
Method: atk_table_get_n_rows(): <value> 		Property: AXARIARowCount: <value>
aria-rowindex Object Attribute: rowindex:<value>
Method: IAccessible2::groupPosition(): positionInGroup=<value> on rows 		Property: GridItem.Row: <value> (zero-based) Object Attribute: rowindex:<value>
Method: atk_table_cell_get_position(): row=<value> 		Property: AXARIARowIndex: <value>
aria-rowspan Object Attribute: rowspan:<value>
Method: IAccessibleTableCell::rowExtent(): column=<value> 		Property: GridItem.RowSpan: <value> Object Attribute: rowspan:<value>
Method: atk_table_cell_get_row_column_span(): row_span=<value> 		Property: AXRowIndexRange.length: <value>
aria-selected=true State: STATE_SYSTEM_SELECTABLE
State: STATE_SYSTEM_SELECTED
See also: Selection for details on accessibility events 		Property: SelectionItem.IsSelected: true State: STATE_SELECTABLE
State: STATE_SELECTED
See also: Selection for details on accessibility events 		Property: AXSelected: YES
aria-selected=false State: STATE_SYSTEM_SELECTABLE
State: STATE_SYSTEM_SELECTED not exposed
See also: Selection for details on accessibility events 		Property: SelectionItem.IsSelected: false State: STATE_SELECTABLE
State: STATE_SELECTED not exposed
See also: Selection for details on accessibility events 		Property: AXSelected: NO
aria-selected is undefined Not mapped Not mapped Not mapped Not mapped
aria-setsize Object Attribute: setsize:<value>
See also: Group Position 		Property: AriaProperties.setsize: <value>
See also: Group Position

If the author-provided value of aria-setsize is -1, the exposed value should be based on the number of objects in the DOM.

Object Attribute: setsize:<value>
State: STATE_INDETERMINATE if the author-provided value is -1
See also: Group Position 		Property: AXARIASetSize: <value>
See also: Group Position
aria-sort=ascending Object Attribute: sort:ascending Property: AriaProperties.sort: ascending
Property: ItemStatus: ascending if the element maps to HeaderItem Control Type 		Object Attribute: sort:ascending Property: AXSortDirection: AXAscendingSortDirection
aria-sort=descending Object Attribute: sort:descending Property: AriaProperties.sort: descending
Property: ItemStatus: descending if the element maps to HeaderItem Control Type 		Object Attribute: sort:descending Property: AXSortDirection: AXDescendingSortDirection
aria-sort=other Object Attribute: sort:other Property: AriaProperties.sort: other
Property: ItemStatus: other if the element maps to HeaderItem Control Type 		Object Attribute: sort:other Property: AXSortDirection: AXUnknownSortDirection
aria-sort=none Object Attribute: sort:none, if the value is not unspecified Not mapped* Object Attribute: sort:none, if the value is not unspecified Not mapped*
aria-valuemax Method: IAccessibleValue::maximumValue(): <value>
See also: Handling Author Errors for States and Properties 		Property: RangeValue.Maximum: <value>
See also: Handling Author Errors for States and Properties 		Method: atk_value_get_maximum_value(): <value>
See also: Handling Author Errors for States and Properties 		Property: AXMaxValue: <value>
See also: Handling Author Errors for States and Properties
aria-valuemin Method: IAccessibleValue::minimumValue(): <value>
See also: Handling Author Errors for States and Properties 		Property: RangeValue.Minimum: <value>
See also: Handling Author Errors for States and Properties 		Method: atk_value_get_minimum_value(): <value>
See also: Handling Author Errors for States and Properties 		Property: AXMinValue: <value>
See also: Handling Author Errors for States and Properties
aria-valuenow Method: IAccessibleValue::currentValue(): <value>
Method: IAccessible::get_accValue(): <value> if aria-valuetext is not defined
See also: Handling Author Errors for States and Properties 		Property: RangeValue.Value: <value>
See also: Handling Author Errors for States and Properties 		Method: atk_value_get_current_value(): <value>
See also: Handling Author Errors for States and Properties 		Property: AXValue: <value>
See also: Handling Author Errors for States and Properties
aria-valuetext Method: IAccessible::get_accValue(): <value>
Object Attribute: valuetext:<value>
See also: Handling Author Errors for States and Properties 		Property: Value.Value: <value>
See also: Handling Author Errors for States and Properties 		Object Attribute: valuetext:<value>
See also: Handling Author Errors for States and Properties 		Property: AXValueDescription: <value>
See also: Handling Author Errors for States and Properties

4.6 Special Processing Requiring Additional Computation

4.6.1 Name and Description

For information on how to compute an accessible name or accessible description, see the section titled Accessible Name and Description Computation of the Accessible Name and Description Computation specification.

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

4.6.2.1 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 State and Property Mapping Table when an element's ID is referenced by a relation property of another element and the referenced element is in the accessibility tree. 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.

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.

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

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

4.7 Actions

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

Note

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

4.8 Events

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

4.8.1 State and Property Change Events

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

Note

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

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

Note

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

In addition:

IA2_EVENT_ACTIVE_DESCENDANT_CHANGED

 See Focus Changes. See Focus Changes. See Focus Changes.

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-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 EVENT_OBJECT_DESCRIPTIONCHANGE PropertyChangeEvent object:property-change:accessible-description TBD
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 EVENT_OBJECT_NAMECHANGE PropertyChangeEvent object:property-change:accessible-name TBD
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

4.8.2 Changes to document content or node visibility

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

Table of document change scenarios and events to be fired in each API
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.
If in aria-errormessage, AXValidationErrorChanged.
When text is inserted IA2_EVENT_TEXT_INSERTED EVENT_OBJECT_LIVEREGIONCHANGED text_changed::insert If in a live region, AXLiveRegionChanged.
If in aria-errormessage, AXValidationErrorChanged.
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.
If in aria-errormessage, AXValidationErrorChanged.

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.

4.8.3 Focus Changes

The following table defines the accessibility API keyboard focus states and events.

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

4.8.4 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

4.8.5 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

A. Change Log

A.1 Substantive changes since the last public working draft

A.2 Substantive changes since the Core Accessibility API Mappings 1.1 Recommendation

B. Acknowledgments

This section is non-normative.

The following people contributed to the development of this document.

B.1 Participants active in the ARIA WG at the time of publication

B.2 Other ARIA contributors, commenters, and previously active participants

B.3 Enabling funders

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

C. References

C.1 Normative references

[AT-SPI]
Assistive Technology Service Provider Interface. The GNOME Project. URL: https://developer.gnome.org/libatspi/stable/
[ATK]
ATK - Accessibility Toolkit. The GNOME Project. URL: https://developer.gnome.org/atk/stable/
[AXAPI]
The NSAccessibility Protocol for macOS. Apple, Inc. URL: https://developer.apple.com/documentation/appkit/nsaccessibility
[CORE-AAM-1.1]
Core Accessibility API Mappings 1.1. Joanmarie Diggs; Joseph Scheuhammer; Richard Schwerdtfeger; Michael Cooper; Andi Snow-Weaver; Aaron Leventhal. W3C. 14 December 2017. W3C Recommendation. URL: https://www.w3.org/TR/core-aam-1.1/
[HTML5]
HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 27 March 2018. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[IAccessible2]
IAccessible2. Linux Foundation. URL: https://www.linuxfoundation.org/collaborate/workgroups/accessibility/iaccessible2
[MSAA]
Microsoft Active Accessibility (MSAA) 2.0. Microsoft Corporation. URL: https://msdn.microsoft.com/en-us/library/ms697707.aspx
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[UI-AUTOMATION]
UI Automation. Microsoft Corporation. URL: https://msdn.microsoft.com/en-us/library/ee684009%28v=vs.85%29.aspx
[UIA-EXPRESS]
The IAccessibleEx Interface. Microsoft Corporation. URL: https://msdn.microsoft.com/en-us/library/windows/desktop/dd561898%28v=vs.85%29.aspx
[WAI-ARIA-1.2]
Accessible Rich Internet Applications (WAI-ARIA) 1.2. Joanmarie Diggs; James Nurthen; Michael Cooper. W3C. 19 July 2018. W3C Working Draft. URL: https://www.w3.org/TR/wai-aria-1.2/
[WCAG21]
Web Content Accessibility Guidelines (WCAG) 2.1. Andrew Kirkpatrick; Joshue O Connor; Alastair Campbell; Michael Cooper. W3C. 5 June 2018. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/

C.2 Informative references

[WAI-ARIA-PRACTICES-1.2]
WAI-ARIA Authoring Practices 1.2. Matthew King; James Nurthen; Zoë Bijl; Michael Cooper; Joseph Scheuhammer; Lisa Pappas; Richard Schwerdtfeger. W3C. 19 July 2018. W3C Working Draft. URL: https://www.w3.org/TR/wai-aria-practices-1.2/
[WAI-ARIA-ROADMAP]
Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap). Richard Schwerdtfeger. W3C. 4 February 2008. W3C Working Draft. URL: https://www.w3.org/TR/wai-aria-roadmap/