WAI-ARIA 1.0 User Agent Implementation Guide

Table of accessibility APIs for focus states and events
	MSAA	Microsoft UIA	ATK/AT-SPI	Mac OS X Accessibility
Focusable state	`STATE_SYSTEM_FOCUSABLE`	`UIA_IsKeyboardFocusablePropertyId`	`STATE_FOCUSABLE`	`boolean AXFocused` (writable)
Focused state	`STATE_SYSTEM_FOCUSED`	`UIA_HasKeyboardFocusPropertyId`	`STATE_FOCUSED`	`boolean AXFocused`
Focus event	`EVENT_OBJECT_FOCUS`	`UIA_AutomationFocusChangedEventId`	`object:state-changed:focused` or `focus:`	`AXFocusedUIElementChanged`

5. Mapping WAI-ARIA to Accessibility APIs

This section is normative.

5.1. General rules for exposing WAI-ARIA semantics

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

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

5.1.1. Excluding Elements from the Accessibility Tree

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

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

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

Elements, including their descendents, that have a WAI-ARIA global attribute of aria-hidden="true". In other words, aria-hidden="true" on a parent overrides aria-hidden="false" on descendants.
Children of objects which have the characteristic "Children Presentational: True":

5.1.2. Including Elements in the Accessibility Tree

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

Text elements
Elements that may fire an accessibility API event
Elements that are focusable, or have an ID attribute and an ancestor with the aria-activedescendant attribute that matches the implicit or explicit semantics of the required context role. In either case, the element may receive focus and need to fire a FOCUS event.
Elements that have a mappable role in the role attribute string (see Role Mapping below).
Elements that have a global WAI-ARIA attribute but do not have aria-hidden="true". (See Excluding Elements in the Accessibility Tree for additional guidance on aria-hidden.)
Elements that have an ID which is referenced by another element via a WAI-ARIA relation (aria-controls, aria-describedby, aria-flowto, aria-labelledby or aria-owns) and are not hidden.
Note: Text equivalents for hidden referenced objects may still be used in the name and description calculation even when not included in the accessibility tree.

5.1.3. Notification of State Changes

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

5.2. Conflicts between native markup semantics and WAI-ARIA

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

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

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

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

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

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

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

In IAccessible2 and ATK/AT-SPI, use object attributes to expose semantics that are not directly supported in the APIs. Object attributes are name-value pairs that are loosely specified, and very flexible for exposing things where there is no specific interface in an accessibility API. For example, at this time, the aria-live attribute can be exposed via an object attribute because accessibility APIs have no such property available. Specific rules for exposing object attribute name-value pairs are described throughout this document, and rules for the general cases are in State and Property Mapping.
In Microsoft UIA, use the AriaRole and AriaProperties properties to expose semantics that are not directly supported in the control type.

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

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

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

5.4. Role mapping

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

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

The user agent MUST use the first token in the sequence of tokens in the role attribute value which matches, on comparison, the name of any non-abstract WAI-ARIA role according to rules that are specified in the Role Mapping Table below. See Conflicts between native markup semantics and WAI-ARIA for additional information. Note that when WAI-ARIA roles override host language semantics, there are no changes in the DOM, only in the accessibility tree. In the absence of author-supplied scripts, the presence of WAI-ARIA roles might not make sense. But user agents MUST map WAI-ARIA roles even in the absence of author-supplied scripts.
The following steps will correctly identify the applicable WAI-ARIA role:
1. Use the rules of the host language to detect that an element has a role attribute and to identify the attribute value string for it.
2. Separate the attribute value string for that attribute into a sequence of whitespace-free substrings by separating on whitespace.
3. Do a comparison of the substrings to all the names of the non-abstract WAI-ARIA roles. Case-sensitivity of the comparison inherits from the case-sensitivity of the host language.
4. Use the first such substring in textual order that matches the name of a non-abstract WAI-ARIA role for the API role mapping. See the Role Mapping Table below for details.
User agents MUST NOT map roles defined in the WAI-ARIA specification as "abstract" via the standard role mechanism of the accessibility API. The abstract roles are:
If the element does not have a role attribute, or if the role attribute contains no tokens matching the name of a non-abstract WAI-ARIA role, the user agent MUST fall back on normal processing of the base markup for the element with the role attribute. For example, for <table role="foo"> use the element name table to determine what platform accessibility API role to use according to the host language's role mapping. For <input type="text" role="bar">, use the platform accessibility API for a text input.
When an explicit or inherited role of presentation is applied to an element, the user agent MUST implement the rules for presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [ARIA].
User agents MUST expose the WAI-ARIA role string if the API supports a mechanism to do so. This allows assistive technologies to do their own additional processing of roles.
- MSAA : not supported
- IAccessible2: expose as an object attribute pair (xml-roles:"string")
- UIA: 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")
Platform accessibility APIs typically do not provide a vehicle to notify assistive technologies that a role has changed. Due to this and document caching, assistive technologies are unlikely to process a change in role attribute value. Authors who wish to change a role are advised by the WAI-ARIA specification to delete the associated element and its children and replace it with a new element having the appropriate role. If a role is changed, however, user agents SHOULD update the mapping in order to reflect the content in the DOM. Since assistive technologies will not know that the role has changed, user agents MAY address this error condition by treating it as removing a subtree item and inserting a new one as described in Changes to document content or node visibility.

5.4.1. Role Mapping Table

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

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Table describing mapping of WAI-ARIA roles to accessibility APIs.
WAI-ARIA role	MSAA + UIA Express role	MSAA + IAccessible2 role and other IAccessible2 features	UIA Control Type and other features	ATK/AT-SPI role	Mac OS X AXRole AXSubrole AXRoleDescription^{[Note 1]}
`alert`	`ROLE_SYSTEM_ALERT` The user agent SHOULD fire `EVENT_SYSTEM_ALERT` ^{[Note 2]}	`ROLE_SYSTEM_ALERT` The user agent SHOULD fire `EVENT_SYSTEM_ALERT` ^{[Note 2]}	`Text` The user agent SHOULD fire a system alert event.^{[Note 2]}	`ROLE_ALERT` The user agent SHOULD fire a system alert event.^{[Note 2]}	`AXGroup` `AXApplicationAlert` `'alert'` The user agent SHOULD fire a system alert event.^{[Note 2]}
`alertdialog`	`ROLE_SYSTEM_DIALOG` The user agent SHOULD fire `EVENT_SYSTEM_ALERT` ^{[Note 2]}	`ROLE_SYSTEM_DIALOG` The user agent SHOULD fire `EVENT_SYSTEM_ALERT` ^{[Note 2]}	`Pane` The user agent SHOULD fire a system alert event.^{[Note 2]}	`ROLE_DIALOG` The user agent SHOULD fire a system alert event.^{[Note 2]}	`AXGroup` `AXApplictionAlertDialog` `'alert dialog'` The user agent SHOULD fire a system alert event.^{[Note 2]}
`application`	`ROLE_SYSTEM_APPLICATION`	`ROLE_SYSTEM_APPLICATION`	`Pane`	`ROLE_EMBEDDED`	`AXGroup` `AXLandmarkApplication` `'application'`
`article`	`ROLE_SYSTEM_DOCUMENT` + `STATE_SYSTEM_READONLY`	`ROLE_SYSTEM_DOCUMENT` + `STATE_SYSTEM_READONLY` IAccessible2: Object attribute `xml-roles:article`	Expose as text string in `AriaRole`	`ROLE_DOCUMENT_FRAME` + do not expose `STATE_EDITABLE` Object attribute `xml-roles:article`	`AXGroup` `AXDocumentArticle` `'article'`
`banner`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:banner`	Expose as text string in `AriaRole`	Object attribute `xml-roles:banner`	`AXGroup` `AXLandmarkBanner` `'banner'`
`button`	`ROLE_SYSTEM_PUSHBUTTON`.	`ROLE_SYSTEM_PUSHBUTTON`. If `aria-haspopup="true"`, expose as `ROLE_SYSTEM_BUTTONMENU` IAccessible2: If `aria-pressed` is not undefined, it SHOULD be exposed as `IA2_ROLE_TOGGLE_BUTTON`	`Button`	`ROLE_PUSH_BUTTON` If `aria-pressed` (state) is not undefined, it SHOULD be exposed as `ROLE_TOGGLE_BUTTON`	If `aria-pressed (state)` is defined (true/false/mixed) use: `AXCheckBox` `AXToggleButton` `'toggle button'` If `aria-pressed (state)` is not defined use: `AXButton` `<nil>` `'button'`
`checkbox`	`ROLE_SYSTEM_CHECKBUTTON`	`ROLE_SYSTEM_CHECKBUTTON` IAccessible2: Object attribute `checkable:true`	`Checkbox`	`ROLE_CHECK_BOX` + object attribute `checkable:true`	`AXCheckBox` `<nil>` `'check box'`
`columnheader`	`ROLE_SYSTEM_COLUMNHEADER`	`ROLE_SYSTEM_COLUMNHEADER` IAccessible2: Used to help support `AccessibleTable` for the container `grid` role	`HeaderItem`	`ROLE_COLUMN_HEADER`	`AXCell` or `AXSortButton` if using `aria-sort` `<nil>` `'cell`' Parent table also implements `AXColumnHeaderUIElements` property that is a list of pointers to the column header cells. Parent table also implements `AXHeader` property that is a pointer to the row or group containing the columnheader cells.
`combobox`	`ROLE_SYSTEM_COMBOBOX` + `STATE_SYSTEM_HASPOPUP`. If `aria-expanded` (state) is not `"true"`, expose `STATE_SYSTEM_COLLAPSED`.	`ROLE_SYSTEM_COMBOBOX` + `STATE_SYSTEM_HASPOPUP`. If `aria-expanded` (state) is not `"true"`, expose `STATE_SYSTEM_COLLAPSED`.	`Combobox`	`ROLE_COMBO_BOX` + `STATE_EXPANDABLE` + object attribute `haspopup:true`	`AXComboBox` `<nil>` `'combo box'`
`complementary`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:complementary`	Expose as text string in `AriaRole`	Object attribute `xml-roles:complementary`	`AXGroup` `AXLandmarkComplementary` `'complementary'`
`contentinfo`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:contentinfo`	Expose as text string in `AriaRole`	Object attribute `xml-roles:contentinfo`	`AXGroup` `AXLandmarkContentInfo` `'content'`
`definition`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:definition`	Expose as text string in `AriaRole`	Object attribute `xml-roles:definition`	`AXGroup` `AXDefinition` `'definition'`
`dialog`	`ROLE_SYSTEM_DIALOG`	`ROLE_SYSTEM_DIALOG`	`Pane`	`ROLE_DIALOG`	`AXGroup` `AXApplicationDialog` `'dialog'`
`directory`	`ROLE_SYSTEM_LIST`	`ROLE_SYSTEM_LIST`	`List`	`ROLE_LIST`	`AXList` `AXContentList` `'content list'`
`document`	`ROLE_SYSTEM_DOCUMENT` + `STATE_SYSTEM_READONLY`	`ROLE_SYSTEM_DOCUMENT` + `STATE_SYSTEM_READONLY`	`Document`	`ROLE_DOCUMENT_FRAME` + do not expose `STATE_EDITABLE`	`AXGroup` `AXDocument` `'document'`
`form`	Expose as text string in `AriaRole`	`IAccessible2: IA2_ROLE_FORM`	Expose as text string in `AriaRole`	`ROLE_FORM`	`AXGroup` `<nil>` `'group'`
`grid`	`ROLE_SYSTEM_TABLE`	`ROLE_SYSTEM_TABLE` IAccessible2: Use `IAccessibleTable2` interface	`DataGrid` Also requires `selection` pattern	`ROLE_TABLE`	`AXTable` `<nil>` `'table'`
`gridcell`	`ROLE_SYSTEM_CELL`	`ROLE_SYSTEM_CELL`	`DataItem` Also requires `selectionitem` pattern; `selectionContainer` property must reference the parent `grid` object	`ROLE_TABLE_CELL`	`AXCell` `<nil>` `'cell'`
`group`	`ROLE_SYSTEM_GROUPING`	`ROLE_SYSTEM_GROUPING`	`Group`	`ROLE_PANEL`	`AXGroup` `<nil>` `'group'`
`heading` The heading level is specified by the `aria-level` property.	`ROLE_SYSTEM_TEXT`	Expose as object attribute `xml-roles:heading`. Also, expose `IAccessible2: IA2_ROLE_HEADING`	`Text`	`ROLE_HEADING`	`AXHeading` `<nil>` `'heading'`
`img`	`ROLE_SYSTEM_GRAPHIC`	`ROLE_SYSTEM_GRAPHIC`	`Image`	`ROLE_IMAGE`	`AXImage` `<nil>` `'image'`
`link`	`ROLE_SYSTEM_LINK` + `STATE_LINKED` Also, expose `STATE_LINKED` on all descendants	`ROLE_SYSTEM_LINK` + `STATE_LINKED` Also, expose `STATE_LINKED` on all descendants IAccessible2: Use `AccessibleHypertext` interface	`HyperLink`	`ROLE_LINK`	`AXLink` `<nil>` `'link'`
`list`	`ROLE_SYSTEM_LIST` + `STATE_SYSTEM_READONLY`	`ROLE_SYSTEM_LIST` + `STATE_SYSTEM_READONLY`	`List` When the `list` contains `listitems`, it must implement the `selection` pattern.	`ROLE_LIST` + do not expose `STATE_EDITABLE`	`AXList` `AXContentList` `'content list'`
`listbox`	`ROLE_SYSTEM_LIST`	`ROLE_SYSTEM_LIST`	`List`	`ROLE_LIST`. Special case: if a `listbox` has a parent or is owned by (via `aria-owns`) a `combobox`, it SHOULD be exposed with `ROLE_MENU`.	`AXList` `<nil>` `'list'`
`listitem`	`ROLE_SYSTEM_LISTITEM`	`ROLE_SYSTEM_LISTITEM` + `STATE_SYSTEM_READONLY`	`ListItem` Also requires `selectionitem` pattern; `selectionContainer` property must reference the parent `list` object	`ROLE_LISTITEM` + do not expose `STATE_EDITABLE`	`AXGroup` `<nil>` `'group'`
`log`	Control type/role is `group` Localized Control Type is `log`. `LiveSettingProperty = On (1)`.	IAccessible2: object attributes `xml-roles:log;container-live:polite;live:polite;container-live-role:log`	Control type/role is `group` Localized Control Type is `log`. `LiveSettingProperty = On (1)`.	object attributes `xml-roles:log;container-live:polite;live:polite;container-live-role:log`	`AXGroup` `AXApplicationLog` `'log'`
`main`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:main`	Expose as text string in `AriaRole`	Object attribute `xml-roles:main`	`AXGroup` `AXLandmarkMain` `'main'`
`marquee`	`ROLE_SYSTEM_ANIMATION`	`ROLE_SYSTEM_ANIMATION` + IAccessible2: object attribute `xml-roles:marquee;container-live:off;live:off`	`Text`	`ROLE_ANIMATION` + object attributes `container-live:off;live:off`	`AXGroup` `AXApplicationMarquee` `'marquee'`
`math`	`ROLE_SYSTEM_EQUATION`	`ROLE_SYSTEM_EQUATION`	Expose as text string in `AriaRole`	`ROLE_UNKNOWN`	`AXGroup` `AXDocumentMath` `'math'`
`menu`	`ROLE_SYSTEM_MENUPOPUP`	`ROLE_SYSTEM_MENUPOPUP`	`Menu`	`ROLE_MENU` These objects are not exposed for a submenu if there is a parent menu item spawning the submenu. Since ATK/AT-SPI allows menuitems to have menuitem children, interposing menu objects are not exposed, except for the root parent.	`AXMenu` `<nil>` `'menu'`
`menubar`	`ROLE_SYSTEM_MENUBAR`	`ROLE_SYSTEM_MENUBAR`	`MenuBar`	`ROLE_MENU_BAR`	`AXMenuBar` `<nil>` `'menu bar'`
`menuitem`	`ROLE_SYSTEM_MENUITEM`	`ROLE_SYSTEM_MENUITEM`	`MenuItem`	`ROLE_MENU_ITEM` If `aria-checked` (state) is not undefined, support object attribute `checkable:true`	If the option's parent has a `group` role, then `role="menuitem"` maps to `AXMenuButton` If the option's parent has a `menu` role, then `role="menuitem"` maps to `AXMenuItem` `AXMenuItem` `<nil>` `'menu item`'
`menuitemcheckbox`	`ROLE_SYSTEM_CHECKBUTTON` or `ROLE_SYSTEM_MENUITEM`	`ROLE_SYSTEM_CHECKBUTTON` or `ROLE_SYSTEM_MENUITEM` `IAccessible2: IA2_ROLE_CHECK_MENU_ITEM` + object attribute `checkable:true`	`MenuItem` + `Toggle` Pattern	`ROLE_CHECK_MENU_ITEM` + object attribute `checkable:true`	`AXMenuItem` `<nil>` `'menu item`' If `aria-checked` (state)`="true"`: `AXMenuItemMarkChar` ✓ Otherwise: `AXMenuItemMarkChar` `<nil>`
`menuitemradio`	`ROLE_SYSTEM_RADIOBUTTON` or `ROLE_SYSTEM_MENUITEM` See "Special case" under `aria-checked` for mapping `aria-checked` (state) attribute for radio buttons.	`ROLE_SYSTEM_RADIOBUTTON` or `ROLE_SYSTEM_MENUITEM` `IAccessible2: IA2_ROLE_RADIO_MENU_ITEM` + object attribute `checkable:true`	`MenuItem`	`ROLE_RADIO_MENU_ITEM` + object attribute `checkable:true`	`AXMenuItem` `<nil>` `'menu item`' If `aria-checked` (state)`="true"`: `AXMenuItemMarkChar` ✓. Otherwise: `AXMenuItemMarkChar` `<nil>`
`navigation`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:navigation`	Expose as text string in `AriaRole`	Object attribute `xml-roles:navigation`	`AXGroup` `AXLandmarkNavigation` `'navigation'`
`note`	Expose as text string in `AriaRole`	`IAccessible2: IA2_ROLE_NOTE`	Expose as text string in `AriaRole`	Object attribute `xml-roles:note`	`AXGroup` `AXDocumentNote` `'note'`
`option` If `aria-selected` (state) is undefined treat as `aria-selected = "false"`.	`ROLE_SYSTEM_LISTITEM`	`ROLE_SYSTEM_LISTITEM` IAccessible2: If `aria-checked` (state) is not undefined, support object attribute `checkable:true`	`ListItem` + `Invoke` pattern	`ROLE_LIST_ITEM` If `aria-checked` (state) is not undefined, support object attribute `checkable:true` Special case: if an `option` has a parent that was exposed as a `ROLE_MENU`, the `option` SHOULD be exposed as an `ROLE_MENU_ITEM`	`AXStaticText` `<nil>` `'text'`
`presentation`	See General rules for exposing WAI-ARIA semantics	If the object is in the accessibility tree, expose as `ROLE_SYSTEM_PANE` See General rules for exposing WAI-ARIA semantics	If the object is in the accessibility tree, expose as `Pane` See General rules for exposing WAI-ARIA semantics	If the object is in the accessibility tree, expose as `ROLE_PANEL` See General rules for exposing WAI-ARIA semantics	Not mapped See General rules for exposing WAI-ARIA semantics
`progressbar`	`ROLE_SYSTEM_PROGRESSBAR` + `STATE_SYSTEM_READONLY`	`ROLE_SYSTEM_PROGRESSBAR` + `STATE_SYSTEM_READONLY`	`ProgressBar` If any of the `aria-valuenow`, `aria-valuemax`, or `aria-valuemin` properties are present, also implement the `RangeValue` pattern.	`ROLE_PROGRESS_BAR` + do not expose `STATE_EDITABLE`	`AXProgressIndicator` `<nil>` `'progress indicator'`
`radio`	`ROLE_SYSTEM_RADIOBUTTON` See "Special case" under `aria-checked` for mapping `aria-checked` (state) attribute for radio buttons.	`ROLE_SYSTEM_RADIOBUTTON`	`RadioButton`	`ROLE_RADIO_BUTTON`	`AXRadioButton` `<nil>` `'radio button'`
`radiogroup`	`ROLE_SYSTEM_GROUPING`	`ROLE_SYSTEM_GROUPING`	`List`	`ROLE_PANEL`	`AXRadioGroup` `<nil>` `'radio group'`
`region`	`ROLE_SYSTEM_PANE`	`ROLE_SYSTEM_PANE`	`Pane`	`ROLE_PANEL`	`AXGroup` `AXDocumentRegion` `'region'`
`row`	`ROLE_SYSTEM_ROW` unless inside a `tree` or `treegrid`, in which case `ROLE_SYSTEM_OUTLINEITEM`	`ROLE_SYSTEM_ROW` unless inside a `tree` or `treegrid`, in which case `ROLE_SYSTEM_OUTLINEITEM` IAccessible2: Used to help support: `IAccessibleTable2` interface for the container `grid` role	`DataItem` Also requires `selectionitem` pattern	`ROLE_LIST_ITEM`	`AXRow` `<nil>` `'row'`
`rowgroup`	Expose as text string in `AriaRole` Note: the `rowgroup` role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.	`ROLE_SYSTEM_GROUP` Note: the `rowgroup` role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.	`group` Note: the `rowgroup` role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.	`ROLE_PANEL` Note: the `rowgroup` role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.	Not mapped Note: the `rowgroup` role exists to support role symmetry in HTML, and allows for the propagation of presentation inheritance on tables with an explicit presentation role applied.
`rowheader`	`ROLE_SYSTEM_ROWHEADER`	`ROLE_SYSTEM_ROWHEADER` IAccessible2: Used to help support `IAccessibleTable2` interface for the container `grid` role	`HeaderItem`	`ROLE_ROW_HEADER`	`AXCell` `<nil>` `'cell`' Parent table also implements `AXRowHeaderUIElements` property that is a list of pointers to the row header cells
`scrollbar`	`ROLE_SYSTEM_SCROLLBAR`	`ROLE_SYSTEM_SCROLLBAR`	`scrollbar`	`ROLE_SCROLLBAR`	`AXScrollBar` `<nil>` `'scroll bar'`
`search`	Expose as text string in `AriaRole`		Expose as text string in `AriaRole`	Object attribute `xml-roles:search`	`AXGroup` `AXLandmarkSearch` `'search'`
`separator`	`ROLE_SYSTEM_SEPARATOR`	`ROLE_SYSTEM_SEPARATOR`	`Separator`	`ROLE_SEPARATOR`	`AXSplitter` `<nil>` `'splitter'`
`slider`	`ROLE_SYSTEM_SLIDER`	`ROLE_SYSTEM_SLIDER`	`Slider`	`ROLE_SLIDER`	`AXSlider` `<nil>` `'slider'`
`spinbutton`	`ROLE_SYSTEM_SPINBUTTON`	`ROLE_SYSTEM_SPINBUTTON`	`Spinner`	`ROLE_SPIN_BUTTON`	`AXIncrementor` `<nil>` `'stepper'`
`status`	`ROLE_SYSTEM_STATUSBAR`	`ROLE_SYSTEM_STATUSBAR` + IAccessible2: object attributes `container-live:polite;live:polite;container-live-role:status`	`StatusBar`	`ROLE_STATUSBAR` + object attributes `container-live:polite;live:polite;container-live-role:status`	`AXGroup` `AXApplicationStatus` `'status'`
`tab` If `aria-selected` (state) is undefined treat as `aria-selected = "false"`.	`ROLE_SYSTEM_PAGETAB`. Expose `SELECTED` state if focus is inside `tabpanel` associated with `aria-labelledby`.	`ROLE_SYSTEM_PAGETAB`. Expose `SELECTED` state if focus is inside `tabpanel` associated with `aria-labelledby`.	`TabItem`	`ROLE_PAGE_TAB`. Expose `SELECTED` state if focus is inside `tabpanel` associated with `aria-labelledby`.	`AXRadioButton` `<nil>` `'tab'`
`tablist`	`ROLE_SYSTEM_PAGETABLIST`	`ROLE_SYSTEM_PAGETABLIST` + IAccessible2: object attributes `container-live:polite;live:polite;container-live-role:tablist`	`Tab` Also requires `selection` pattern	`ROLE_PAGE_TAB_LIST` + object attributes `container-live:polite;live:polite;container-live-role:tablist`	`AXTabGroup` `<nil>` `'tabgroup'`
`tabpanel`	`ROLE_SYSTEM_PANE` or `ROLE_SYSTEM_PROPERTYPAGE`	`ROLE_SYSTEM_PANE` or `ROLE_SYSTEM_PROPERTYPAGE`	`Pane`	`ROLE_SCROLL_PANE`	`AXGroup` `TabPanel` `'tab panel'`
`textbox`	`ROLE_SYSTEM_TEXT`	`ROLE_SYSTEM_TEXT` `IAccessible2: IA2_STATE_SINGLE_LINE` if `aria-multiline` is not `"true"`	`Edit`	`ROLE_ENTRY` + `STATE_SINGLE_LINE` if `aria-multiline` is not `"true"`	If `aria-multiline="false"` (default) use: `AXTextField` `<nil>` `'text field`' If `aria-multiline="true"` use: `AXTextArea` `<nil>` `'text entry area`'
`timer`	Expose as text string in `AriaRole`	IAccessible2: Object attribute `xml-roles:timer;container-live:off;live:off;container-live-role:timer`	Expose as text string in `AriaRole`	`ROLE_UNKNOWN` + object attributes `container-live:off;live:off;container-live-role:timer`	`AXGroup` `AXApplicationTimer` `'timer'`
`toolbar`	`ROLE_SYSTEM_TOOLBAR`	`ROLE_SYSTEM_TOOLBAR`	`ToolBar`	`ROLE_TOOL_BAR`	`AXToolbar` `<nil>` `'toolbar'`
`tooltip`	`ROLE_SYSTEM_TOOLTIP`	`ROLE_SYSTEM_TOOLTIP`	`ToolTip`	`ROLE_TOOL_TIP`	`AXGroup` `AXUserInterfaceTooltip` `'tooltip'`
`tree`	`ROLE_SYSTEM_OUTLINE`	`ROLE_SYSTEM_OUTLINE`	`Tree`	`ROLE_TREE`	`AXOutline` `<nil>` `'outline'`
`treegrid`	`DataGrid`	`ROLE_SYSTEM_OUTLINE` IAccessible2: Use `IAccessibleTable2` interface Object attribute `xml-roles:treegrid`	`DataGrid`	`ROLE_TREE_TABLE`	`AXTable` `<nil>` `'table'`
`treeitem`	`TreeItem`	`ROLE_SYSTEM_OUTLINEITEM` IAccessible2: If `aria-checked` (state) is not undefined, support object attribute `checkable:true`	`TreeItem`	`ROLE_LIST_ITEM` + if `aria-checked` is not undefined, support object attribute `checkable:true`	`AXRow` `AXOutlineRow` `'outline row'`

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

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

5.5. State and Property Mapping

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

User agents MUST compute managed states VISIBLE/INVISIBLE, SHOWING/OFFSCREEN, etc. This typically is done in the same way as for ordinary elements that do not have WAI-ARIA attributes present. The FOCUSABLE/FOCUSED states may be affected by aria-activedescendant. See the rules in Controlling focus with aria-activedescendant.
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.
User agents MUST expose additional states for certain roles as defined in the Role Mapping Table.
User agents MUST compute states for the relevant WAI-ARIA attributes and map to the accessibility API as specified in the State and Property Mapping Table. To determine the relevant WAI-ARIA attributes, refer to the Definition of Roles [ARIA]. Where the author has not provided values for required attributes, user agents SHOULD process as if the default value as indicated in column 1 was provided.
For forward compatibility with new WAI-ARIA properties in future versions, user agents SHOULD expose all properties not in the table below as a text string, removing the "aria-" prefix from the name, if the API supports it. For example, aria-foo="bar" would be exposed with a text string foo=bar in UIA, since aria-foo is not a currently known WAI-ARIA property. The following list specifies the accessibility APIs for exposing properties as text strings.
- MSAA: not supported
- IAccessible2: expose as an object attribute pair ( property:string)
- UIA: expose an object attribute pair in AriaProperties (property=string)
- ATK/AT-SPI: expose as an object attribute pair (property:string)
Some WAI-ARIA properties are not global, and are only supported on certain roles. If a non-global WAI-ARIA state or property is used where it is not supported, user agents SHOULD NOT map the given WAI-ARIA property to the platform accessibility API. For example, if aria-checked="true" is specified on <div role="grid">, it should not be exposed in MSAA implementations as STATE_SYSTEM_CHECKED. User agents MAY expose non-relevant attributes as a text string if the API supports it as described above.
When an explicit or inherited role of presentation is applied to an element, the user agent MUST implement the rules for presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [ARIA].

5.5.1. State and Property Mapping Table

5.5.1.1. Not Mapped

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

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

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

WAI-ARIA state and property mapping rule table
WAI-ARIA State or Property	MSAA + UIA Express	MSAA + IAccessible2	UIA	ATK/AT-SPI	Mac OS X
`aria-activedescendant`	See Controlling focus with `aria-activedescendant`, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations. In cases, however, the focus can be transparent in an accessibility tree as it may be exposed as focus delegation from the container element to the child object that takes active focus. This is represented by an accessible object that comes with `STATE_SYSTEM_FOCUSED` state. When this happens, standard focus event and event handling should apply.	See Controlling focus with `aria-activedescendant`, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations. In cases, however, the focus can be transparent in an accessibility tree as it may be exposed as focus delegation from the container element to the child object that takes active focus. This is represented by an accessible object that comes with `STATE_SYSTEM_FOCUSED` state. When this happens, standard focus event and event handling should apply.	See Controlling focus with `aria-activedescendant`, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations.	See Controlling focus with `aria-activedescendant`, Handling focus changes from the Assistive Technology, and ID Reference Error Processing in Relations. In cases, however, the focus can be transparent in an accessibility tree as it may be exposed as focus delegation from the container element to the child object that takes active focus. This is represented by an accessible object that comes with `STATE_FOCUSED` state. When this happens, standard focus event and event handling should apply.	`array AXSelectedRows` contains pointer to active descendant node
`aria-atomic="true"`	Expose `atomic=true` in `AriaProperties`	IAccessible2: Expose as object attribute `atomic:true` and `container-atomic:true` Expose as object attribute `container-atomic:true` on all descendants as well as `IA2_RELATION_MEMBER_OF` pointing to this element (the atomic root) as described in Changes to document content or node visibility.	Expose `atomic=true` in `AriaProperties`	Expose as object attribute `atomic:true` and `container-atomic:true`. Expose object attribute `container-atomic:true` on all descendants as well as `RELATION_MEMBER_OF` pointing to this element (the atomic root) as described in Changes to document content or node visibility.	`boolean AXARIAAtomic: YES`
`aria-atomic="false"` (default)	Expose `atomic=false` in `AriaProperties`	IAccessible2: Not mapped* — OPTIONAL — but if mapped: Expose as object attribute `atomic:false` and `container-atomic:false` Expose as object attribute `container-atomic:false` on all descendants as well as `IA2_RELATION_MEMBER_OF` pointing to this element (the atomic root) as described in Changes to document content or node visibility.	Expose `atomic=false` in `AriaProperties`	Not mapped* — OPTIONAL — but if mapped: Expose as object attribute `atomic:false` and `container-atomic:false`. Expose object attribute `container-atomic:false` on all descendants as well as `RELATION_MEMBER_OF` pointing to this element (the atomic root) as described in Changes to document content or node visibility.	`boolean AXARIAAtomic: NO`
`aria-autocomplete="inline"`, `"list"`, or `"both"`	Expose `autocomplete=<value>` in `AriaProperties`	IAccessible2: Object attribute `autocomplete:<value>` Expose the `IA2_STATE_SUPPORTS_AUTOCOMPLETION` equivalent state	Expose `autocomplete=<value>` in `AriaProperties`	Object attribute `autocomplete:<value>` Expose the `SUPPORTS_AUTOCOMPLETION` equivalent state	Not mapped
`aria-autocomplete="none"` (default)	Not mapped*	Not mapped*	Not mapped*	Not mapped*	Not mapped*
`aria-busy="true"` (state)	Expose the `STATE_SYSTEM_BUSY` state	Expose the `STATE_SYSTEM_BUSY` state	Expose `busy=true` in `AriaProperties`	Expose the `STATE_BUSY` state	`boolean AXARIABusy: YES`
`aria-busy="false"` (state) (default)	Clear the `STATE_SYSTEM_BUSY` state	Clear the `STATE_SYSTEM_BUSY` state	Expose `busy=false` in `AriaProperties`	Clear the `STATE_BUSY` state	`boolean AXARIABusy: NO`
`aria-checked="true"` (state)	Expose as `ToggleState` property in `Toggle` Control Pattern. `Toggle.ToggleState = On (1)` Special case: For `menuitemradio` and `radio`, expose as `IsSelected` property in `SelectionItem` Control Pattern. `SelectionItem.IsSelected = On (1)`	Set the `STATE_SYSTEM_CHECKED` state IAccessible2: Expose object attribute `checkable:true`	Expose as `ToggleState` property in `Toggle` Control Pattern. `Toggle.ToggleState = On (1)`	Expose object attribute `checkable:true` Set the `STATE_CHECKED` state	`AXValue: 1`
`aria-checked="false"` (state)	Expose as `ToggleState` property in `Toggle` Control Pattern. `Toggle.ToggleState = Off (0)` Special case: For `menuitemradio` and `radio`, expose as `IsSelected` property in `SelectionItem` Control Pattern. `SelectionItem.IsSelected = Off (0)`	Clear the `STATE_SYSTEM_CHECKED` state IAccessible2: Expose object attribute `checkable:true`	Expose as `ToggleState` property in `Toggle` Control Pattern. `Toggle.ToggleState = Off (0)`	Clear the `STATE_CHECKED` state Expose object attribute `checkable:true`	`AXValue: 0`
`aria-checked="mixed"` (state) Treat as `"false"` for `radio` and `menuitemradio` roles.	Expose as `ToggleState` property in `Toggle` Control Pattern. Set the `STATE_SYSTEM_MIXED` state `Toggle.ToggleState = Indeterminate (2)`	Set the `STATE_SYSTEM_MIXED` state IAccessible2: Expose object attribute `checkable:true`	Expose as `ToggleState` property in `Toggle` Control Pattern. `Toggle.ToggleState = Indeterminate (2)`	Expose `STATE_INDETERMINATE`, unless on a role of `radio` or `menuitemradio` (in those cases treat as `"false"`) Expose object attribute `checkable:true`	`AXValue: 2`
`aria-checked` is undefined (state) Treat as `"false"` for `checkbox`, `menuitemcheckbox`, `radio` and `menuitemradio` roles.	Not mapped	Not mapped	Not mapped	Not mapped	Not mapped
`aria-controls`	Expose pointer to the accessible object `ControllerFor` property	IAccessible2: Expose pointer to the accessible object in `IA2_RELATION_CONTROLLER_FOR` Expose reverse relations as described in Relations.	Expose pointer to the accessible object `ControllerFor` property	Expose pointer to the accessible object `RELATION_CONTROLLER_FOR` Expose reverse relations as described in Relations.	`array AXLinkedUIElements` contains pointers to nodes matching IDREFs
`aria-describedby`	Use in calculating the accessible Description as described in Name Computation. Expose in `accDescription` property.	Use in calculating the accessible Description as described in Name Computation. Expose in `accDescription` property. IAccessible2: If the referenced object is in the accessibility tree, expose pointer to it in `IA2_RELATION_DESCRIBED_BY` and expose reverse relations as described in Relations.	Use in calculating the accessible Description as described in Name Computation. If the referenced object is in the accessibility tree, expose pointer to the referenced accessible object in `DescribedBy` property.	Use in calculating the accessible Description as described in Name Computation. Expose in the description property of the accessible object. If the referenced object is in the accessibility tree, expose reverse relations as described in Relations.	Use in calculating the accessible description as described in Name Computation and expose value as `string AXHelp`.
`aria-disabled="true"` (state)	Set `IsEnabled` to `"false"`	Set `STATE_SYSTEM_UNAVAILABLE` Propagate to all descendants of the element with `STATE_SYSTEM_FOCUSABLE`	Set `IsEnabled` to `"false"`	Not mapped	`boolean AXEnabled: NO`
`aria-disabled="false"` (state) (default)	Set `IsEnabled` to `"true"`	Clear `STATE_SYSTEM_UNAVAILABLE`	Set `IsEnabled` to `"true"`	Expose `STATE_ENABLED`	`boolean AXEnabled: YES`
`aria-dropeffect="copy"`, `"move"`, `"link"`, `"execute"`, or `"popup"` (state)	Expose `dropeffect=<value>` in `AriaProperties`	IAccessible2: Expose as object attribute `dropeffect:<value>`	Expose `dropeffect=<value>` in `AriaProperties`	Expose as object attribute `dropeffect:<value>`	`array AXDropEffects`
`aria-dropeffect="none"` (state) (default)	Not mapped*	IAccessible2: Expose as object attribute `dropeffect:none` if there are no other valid tokens. Not mapped if not specified by the author.	Not mapped*	Expose as object attribute `dropeffect:none` if there are no other valid tokens. Not mapped if not specified by the author.	Not mapped*
`aria-expanded="true"` (state)	Expose as `"expanded"` in `ExpandCollapseState` property of `ExpandCollapse` Control Pattern	Set `STATE_SYSTEM_EXPANDED`	Expose as `"expanded"` in `ExpandCollapseState` property of `ExpandCollapse` Control Pattern	Expose `STATE_EXPANDABLE` and `STATE_EXPANDED`	`boolean AXExpanded: YES`
`aria-expanded="false"` (state)	Expose as `"collapsed"` in `ExpandCollapseState` property of `ExpandCollapse` Control Pattern	Set `STATE_SYSTEM_COLLAPSED`	Expose as `"collapsed"` in `ExpandCollapseState` property of `ExpandCollapse` Control Pattern	Expose `STATE_EXPANDABLE`	`boolean AXExpanded: NO`
`aria-expanded` is undefined (state) (default)	Not mapped	Not mapped	Not mapped	Not mapped	Not mapped
`aria-flowto`	Expose a reference to the accessible object in `FlowsTo` property	IAccessible2: Expose reference to the accessible object in `IA2_RELATION_FLOW_TO` Expose reverse relations as described in Relations.	Expose a reference to the accessible object in `FlowsTo` property	Expose reference to the accessible object in `RELATION_FLOWS_TO` Expose reverse relations as described in Relations.	`array AXLinkedUIElements` contains pointer to nodes matching IDREFs
`aria-grabbed="true"`(state)	Expose as `grabbed=true` in `AriaProperties`	IAccessible2: Object attribute `grabbed:true`	Expose as `grabbed=true` in `AriaProperties`	Object attribute `grabbed:true`	`boolean AXGrabbed: YES`
`aria-grabbed="false"`(state)	Expose as `grabbed=false` in `AriaProperties`	IAccessible2: Object attribute `grabbed:false`	Expose as `grabbed=false` in `AriaProperties`	Object attribute `grabbed:false`	`boolean AXGrabbed: NO`
`aria-grabbed` is undefined (state) (default)	Not mapped	Not mapped	Not mapped	Not mapped	Not mapped
`aria-haspopup="true"` (default for role `combobox`)	Expose as `STATE_SYSTEM_HASPOPUP`. If on a push button, change the role to `ROLE_SYSTEM_BUTTONMENU`.	Expose as `STATE_SYSTEM_HASPOPUP`. If on a push button, change the role to `ROLE_SYSTEM_BUTTONMENU`.	Expose state of the pop-up activities as `"expanded"` or `"collapsed"` in the `ExpandCollapseState` property in the `ExpandCollapse` Control Pattern.	Object attribute `haspopup:true`	Expose `AXShowMenu` and `AXPress` actions
`aria-haspopup="false"` (default)	Clear the `HASPOPUP` state. If specified on a push button, change the role to `ROLE_SYSTEM_BUTTONMENU`	Clear the `HASPOPUP` state. If specified on a push button, change the role to `ROLE_SYSTEM_BUTTONMENU`	Not mapped*	Not mapped*	Not mapped*
`aria-hidden="true"` (state)	See Including Elements in the Accessibility Tree. If the object is in the accessibility tree, map all attributes as normal.	See Including Elements in the Accessibility Tree. If the object is in the accessibility tree, map all attributes as normal. IAccessible2: Expose object attribute `hidden:true`.	Expose as `hidden=true` in `AriaProperties`	See Including Elements in the Accessibility Tree. If the object is in the accessibility tree, map all attributes as normal. In addition, expose object attribute `hidden:true`.	Not exposed in `AX` API unless focused. If focused, expose as normal.
`aria-hidden="false"` (state) (default)	Not mapped	Not mapped	Not mapped	Not mapped	Not mapped
`aria-invalid="true"`, `"spelling"`, or `"grammar"` (state)	If `aria-invalid="true"`, expose `false` in `IsDataValidForForm` property, Otherwise expose `<value>` in `IsDataValidForForm` property	IAccessible2: Set `IA2_STATE_INVALID_ENTRY` Expose the value as a text attribute (not object attribute).	If `aria-invalid="true"`, expose `false` in `IsDataValidForForm` property, Otherwise expose `<value>` in `IsDataValidForForm` property	Set `STATE_INVALID_ENTRY` Expose the value as a text attribute (not object attribute).	`AXInvalid: <value>`
`aria-invalid=<unknown value>`	Expose `<value>` in `IsDataValidForForm` property	IAccessible2: Set `IA2_STATE_INVALID_ENTRY` Expose the value as a text attribute (not object attribute).	Expose `<value>` in `IsDataValidForForm` property	Set `STATE_INVALID_ENTRY` Expose the value as a text attribute (not object attribute).	`AXInvalid: <value>`
`aria-invalid="false"` (state) (default)	Expose `true` in `IsDataValidForForm` property	IAccessible2: Clear `IA2_STATE_INVALID_ENTRY` or equivalent state.	Expose `true` in `IsDataValidForForm` property	Not mapped*	`AXInvalid: "false"`
`aria-invalid=""` (state) (default)	Expose `true` in `IsDataValidForForm` property	IAccessible2: Clear `IA2_STATE_INVALID_ENTRY` or equivalent state.	Expose `true` in `IsDataValidForForm` property	Not mapped*	`AXInvalid: "false"`
`aria-label`	Use in calculating the accessible name as described in Name Computation. Expose in `accName` property.	Use in calculating the accessible name as described in Name Computation. Expose in `accName` property.	Use in calculating the accessible name as described in Name Computation. Expose in `Name` property.	Use in calculating the accessible name as described in Name Computation. Expose in the name property of the accessible object.	Calculate accessible name as described in Name Computation and expose value as `string AXDescription`. Note: `AXDescription` is recommended for accessible name values that are not exposed visually, such as `@alt` and `@aria-label`. Accessible name values that are exposed visually, as in the case of a button, should be exposed as string `AXTitle`. For example, with `<input type="button" value="Feb" aria-label="February">`, expose both `AXTitle:"Feb"` and `AXDescription:"February"`.
`aria-labelledby`	Use in calculating the accessible name as described in Name Computation. Expose in `accName` property.	Use in calculating the accessible name as described in Name Computation. Expose in `accName` property. IAccessible2: If the referenced object is in the accessibility tree expose a pointer to it in `IA2_RELATION_LABELLED_BY` and expose reverse relations as described in Relations.	Use in calculating the accessible name as described in Name Computation. Expose in `Name` property. If the referenced object is in the accessibility tree, expose a pointer to it in the `LabeledBy` property.	Use in calculating the accessible name as described in Name Computation. Expose in the name property of the accessible object. If the referenced object is in the accessibility tree, expose a pointer to it in `RELATION_LABELLED_BY` and expose reverse relations as described in Relations.	If `aria-labelledby` references a single element, expose the labeling relationship as element `AXTitleUIElement`. If `aria-labelledby` references multiple elements, or if the labeling element is invisible or otherwise not exposed in the accessibility tree, use in calculating the accessible name as described in Name Computation and expose value as `string AXDescription`.
`aria-level`	Expose as `level=<value>` in `AriaProperites`.	IAccessible2: Expose as object attribute `level:<value>`. If the role supports `aria-posinset` and `aria-setsize`, expose in `groupPosition()`. May affect `RELATION_NODE_CHILD_OF` when used on a tree item. See section Group Position.	Expose as `level=<value>` in `AriaProperites`.	Expose as object attribute `level:<value>`	When used on a `heading`, map to `AXValue`. When used on an outline row (like a `treeitem` or `group`), map to `AXDisclosureLevel.`
`aria-live="assertive"` (default for role `alert`)	Set `LiveSetting` Property to "assertive"	IAccessible2: Expose as object attribute `live:assertive` and `container-live:assertive`. Expose as object attribute `container-live:assertive` on all descendants as described in Changes to document content or node visibility.	Set `LiveSetting` Property to "assertive"	Expose as object attribute `live:assertive` and `container-live:assertive`. Expose as object attribute `container-live:assertive` on all descendants as described in Changes to document content or node visibility.	`AXARIALive: "assertive"`
`aria-live="polite"` (default for role types `log` and `status`)	Set `LiveSetting` Property to "polite"	IAccessible2: Expose as object attribute `live:polite` and `container-live:polite` Expose as object attribute `container-live:polite` on all descendants as described in Changes to document content or node visibility.	Set `LiveSetting` Property to "polite"	Expose as object attribute `live:polite` and `container-live:polite`. Expose as object attribute `container-live:polite` on all descendants as described in Changes to document content or node visibility.	`AXARIALive: "polite"`
`aria-live="off"` (default)	Set `LiveSetting` property to "off"	IAccessible2: Expose as object attribute `live:off` and `container-live:off` Expose as object attribute `container-live:off` on all descendants as described in Changes to document content or node visibility.	Set `LiveSetting` property to "off"	Expose as object attribute `live:off` and `container-live:off`. Expose as object attribute `container-live:off` on all descendants as described in Changes to document content or node visibility.	`AXARIALive: "off"`
`aria-multiline="true"`	Expose as `multiline=true` in `AriaProperties`	IAccessible2: Set the `IA2_MULTI_LINE` state and clear `IA2_SINGLE_LINE`	Expose as `multiline=true` in `AriaProperties`	Set `STATE_MULTI_LINE` and clear `STATE_SINGLE_LINE`	Not mapped See `textbox` in the Role Mapping Table for more information.
`aria-multiline="false"` (default)	Not mapped*	IAccessible2: Clear the `IA2_MULTI_LINE` state, and set `IA2_SINGLE_LINE`	Not mapped*	Set `STATE_SINGLE_LINE` and clear `STATE_MULTI_LINE`	Not mapped See `textbox` in the Role Mapping Table for more information.
`aria-multiselectable="true"`	Set `CanSelectMultiple` property on the `Selection` Control Pattern. See Selection for details.	Set the `STATE_SYSTEM_MULTISELECTABLE` state. Expose `STATE_SYSTEM_EXTSELECTABLE` to exactly match `STATE_SYSTEM_MULTISELECTABLE`. IAccessible2: For text elements, support the selection methods defined on the `IAccessibleText` interface See Selection for details.	Set `CanSelectMultiple` property on the `Selection` Control Pattern. See Selection for details.	Expose `STATE_MULTISELECTABLE` See Selection for details.	Not mapped See Selection for details.
`aria-multiselectable="false"` (default)	Not mapped*	Clear the `STATE_SYSTEM_MULTISELECTABLE` state. Expose `STATE_SYSTEM_EXTSELECTABLE` to exactly match `STATE_SYSTEM_MULTISELECTABLE`. See Selection for details.	Not mapped*	Not mapped*	Not mapped*
`aria-orientation="horizontal"` (default)	Set `Orientation` property to "horizontal"	IAccessible2: Set: `IA2_STATE_HORIZONTAL` Clear: `IA2_STATE_VERTICAL`	Set `Orientation` property to "horizontal"	Set `STATE_HORIZONTAL`	`AXOrientation: AXHorizontalOrientation`
`aria-orientation="vertical"` (default for role `scrollbar`)	Set `Orientation` Property to "vertical"	IAccessible2: Set: `IA2_STATE_VERTICAL` Clear: `IA2_STATE_HORIZONTAL`	Set `Orientation` Property to "vertical"	Set `STATE_VERTICAL`	`AXOrientation: AXVerticalOrientation`
`aria-owns`	The structure should be reflected in the accessibility tree as directed by `aria-owns`. Map the elements that are referenced by this property as children of the current element. If multiple `aria-owns` relationships are found, use only the first one.	The accessibility tree is not modified. IAccessible2: Expose reverse relations as described in Relations If multiple `aria-owns` relationships are found, use only the first one.	The structure should be reflected in the accessibility tree as directed by `aria-owns`. Map the elements that are referenced by this property as children of the current element. If multiple `aria-owns` relationships are found, use only the first one.	Expose reverse relations as described in Relations If multiple `aria-owns` relationships are found, use only the first one.	`array AXLinkedUIElements` contains pointer to nodes matching IDREFs
`aria-posinset` If not provided for relevant roles, user agents calculate `aria-setsize` and `aria-posinset` for each object in the container based on the number of objects in the DOM.	Expose as `posinset=<value>` in `AriaProperties`. Additionally, user agents MAY update the `LegacyIAccessible.Description` property to take the form X of Y, where X is the `aria-posinset` value and Y is the `aria-setsize` value; and if X is less than one, or if X is greater than Y, `LegacyIAccessible.Description` will be empty.	IAccessible2: Expose as object attribute `posinset:<value>` and in `groupPosition()`.	Expose as `posinset=<value>` in `AriaProperties`.	Expose as object attribute `posinset:<value>`.	`AXARIAPosInSet: <value>`
`aria-pressed="true"` (state)	Expose as `ToggleState property` of `Toggle` Control Pattern `Toggle.ToggleState = On (1)`	Set the `STATE_SYSTEM_PRESSED` state. IAccessible2: If on a button, expose the role as `IA2_ROLE_TOGGLE_BUTTON` Expose object attribute `checkable:true`	Expose as `ToggleState property` of `Toggle` Control Pattern `Toggle.ToggleState = On (1)`	Expose `STATE_PRESSED`. If on a button, expose the role as `ROLE_TOGGLE_BUTTON`. Expose object attribute `checkable:true`	AXValue: 1
`aria-pressed="mixed"` (state)	Expose as `ToggleState` property of `Toggle` Control Pattern `Toggle.ToggleState = Indeterminate (2)`	Set the `STATE_SYSTEM_PRESSED` state. IAccessible2: If on a button, expose the role as `IA2_ROLE_TOGGLE_BUTTON` Expose object attribute `checkable:true`	Expose as `ToggleState` property of `Toggle` Control Pattern `Toggle.ToggleState = Indeterminate (2)`	Expose `STATE_INDETERMINATE`/`STATE_SYSTEM_MIXED`. If on a button, expose the role as `ROLE_TOGGLE_BUTTON`. Expose object attribute `checkable:true`	AXValue: 2
`aria-pressed="false"` (state)	Expose as `ToggleState` property of `Toggle` Control Pattern `Toggle.ToggleState = Off (3)`	Clear the `STATE_SYSTEM_PRESSED` state IAccessible2: If on a button, expose the role as `IA2_ROLE_TOGGLE_BUTTON` Expose object attribute `checkable:true`	Expose as `ToggleState` property of `Toggle` Control Pattern `Toggle.ToggleState = Off (3)`	If on a button, expose the role as `ROLE_TOGGLE_BUTTON`. Expose object attribute `checkable:true`	AXValue: 0
`aria-pressed` is undefined (state) (default)	Not mapped*	Not mapped*	Not mapped*	Not mapped*	Not mapped*
`aria-readonly="true"`	Expose as `STATE_SYSTEM_READONLY`	Expose as `STATE_SYSTEM_READONLY`	Set `Value.IsReadOnly="true"`	No mapping	`AXValue` (not writable)
`aria-readonly="false"` (default)	Not mapped	IAccessible2: Expose `IA2_STATE_EDITABLE`	Set `Value.IsReadOnly="false"`	Expose `STATE_EDITABLE`	`AXValue` (writable)
`aria-relevant="additions"`, `"removals"`, `"text"`, or `"all"`	Expose as `relevant=<value>` in `AriaProperties`	IAccessible2: Expose as object attribute `relevant:<value>` and `container-relevant:<value>` Expose as object attribute `container-relevant:<value>` on all descendants as described in Changes to document content or node visibility.	Expose as `relevant=<value>` in `AriaProperties`	Expose as object attribute `relevant:<value>` and `container-relevant:<value>`. Expose as object attribute `container-relevant:<value>` on all descendants as described in Changes to document content or node visibility.	`AXARIARelevant: <value>`
`aria-relevant="additions text"` (Default)	Expose as `relevant=additions text` in `AriaProperties`	IAccessible2: Expose as object attribute `relevant:additions text` and `container-relevant:additions text` Expose as object attribute `container-relevant:additions text` on all descendants as described in Changes to document content or node visibility.	Expose as `relevant=additions text` in `AriaProperties`	Expose as object attribute `relevant:additions text` and `container-relevant:additions text`. Expose as object attribute `container-relevant:additions text` on all descendants as described in Changes to document content or node visibility	`AXARIARelevant: <value>`
`aria-required="true"`	Expose as `IsrequiredForForm` property.	IAccessible2: Expose `IA2_STATE_REQUIRED`	Expose as `IsrequiredForForm` property.	Expose `STATE_REQUIRED`	`boolean AXRequired: YES`
`aria-required="false" (default)`	Not mapped*	Not mapped*	Not mapped*	Not mapped*	Not mapped*
`aria-selected="true"` (state) If role is `radio` or `menuitemradio`, mapping the value is OPTIONAL.	Expose `STATE_SYSTEM_SELECTED` Expose `STATE_SYSTEM_SELECTABLE`	Expose `STATE_SYSTEM_SELECTED` Expose `STATE_SYSTEM_SELECTABLE` IAccessible2: If not `DISABLED`, toggle between `"true"` and `"false"` as appropriate when `aria-multiselectable` is used on an ancestor as described in Selection.	Expose `IsSelected` property on `SelectionItem` Control Pattern. The availability of the `SelectionItem` Control Pattern indicates the item is selectable.	Expose `STATE_SELECTED` and `STATE_SELECTABLE`. If not `DISABLED`, toggle between `"true"` and `"false"` as appropriate when the `AccessibleSelection` interface is used on an ancestor with `aria-multiselectable` as described in Selection.	`boolean AXSelected: YES`
`aria-selected="false"` (state) If role is `radio` or `menuitemradio`, mapping the value is OPTIONAL.	Clear `STATE_SYSTEM_SELECTED` Expose `STATE_SYSTEM_SELECTABLE`	Clear `STATE_SYSTEM_SELECTED` Expose `STATE_SYSTEM_SELECTABLE` IAccessible2: If not `DISABLED`, toggle between `"true"` and `"false"` as appropriate when the `AccessibleSelection` interface is used on an ancestor with `aria-multiselectable` as described in Selection.	Not mapped	Clear `STATE_SELECTED` and expose `STATE_SELECTABLE`.	`boolean AXSelected: NO`
`aria-selected` is undefined (state) (default) If role is `option` or `tab` treat as `false`.	Not mapped	Not mapped	Not mapped	Not mapped	Not mapped
`aria-setsize` If not provided for relevant roles, user agents calculate `aria-setsize` and `aria-posinset` for each object in the container based on the number of objects in the DOM.	Expose as `setsize=<value>` in `AriaProperties` Additionally, user agents MAY update the `LegacyIAccessible.Description` property to take the form X of Y, where X is the `aria-posinset` value and Y is the `aria-setsize` value; and if X is less than one, or if X is greater than Y, `LegacyIAccessible.Description` will be empty.	IAccessible2: Expose object attribute `setsize:<value>` and `groupPosition()`.	Expose as `setsize=<value>` in `AriaProperties.`	Expose object attribute `setsize:<value>`.	`AXARIASetSize: <value>`
`aria-sort="ascending",` `"descending"`, or `"other"`	Expose as `sort=<value>` in `AriaProperties`. If on an element that maps to `HeaderItem` controls (`th` elements, and elements that include the `"columnheader"` and `"rowheader"` role), `ItemStatus="<value>"`.	IAccessible2: Expose as object attribute `sort:<value>`	Expose as `sort=<value>` in `AriaProperties.` If on an element that maps to `HeaderItem` controls (`th` elements, and elements that include the `"columnheader"` and `"rowheader"` role), `ItemStatus="<value>"`.	Expose as object attribute `sort:<value>`	`AXSortDirection: AXAscendingSortDirection \| AXDescendingSortDirection \| AXUnknownSortDirection`
`aria-sort="none"` (default)	Not mapped*	IAccessible2: If specified, expose as object attribute `sort:<value>`	Not mapped*	If specified, expose as object attribute `sort:<value>`	Not mapped*
`aria-valuemax`	Expose the `Maximum` property in `RangeValue` Control Pattern See Widget values for additional information	IAccessible2: Expose via `AccessibleValue` interface. See Widget values for additional information	Expose the `Maximum` property in `RangeValue` Control Pattern See Widget values for additional information	Expose via `AccessibleValue` interface. See Widget values for additional information	`number AXMaxValue` See Widget values for additional information
`aria-valuemin`	Expose the `Minimum` property in `RangeValue` Control Pattern See Widget values for additional information	IAccessible2: Expose via `AccessibleValue` interface See Widget values for additional information	Expose the `Minimum` property in `RangeValue` Control Pattern See Widget values for additional information	Expose via `AccessibleValue` interface See Widget values for additional information	`number AXMinValue` See Widget values for additional information
`aria-valuenow`	If `aria-valuetext` is not defined, expose via `IAccessible::get_accValue`	If `aria-valuetext` is not defined, expose via `IAccessible::get_accValue` IAccessible2: Expose via `AccessibleValue` interface. See Widget values for additional information	Expose `Value` property in `RangeValue` Control Pattern See Widget values for additional information	Expose via `AccessibleValue` interface. See Widget values for additional information	`number AXValue` See Widget values for additional information
`aria-valuetext`	Expose `Value` property in `Value` Control Pattern which can co-exist with `RangeValue` Control Pattern. See Widget values for additional information	Expose via `IAccessible::get_accValue` IAccessible2: Expose as object attribute `valuetext:<value>` See Widget values for additional information	Expose `Value` property in `Value` Control Pattern which can co-exist with `RangeValue` Control Pattern. See Widget values for additional information	Expose as object attribute `valuetext:<value>` See Widget values for additional information	`AXValueDescription: <value>` See Widget values for additional information

5.6. Special Processing Requiring Additional Computation

5.6.1. Name and Description

5.6.1.1. Name Computation

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

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

5.6.1.2. Description Computation

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

5.6.1.3. Text Alternative Computation

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

The text alternative for a given node is computed as follows:

Skip hidden elements unless the author specifies to use them via an aria-labelledby or aria-describedby being used in the current computation. By default, users of assistive technologies won't receive the hidden information, but an author will be able to explicitly override that and include the hidden text alternative as part of the label string sent to the accessibility API.
For any non-skipped elements:
1. Authors specify an element's text alternative in content attributes, used in this order of preference:
  - The aria-labelledby attribute takes precedence as the element's text alternative unless this computation is already occurring as the result of a recursive aria-labelledby declaration (in other words, aria-labelledby is not recursive when referenced from another element, so it will not cause loops). However, the element's aria-labelledby attribute can reference the element's own IDREF in order to concatenate a string provided by the element's aria-label attribute or another feature lower in this preference list. The text alternatives for all the elements referenced will be computed using this same set of rules. User agents will then trim whitespace and join the substrings using a single space character. Substrings will be joined in the order specified by the author (IDREF order in the aria-labelledby attribute).
    In the following example, the <span> elements would have text alternatives of "Delete Documentation.pdf" and "Delete HolidayLetter.pdf", respectively.
    
    <h1>Files</h1> <ul> <li> <a id="file_row1" href="./files/Documentation.pdf">Documentation.pdf</a> <span role="button" tabindex="0" id="del_row1" aria-label="Delete" aria-labelledby="del_row1 file_row1"></span> </li> <li> <a id="file_row2" href="./files/HolidayLetter.pdf">HolidayLetter.pdf</a> <span role="button" tabindex="0" id="del_row2" aria-label="Delete" aria-labelledby="del_row2 file_row2"></span> </li> </ul>
  - If aria-labelledby is empty or undefined, the aria-label attribute, which defines an explicit text string, is used. However, if this computation is already occurring as the result of a recursive text alternative computation and the current element is an embedded control as defined in rule 2B, ignore the aria-label attribute and skip directly to rule 2B.
  - If aria-labelledby and aria-label are both empty or undefined, and if the element is not marked as presentational (role="presentation", check for the presence of an equivalent host language attribute or element for associating a label, and use those mechanisms to determine a text alternative. For example, in HTML, the img element's alt attribute defines a label string and the label element references the form element it labels.
  See How to Specify Alternate Text ([HTML], section 13.8) and HTML5 Requirements for providing text to act as an alternative for images ([HTML5], section 4.8.1.1). In the case of HTML frame and iframe elements, the title element in the head element of the document inside a frame or iframe is used in this step of the calculation of the name of the frame or iframe.
  
  Editorial Note: We've asked the HTML5 WG to remove or reduce this section, so we may remove the reference to it.
2. Authors sometimes embed a control within the label of another widget, where the user can adjust the embedded control's value. For example, consider a check box label that contains a text input field: "Flash the screen [input] times". If the user has entered "5" for the embedded text input, the complete label is "Flash the screen 5 times". For such cases, include the value of the embedded control as part of the text alternative in the following manner:
  - If the embedded control is a text field, use its value.
  - If the embedded control is a menu, use the text alternative of the chosen menu item.
  - If the embedded control is a select or combobox, use the chosen option.
  - If the embedded control is a range (e.g. a spinbutton or slider), use the value of the aria-valuetext attribute if available, or otherwise the value of the aria-valuenow attribute.
  Editorial Note: This bullet of the text alternative computation is currently normative. Its status is considered a feature at risk and may be changed from a normative requirement to an informative recommendation if interoperable implementations are not found.
3. Otherwise, if the attributes checked in rules A and B didn't provide results, text is collected from descendant content if the current element's role allows "Name From: contents." The text alternatives for child nodes will be concatenated, using this same set of rules. This same rule may apply to a child, which means the computation becomes recursive and can result in text being collected in all the nodes in this subtree, no matter how deep they are. However, any given descendant subtree may instead collect their part of the text alternative from the preferred markup described in A and B above. These author-specified attributes are assumed to provide the correct text alternative for the entire subtree. All in all, the node rules are applied consistently as text alternatives are collected from descendants, and each containing element in those descendants may or may not allow their contents to be used. Each node in the subtree is consulted only once. If text has been collected from a child node, and is referenced by another IDREF in some descendant node, then that second, or subsequent, reference is not followed. This is done to avoid infinite loops.
4. The last resort is to use text from a tooltip attribute (such as the title attribute in HTML). This is used only if nothing else, including subtree content, has provided results.
Text nodes are often visited because they are children of an element that uses rule 2C to collect text from its children. However, because it is possible to specify textual content using CSS rules, it is necessary for user agents to combine such content, as appropriate, with the text referenced by the text nodes to produce a complete text alternative. An example is the use of CSS :before and :after pseudo-elements, where the user agent combines the textual content specified in the style sheet with that given in the DOM.
- When an image replaces text, then the UA should use the original text, since that text is presumably the equivalent.
- When text replaces an image, then the UA should provide that text.
- When new text replaces old, then the UA should include the new text, since that is what is rendered on screen.

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

5.6.2. Widget Values

Some WAI-ARIA roles are widgets that have a particular value within a range of values. For example progressbar, spinbutton, and slider use aria-valuemin and aria-valuemax to specify the range of valid values, aria-valuenow to specify the current value, and optionally aria-valuetext to specify a text string equivalent for the current value.

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

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

If an element has the aria-valuetext property set, but not aria-valuenow, user agents MUST expose the string value of aria-valuetext as specified in State and Property Mapping.

5.6.3. Relations

Often in a GUI, there are relationships between the widgets that can be exposed programmatically to assistive technology. WAI-ARIA provides several relationship properties which are globally applicable to any element: aria-controls, aria-describedby, aria-flowto, aria-labelledby, aria-owns, aria-posinset, and aria-setsize. Therefore, it is not important to check the role before computing them. User agents can simply map these relations to accessibility APIs as defined in the section titled State and Property Mapping.

5.6.3.1. ID Reference Error Processing

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

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

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

aria-activedescendant is defined as referencing only a single ID reference. Any aria-activedescendant value that does not match an existing IDREF exactly is an author error and will not match any element in the DOM.

5.6.3.2. Reverse Relations

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

Reverse relation mapping table
WAI-ARIA Relation	IAccessible2	ATK/AT-SPI
`aria-controls` references the element's ID	`IA2_RELATION_CONTROLLED_BY`	`RELATION_CONTROLLED_BY`
`aria-describedby` references the element's ID	`IA2_RELATION_DESCRIPTION_FOR`	`RELATION_DESCRIPTION_FOR`
`aria-flowto` references the element's ID	`IA2_RELATION_FLOW_FROM`	`RELATION_FLOW-FROM`
`aria-labelledby` references the element's ID	`IA2_RELATION_LABEL_FOR`	`RELATION_LABEL_FOR`
`aria-owns` references the element's ID	`IA2_RELATION_NODE_CHILD_OF/IA2_RELATION_NODE_PARENT_OF`	`RELATION_NODE_CHILD_OF/RELATION_NODE_PARENT_OF`

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

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

5.6.3.3. Implied reverse relations

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

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

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

In the case of aria-atomic, where reverse relations are supported by the API:

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

5.6.4. Group Position

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

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

for role="treeitem", walk the tree backward and forward until the explicit or computed level becomes less than the current item's level. Count items only if they are at the same level as the current item.
Otherwise, walk backward and forward within the DOM parent, counting items that have the same role.
Because these values are 1-based, include the current item in the computation. For aria-posinset, include the current item and other group items if they are before the current item in the DOM. For aria-setsize, add to that the number of items in the same group after the current item in the DOM.

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

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

5.7. Actions

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

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

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

5.8. Events

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

5.8.1. State and Property Change Events

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

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

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

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Table of events to be fired in each API for changes in WAI-ARIA states and properties
State or Property	MSAA + UIA Express event	MSAA + IAccessible2 event	UIA event	ATK/AT-SPIevent	Mac OS X Notification
`aria-activedescendant`	Not mapped	See Controlling focus with `aria-activedescendant` In addition: IAccessible2: `IA2_EVENT_ACTIVE_DESCENDANT_CHANGED`	See Controlling focus with `aria-activedescendant`	See Controlling focus with `aria-activedescendant`	See Controlling focus with `aria-activedescendant` In addition: `AXSelectedChildrenChanged`
`aria-busy` (state)	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	`PropertyChangedEvent`	`object:state-changed:busy`	Not mapped
`aria-checked` (state)	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	`ToggleStateProperty` as part of `toggle` pattern	`object:state-changed:checked`	`AXValueChanged`
`aria-disabled` (state)	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	Not mapped	`object:state-changed:enabled` and `object:state-changed:sensitive`	Not mapped
`aria-dropeffect` (state)	Not mapped	IAccessible2: `IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED`	Not mapped	`object:property-change`	Not mapped
`aria-expanded` (state)	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	`expand`/`collapse` pattern events	`object:state-changed:expanded`	`AXRowExpanded`, `AXRowCollapsed`, `AXRowCountChanged`
`aria-grabbed` (state)	`EVENT_OBJECT_SELECTION`	`EVENT_OBJECT_SELECTION` IAccessible2: `IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED`	Not mapped	`object:property-change`	Not mapped
`aria-hidden` (state)	`EVENT_OBJECT_HIDE`, `EVENT_OBJECT_SHOW`	IAccessible2: `IA2_EVENT_OBJECT_ATTRIBUTE_CHANGED`	`StructureChangedEvent`	`object:property-change`	`AXUIElementDestroyed`, `AXUIElementCreated`
`aria-invalid` (state)	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	Not mapped	`object:state-changed:invalid_entry`	`AXInvalidStatusChanged`
`aria-pressed` (state)	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	Not mapped	`object:state-changed:pressed`	Not mapped
`aria-readonly`	`EVENT_OBJECT_STATECHANGE`	`EVENT_OBJECT_STATECHANGE`	Not mapped	`object:state-changed:readonly`	Not mapped
`aria-required`	Not mapped	`EVENT_OBJECT_STATECHANGE`	Not mapped	`object:state-changed:required`	Not mapped
`aria-selected` (state)	See section Selection for details.
`aria-valuenow`	`EVENT_OBJECT_VALUECHANGE`	`EVENT_OBJECT_VALUECHANGE`	`ValueProperty` property change as part of `value` pattern	`object:property-change:accessible-value`	`AXValueChanged`
`aria-valuetext`	Not mapped	`EVENT_OBJECT_VALUECHANGE`	Not mapped	`object:property-change:accessible-value`	`AXValueChanged`

5.8.2. Changes to document content or node visibility

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

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Table of document change scenarios and events to be fired in each API
Scenario	MSAA + UIA Express event	MSAA + IAccessible2 event	UIA event	ATK/AT-SPI event	Mac OS X Notification
When text is removed	`EVENT_OBJECT_LIVEREGIONCHANGED`	IAccessible2: `IA2_EVENT_TEXT_REMOVED`	`EVENT_OBJECT_LIVEREGIONCHANGED`	`text_changed::delete`	If in a live region, `AXLiveRegionChanged`
When text is inserted	`EVENT_OBJECT_LIVEREGIONCHANGED`	IAccessible2: `IA2_EVENT_TEXT_INSERTED`	`EVENT_OBJECT_LIVEREGIONCHANGED`	`text_changed::insert`	If in a live region, `AXLiveRegionChanged`
When text is changed	`EVENT_OBJECT_LIVEREGIONCHANGED`	IAccessible2: `IA2_EVENT_TEXT_REMOVE` and `IA2_EVENT_TEXT_INSERTED`	`EVENT_OBJECT_LIVEREGIONCHANGED`	`text_changed::delete` and `text_changed::insert`	If in a live region, `AXLiveRegionChanged`

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

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Table of document change scenarios and events to be fired in each API
Scenario	MSAA	Microsoft UIA event	ATK/AT-SPI event	Mac OS X 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 Mac OS X, the event is AXLiveRegionChanged. This also requires the user agent to provide a unique ID in the accessibility API notification identifying the unique node being removed.

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

To expose whether a change occurred from user input:

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

Exposing additional useful information about the context of the change:

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

Additional MSAA events may be necessary:

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

5.8.3. Selection

There are two cases for selection:

Single selection
Multiple selection

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

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Scenario	MSAA	Microsoft UIA	ATK/AT-SPI	Mac OS X
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.	`AXSelectedChildrenChanged`

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

In Microsoft UIA, the Selection and SelectionItem Control Patterns expose the selection availability, state, and methods.
User agents MUST fire the following events when aria-selected changes on a descendant, as follows:

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Scenario	MSAA	Microsoft UIA	ATK/AT-SPI	Mac OS X
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.	`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.	`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.	`AXSelectedChildrenChanged`

5.8.4. Special Events for Menus

Editorial Note: This section, special events for menus, is considered a feature at risk and may be removed.

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.

Editorial Note: The Microsoft UIA column in the following table is considered a feature at risk and may be removed.

Scenario	MSAA	Microsoft UIA	Mac OS X
Menubar is currently not active, and user moves focus to the menubar from elsewhere thereby activating it. As a result, a menuitem in the menubar is focused.	Activate the menubar and fire `EVENT_SYSTEM_MENUSTART` on the accessible object for the menubar.	`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`

WAI-ARIA role	Required Attribute	Default value
`checkbox`	`aria-checked`	See `aria-checked="false"` in State and Property mapping table.
`menuitemcheckbox`	`aria-checked`
`menuitemradio`	`aria-checked`
`radio`	`aria-checked`
`combobox`	`aria-expanded`	See `aria-expanded="false"` in State and Property mapping table.
`scrollbar`	`aria-controls`	no mapping
`scrollbar`	`aria-orientation`	See `aria-orientation="vertical"` in State and Property mapping table.
`scrollbar`	`aria-valuemax`	0
`scrollbar`	`aria-valuemin`	0
`scrollbar`	`aria-valuenow`	0
`slider`	`aria-valuemax`	0
`slider`	`aria-valuemin`	0
`slider`	`aria-valuenow`	0
`spinbutton`	`aria-valuemax`	0
`spinbutton`	`aria-valuemin`	0
`spinbutton`	`aria-valuenow`	0

WAI-ARIA 1.0 User Agent Implementation Guide

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

W3C Candidate Recommendation 17 December 2013

Abstract

Status of this Document

Exit Criteria

Features at risk

Feedback

Publication Information

Table of Contents

1. Introduction

1.1. Accessibility APIs

1.2. The Accessibility Tree and the DOM Tree

2. Normative User Agent Implementation Requirements for WAI-ARIA

3. Important Terms

4. Supporting Keyboard Navigation

4.1. Focus States and Events Table

4.2. Controlling focus with tabindex

4.3. Controlling focus with aria-activedescendant

4.4. Handling focus changes from the Assistive Technology

5. Mapping WAI-ARIA to Accessibility APIs

5.1. General rules for exposing WAI-ARIA semantics

5.1.1. Excluding Elements from the Accessibility Tree

5.1.2. Including Elements in the Accessibility Tree

5.1.3. Notification of State Changes

5.2. Conflicts between native markup semantics and WAI-ARIA

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

5.4. Role mapping

5.4.1. Role Mapping Table

5.5. State and Property Mapping

5.5.1. State and Property Mapping Table

5.5.1.1. Not Mapped

5.6. Special Processing Requiring Additional Computation

5.6.1. Name and Description

5.6.1.1. Name Computation

5.6.1.2. Description Computation

5.6.1.3. Text Alternative Computation

5.6.2. Widget Values

5.6.3. Relations

5.6.3.1. ID Reference Error Processing

5.6.3.2. Reverse Relations

5.6.3.3. Implied reverse relations

5.6.4. Group Position

5.7. Actions

5.8. Events

5.8.1. State and Property Change Events

5.8.2. Changes to document content or node visibility

5.8.3. Selection

5.8.4. Special Events for Menus

6. Special Document Handling Procedures

6.1. CSS Selectors

6.2. Author Errors

7. Appendices

7.1. References

7.1.1. Normative References

7.1.2. Informative References

7.2. Acknowledgments

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

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

7.2.3. Enabling funders

4.2. Controlling focus with `tabindex`

4.3. Controlling focus with `aria-activedescendant`