WAI-ARIA 1.0 User Agent Implementation Guide

1.1. Accessibility APIs

To provide access to desktop GUI applications, assistive technologies originally used heuristic techniques to determine the meaning of the user interface and built an alternative off screen model. For example, a row of labels displayed horizontally near the top of an application window might be a menu. Labels with a border drawn around them might be buttons. Heuristic techniques are not always accurate, however, and require assistive technologies to be updated whenever the software application is updated.

A much better technique is for the software application to provide the necessary information for interoperability with assistive technology. To meet this need, platform owners have developed specialized interfaces, called accessibility APIs, which can be used to communicate accessibility information about user interfaces to assistive technologies.

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

In the case of rich Internet applications, developers use DOM APIs to manipulate objects in the DOM tree to make them behave like interactive desktop GUI applications. In order to make a Web application understandable to assistive technologies, the user agent needs to map accessibility information from the elements in the DOM tree to the Accessibility APIs of the underlying operating system or software platform throughout the lifecycle of the application. The information needed is provided when developers use WAI-ARIA to supply semantic role, state, and property information for elements. The screen reader or other assistive technology uses the semantic information exposed via the accessibility API to provide an alternative rendering of an application that is meaningful to a user.

Accessibility APIs covered by this document are:

• Microsoft Active Accessibility (MSAA)
• IAccessible2
• User Interface Automation (UIA)
• Linux Accessibility Toolkit (ATK) and Assistive Technology - Service Provider Interface (AT-SPI)
• Mac OS X Accessibility Protocol

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

1.2. The Accessible Tree and the DOM Tree

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

3.1. Controlling focus with tabindex

Note: this section is specific to HTML only.

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

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

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

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

3.2. Controlling focus with aria-activedescendant

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

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

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

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

3.3. Handling focus changes from the Assistive Technology

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

• If the would-be-focused element can take real DOM focus, the user agent MUST set the DOM focus to it.
• Otherwise, if the current element has an ID and an ancestor with the aria-activedescendant attribute present, the user agent MUST set DOM focus to that ancestor. If successful, then set aria-activedescendant on the ancestor to the ID of the current element.

4.1. General rules for exposing WAI-ARIA semantics

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

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

• is a text element
• may fire an accessible event
• has a WAI-ARIA property, relationship or feature which needs to be exposed and does not have a role of presentation directly or inherited from an owner element.
• is focusable, or has 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 it may receive focus and need to fire a focus event.
• has a role attribute but does not contain the presentation role before any other mappable role (see Role Mapping below) and does not inherit a role of presentation from an owning element. If the presentation role is used or computed, the element must still be exposed if it has a WAI-ARIA global attribute other than aria-hidden or is focusable, so that focus events can be fired (focus must never be lost).
• has one of the WAI-ARIA global attributes but does not have the aria-hidden property set to "true". Hidden elements are not exposed to assistive technology.
• has 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 does not have a role of presentation directly or inherited from an owner element.

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

• elements with role="presentation" that are not focusable or that do not have global states or properties other than aria-hidden. In the case of structural container elements that have role "presentation", such as HTML tables or lists, child elements that are required owned elements [ARIA] of the container inherit the presentation role and MUST NOT be included in the accessible tree unless they meet one of the above criteria. Note that the contents of presentational tables are DOM text elements, not child structural elements and MUST always be included in the accessible tree.
• elements with property aria-hidden="true". Hidden elements are not exposed to assistive technology.

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

• children of the following objects, which have the characteristic "Children Presentational: True":
  • button
  • img
  • math
  • progressbar
  • separator
  • slider

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

4.2. Conflicts between native markup semantics and WAI-ARIA

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

• When WAI-ARIA states and properties correspond to host language features that have the same implicit WAI-ARIA semantic, it can be particularly problematic to use the WAI-ARIA feature. If the WAI-ARIA feature and the host language feature are both provided but their values are not kept in sync, it is uncertain which one is correct. 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.
• Although host languages can also have features that have implicit WAI-ARIA semantics corresponding to roles, the above rule does not apply to roles. When a WAI-ARIA role is provided, 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. This is because values for roles do not conflict in the same way as values for states and properties, and because authors are expected to have good reason to provide a WAI-ARIA role even on elements that would not normally be re-purposed.

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

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

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

IAccessible2 and ATK use object attributes to expose semantics that are not directly supported in the APIs. Object attributes are name-value pairs that are loosely specified, and very flexible for exposing things 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 not covered are in State and Property Mapping.

In UIA, use the AriaRole and AriaProperties properties to expose semantics that are not directly supported in the control patterns.

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

4.4. Role mapping

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

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

1. The first token in the sequence of tokens in the role attribute value which matches, on case-sensitive comparison, the name of any non-abstract WAI-ARIA role MUST be used for the standard role mechanism of the accessibility API. Use the role mapping table below and apply any special case rules that are specified. When a matching role is found, user agents MUST use it to override any implicit role inferred from the host language markup in performing this mapping, unless the role requires WAI-ARIA states and properties whose attributes are explicitly forbidden on the native element by the host language. Note that this overriding does not result in any changes in the DOM, only in the accessibility API representation of the document. Also note that some WAI-ARIA roles may not make sense in the absence of author-supplied scripts but user agents MUST map them anyway.

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

   1. Use the rules of the host language to detect that an element has an attribute with attribute name of role and to identify the attribute value string for that attribute.
   2. Separate the attribute value string for that attribute into a sequence of whitespace-free substrings by separating on whitespace.
   3. Do a case-sensitive comparison of the substrings to all the names of the non-abstract WAI-ARIA roles.
   4. Use the first such substring in textual order that matches the name of a non-abstract WAI-ARIA role for the API role mapping.
2. Roles defined in the WAI-ARIA spec as "abstract" MUST NOT be mapped via the standard role mechanism of the accessibility API. The abstract roles are:
   • composite
   • input
   • landmark
   • range
   • roletype
   • section
   • sectionhead
   • select
   • widget
   • structure
   • widget
   • window
3. If the element does not have a role attribute, or if the role attribute contains no tokens matching the name of a non-abstract WAI-ARIA role, the user agent MUST fall back on normal processing of the base markup for the element with the role attribute. For example, for <table role="foo"> use the element name "table" to determine what platform accessibility API role to use. For <input type="text" role="bar">, use the platform accessibility API for a text input.
4. When an explicit or inherited role of presentation is applied to an element with the implicit semantic of a WAI-ARIA role that has required owned elements [ARIA], in addition to the element with the explicit role of presentation, the user agent MUST apply an inherited role of presentation to any owned elements that do not have an explicit role defined. User agents SHOULD NOT assign an implicit role of presentation to host language semantics, but reserve the presentation role for nodes that have an explicit or inherited role of presentation, as defined by the author.
5. The entire role string MUST be exposed as a text string if the API supports it. This allows assistive technologies to do their own additional processing of roles.
   • Microsoft Active Accessibility: not supported
   • IAccessible2: expose as an object attribute pair (role=string)
   • User Interface Automation: expose as AriaRole property. The AriaRole property can also support secondary roles using a space as a separator.
   • Accessibility Toolkit: expose as an object attribute pair (role=string)
   • Apple: expose as AXRoleDescription property (AXRoleDescription=string)

   See the Role Mapping Table below for details.

6. Platform accessibility APIs typically do not provide a vehicle to notify assistive technologies that a role has changed. Due to this and document caching, assistive technologies are unlikely to process a change in role attribute value. Authors who wish to change a role are advised by the WAI-ARIA specification to delete the associated element and its children and replace it with a new element having the appropriate role. If a role is changed, however, user agents SHOULD update the mapping in order to reflect the content in the DOM. Since assistive technologies will not know that the role has changed, a user agents MAY address this error condition by treating it as removing a subtree item and inserting a new one as described in Changes to document content or node visibility.

4.5. State and Property Mapping

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

1. Compute the states that are managed by the user agent such as VISIBLE/INVISIBLE, SHOWING/OFFSCREEN, etc. This typically is done in the same way as for ordinary elements that do not have WAI-ARIA attributes present. The FOCUSABLE/FOCUSED states may be affected by aria-activedescendant. See the rules in Controlling focus with aria-activedescendant.
2. Add in states and object attributes supported by the accessibility implementation for the base markup. Map states and properties that are supported in the API.
3. User agents SHOULD add additional information to the description, object attribute, or other text string.
4. Some roles require additional states to be exposed. Apply special case rules for the primary role as defined in the table in Role mapping.
5. Compute states for the relevant WAI-ARIA attributes. To determine the relevant WAI-ARIA attributes, refer to the Definition of Roles [ARIA]. See the table below for accessibility API mapping information. Where default values are indicated in column 1, user agents should process as if the default value was provided on roles for which that state or property is relevant.
6. For forward compatibility with new WAI-ARIA properties in future versions, user agents SHOULD expose all properties not in these tables with a text string, removing the "aria-" prefix from the name. For example, aria-foo="bar" would be exposed with a text string foo=bar, since aria-foo is not a currently known WAI-ARIA property.
7. Some WAI-ARIA properties are not global, and are only supported on certain roles. If a non-global WAI-ARIA state or property is used where it is not supported, user agents SHOULD act as if the WAI-ARIA state or property is absent, and not map the given WAI-ARIA property to the platform accessibility API. For example, aria-checked (state)="true" should not be exposed in MSAA implementations as STATE_SYSTEM_CHECKED on <div role="grid">
8. For any element with an explicit or inherited role of presentation and which is not focusable, user agents MUST ignore role-specific WAI-ARIA attributes for that element. For example, in HTML, a table element with a role of presentation will have the implicit native semantics of its tr element removed because the grid role to which the table corresponds has a required owned elements [ARIA] of row. In turn, the implicit native semantics of the th and td elements will also be removed, because the row has required owned elements of role gridcell/columnheader/rowheader, which correspond to th and td elements. The same principle applies to list elements with required owned listitem elements: ul and ol elements with a role of presentation will have the implicit semantics of their li children removed as well.
9. In UIA, the AriaProperties property directly corresponds to the WAI-ARIA attributes when an element is exposed in the accessible tree. UIA AriaProperties is a string property formatted as a one or more name and value pair, separated by a delimiter. For example, "checked=true;disabled=false". Delimiters are the equal sign ("=") and the semicolon (";"). A backslash (\) is used as an escape character when the delimiter character or a backslash appears in the value. Some states that take ID as context are not however supported by the UIA AriaProperties. Instead, UIA supports specific relations properties such as DescribedBy or LabeledBy. See UI Automation for W3C Accessible Rich Internet Applications Specification [UIA-ARIA]] for the full mapping from WAI-ARIA states to UIA properties.

   WAI-ARIA state and property mapping rule table

   WAI-ARIA State or Property	MSAA	IAccessible2 (if different from MSAA)	UI Automation	ATK	MAC Accessibility
   aria-activedescendant	See Controlling focus with aria-activedescendant and Handling focus changes from the Assistive Technology and ID Reference Error Processing in Relations. In cases, however, the focus can be transparent in an accessible 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 and Handling focus changes from the Assistive Technology and ID Reference Error Processing in Relations. In cases, however, the focus can be transparent in an accessible 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 HasKeyboardFocus state. When this happens standard focus event and event handling should apply.
   aria-atomic="true"		Expose object attribute atomic="true". In addition, expose object attribute container-atomic="true" on all descendants as well as IA2_RELATION_MEMBER_OF pointing to this element (the atomic root) as described in Changes to document content or node visibility.		Expose object attribute atomic="true". In addition, expose object attribute container-atomic="true" on all descendants as well as RELATION_MEMBER_OF pointing to this element (the atomic root) as described in Changes to document content or node visibility.
   aria-atomic="false" (default)
   aria-autocomplete="inline", "list", or "both"		Object attribute autocomplete Expose the IA2_STATE_SUPPORTS_AUTOCOMPLETION equivalent state		Object attribute autocomplete Expose the ATK_SUPPORTS_AUTOCOMPLETION equivalent state
   aria-autocomplete="none" (default)
   aria-busy (state)="true" (state)	Expose the STATE_SYSTEM_BUSY state			Expose the ATK_STATE_BUSY state
   aria-busy (state)="false" (state) (default)	Clear the STATE_SYSTEM_BUSY state			Clear the ATK_STATE_BUSY state
   aria-checked (state)="true" (state)	Set the STATE_SYSTEM_CHECKED state	Expose object attribute checkable="true"	Expose as ToggleState property in Toggle Control Pattern	Expose object attribute checkable="true"	AXValue="1"
   aria-checked (state)="false" (state)	Clear the STATE_SYSTEM_CHECKED state	Expose object attribute checkable="true"	Expose as ToggleState property in Toggle Control Pattern.	Expose object attribute checkable="true"	AXValue="0"
   aria-checked (state)="mixed" (state) Treat as "false" on radio and menuitemradio roles	Set the STATE_SYSTEM_CHECKED state	Expose object attribute checkable="true"	Expose as ToggleState property in Toggle Control Pattern.	Expose ATK_STATE_INDETERMINATE/STATE_SYSTEM_MIXED, unless on a role of radio or menuitemradio (in those cases treat as "false") Expose object attribute checkable="true"	AXValue="0.5"
   aria-checked is undefined (state)
   aria-controls		Expose pointer to the accessible object in IA2_RELATION_CONTROLLER_FOR Expose reverse relations as described in Relations.	Expose pointer to the accessible object ControllerFor property	Expose pointer to the accessible object RELATION_CONTROLLER_FOR Expose reverse relations as described in Relations.
   aria-describedby	If hidden, expose via accDescription	If not hidden, expose pointer to the accessible object in IA2_RELATION_DESCRIBED_BY Expose reverse relations as described in Relations.	Expose pointer to the accessible object in DescribedBy	Expose pointer to the accessible object in RELATION_DESCRIBED_BY Expose reverse relations as described in Relations.	Set AXDescription to text value of element found by property value
   aria-disabled (state)="true" (state)	Set STATE_SYSTEM_UNAVAILABLE Expose STATE_SYSTEM_SENSITIVE + STATE_SYSTEM_ENABLED Propagate to all descendants of the element with STATE_SYSTEM_FOCUSABLE		Set IsEnabled to "false"		Set AXEnabled to "false"
   aria-disabled (state)="false" (state) (default)	Clear STATE_SYSTEM_UNAVAILABLE		Set IsEnabled to "true"	Expose ATK_STATE_ENABLED	Set AXEnabled to "true"
   aria-dropeffect="copy", "move", "link", "execute", or "popup" (state)		Expose as object attribute "dropeffect"		Expose as object attribute "dropeffect"
   aria-dropeffect="none" (state) (default)		Expose as object attribute "dropeffect"		Expose as object attribute "dropeffect"
   aria-expanded (state)="true" (state)	Set STATE_SYSTEM_EXPANDED		Expose as ExpandCollapseState property of ExpandCollapse Control Pattern	Expose ATK_STATE_EXPANDABLE and ATK_STATE_EXPANDED
   aria-expanded (state)="false" (state)	Set STATE_SYSTEM_COLLAPSED		Expose as ExpandCollapseState property of ExpandCollapse Control Pattern	Expose ATK_STATE_EXPANDABLE
   aria-expanded is undefined (state) (default)
   aria-flowto		Expose reference to the accessible object in IA2_RELATION_FLOW_TO Expose reverse relations as described in Relations.	Expose a reference to the accessible object in FlowsTo property	Expose reference to the accessible object in RELATION_FLOW_TO Expose reverse relations as described in Relations.
   aria-grabbed (state)="true" or "false"		Object attribute grabbed="true"		Object attribute grabbed="true"
   aria-grabbed is undefined (default)		Object attribute grabbed="false"		Object attribute grabbed="false"
   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 state of the pop-up activities in the ExpandCollapseState property in the ExpandCollapse Control Pattern.	Object attribute haspopup="true"	Expose AXShowMenu action
   aria-haspopup="false" (default)	Clear the HASPOPUP state. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU
   aria-hidden (state)="true" (state)	This is used in platform accessibility APIs to indicate that the element and its children are hidden and should not be exposed to assistive technology. For assistive technologies that operate directly on the user agent's DOM it indicates that the element and its children are hidden and should not be processed by the assistive technology. If the aria-hidden state is undefined, implementations MAY use information from the browser rendering engine to determine if the element is visibly hidden. Advisory: it is incorrect use of WAI-ARIA if an element with aria-hidden (state)="true" is visible. The aria-hidden property is exposed only so that DOM-based assistive technologies can be informed of visibility changes. However, the browser engine will be able to provide the most complete set of all truly hidden nodes.
   aria-hidden (state)="false" (state) (default)
   aria-invalid (state)="true", "spelling", or "grammar" (state)		Set IA2_STATE_INVALID_ENTRY. Expose the value as a text attribute (not object attribute).	Expose status in IsDataValidForForm property	Expose the value as a text attribute (not object attribute).
   aria-invalid (state)="false" (state) (default)		Clear IA2_STATE_INVALID_ENTRY or equivalent state.	Expose status in IsDataValidForForm property
   aria-label	Expose in accessible name
   aria-labelledby		Expose a reference to the accessible object in IA2_RELATION_LABELLED_BY Expose reverse relations as described in Relations and compute the accessible name as described in Name Computation	Expose a reference to the accessible object in the LabeledBy property.	Expose a reference to the accessible object in RELATION_LABELLED_BY Expose reverse relations as described in Relations and compute the accessible name as described in Name Computation
   aria-level	Expose the level by accValue property of an outline object. The structure should be reflected in the accessible tree as directed by aria-level.	Expose as object attribute "level" and in groupPosition. May affect RELATION_NODE_CHILD_OF when used on a tree item. See section Group Position.	The tree hierarchy should be represented in the Automation Element structure as directed by aria-level.	Expose as object attribute "level"
   aria-live="assertive" (default for role alert)		Expose as object attribute "live". Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.		Expose as object attribute "live". Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.
   aria-live="polite" (default for role types log and status)		Expose as object attribute "live". Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.		Expose as object attribute "live". Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.
   aria-live="off" (default)		Expose as object attribute "live". Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.		Expose as object attribute "live". Expose a "container-live" object attribute with the value on all descendants as described in Changes to document content or node visibility.
   aria-multiline="true"		Set the IA2_MULTI_LINE state and clear IA2_SINGLE_LINE		Expose ATK_STATE_MULTI_LINE	Report "textbox" role as AXTextArea
   aria-multiline="false" (default)		Clear the IA2_MULTI_LINE state, and set IA2_SINGLE_LINE			Report "textbox" role as AXTextArea
   aria-multiselectable="true"	Set the MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match MULTISELECTABLE.	Expose the AccessibleSelection interface. See Selection.	Set CanSelectMultiple property on the Selection Control Pattern.	Expose ATK_STATE_MULTISELECTABLE
   aria-multiselectable="false" (default)	Clear the MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match MULTISELECTABLE.	Expose the AccessibleSelection interface. See Selection.
   aria-orientation="horizontal" (default)		Set IA2_STATE_HORIZONTAL		Set ATK_STATE_HORIZONTAL
   aria-orientation="vertical" (default for role scrollbar)		Clear IA2_STATE_HORIZONTAL		Set ATK_STATE_VERTICAL
   aria-owns	In MSAA-only implementations, the structure should be reflected in the accessible tree as directed by aria-owns. In implementations that use MSAA plus an API that supports relationships, the accessible tree should not be modified. If multiple aria-owns relationships are found, use only the first one.	IA2_RELATION_PARENT_WINDOW_OF 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 accessible tree as directed by aria-owns. If multiple aria-owns relationships are found, use only the first one.	ATK_RELATION_PARENT_WINDOW_OF Expose reverse relations as described in Relations If multiple aria-owns relationships are found, use only the first one.
   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.	The structure should be reflected in the accessible tree as directed by aria-posinset.	Expose as object attribute "posinset" and in "groupPosition".	The structure should be reflected in the accessible tree as directed by aria-posinset.	Expose as object attribute "posinset".
   aria-pressed (state)="true" (state)	Set the STATE_SYSTEM_PRESSED state.	If on a button (WAI-ARIA/HTML/XUL), expose the role as IA2_ROLE_TOGGLE_BUTTON. Expose object attribute checkable="true"	Expose as ToggleState property of Toggle Control Pattern	If on a button (WAI-ARIA/HTML/XUL), expose the role as ATK_ROLE_TOGGLE_BUTTON. Expose object attribute checkable="true"
   aria-pressed (state)="mixed" (state)	Set the STATE_SYSTEM_PRESSED state.	If on a button (WAI-ARIA/HTML/XUL), expose the role as IA2_ROLE_TOGGLE_BUTTON. Expose object attribute checkable="true"	Expose as ToggleState property of Toggle Control Pattern	Expose ATK_STATE_INDETERMINATE/STATE_SYSTEM_MIXED. If on a button (WAI-ARIA/HTML/XUL), expose the role as ATK_ROLE_TOGGLE_BUTTON. Expose object attribute checkable="true"
   aria-pressed (state)="false" (state)	Clear the STATE_SYSTEM_PRESSED state	If on a button (WAI-ARIA/HTML/XUL), expose the role as IA2_ROLE_TOGGLE_BUTTON. Expose object attribute checkable="true"	Expose as ToggleState property of Toggle Control Pattern	If on a button (WAI-ARIA/HTML/XUL), expose the role as ATK_ROLE_TOGGLE_BUTTON. Expose object attribute checkable="true"
   aria-pressed is undefined (state) (default)
   aria-readonly="true"	Expose as STATE_SYSTEM_READONLY	If on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY		If on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY
   aria-readonly="false" (default)	Expose as STATE_SYSTEM_READONLY	If on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY		If on an element that is editable, (e.g. an ENTRY or supports the IAccessibleEditableText interface) make sure that EDITABLE is set to the logical opposite of READONLY
   aria-relevant="additions", "removals", "text", or "all"		Expose as object attribute "relevant". Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility.		Expose as object attribute "relevant". Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility.
   aria-relevant="additions text" (Default)		Expose the value in an object attribute called "relevant". Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility.		Expose the value in an object attribute called "relevant". Expose a "container-relevant" object attribute with the value on all descendants as described in Changes to document content or node visibility.
   aria-required="true"		Expose IA2_STATE_REQUIRED	Expose as IsrequiredForForm property.	Expose ATK_STATE_REQUIRED
   aria-required="false" (default)
   aria-selected (state)="true" (state)	Expose STATE_SYSTEM_SELECTED Expose STATE_SYSTEM_SELECTABLE	If not DISABLED, toggle between "true" and "false" as appropriate when the AccessibleSelection interface is used on an ancestor with aria-multiselectable as described in Selection.	Expose IsSelected property on SelectionItem Control Pattern. The availability of the SelectionItem Control Pattern indicates the item is selectable.	If not DISABLED, toggle between "true" and "false" as appropriate when the AccessibleSelection interface is used on an ancestor with aria-multiselectable as described in Selection. Expose ATK_STATE_SELECTED	Set AXSelected attribute
   aria-selected (state)="false" (state)	Clear STATE_SYSTEM_SELECTED Expose STATE_SYSTEM_SELECTABLE	If not DISABLED, toggle between "true" and "false" as appropriate when the AccessibleSelection interface is used on an ancestor with aria-multiselectable as described in Selection.			Set AXSelected attribute
   aria-selected is undefined (state) (default)
   aria-setsize If not provided for relevant roles, user agents calculate aria-setsize and aria-posinset for each object in the container based on the number of objects in the DOM.		Expose object attribute "setsize" and "groupPosition".		Expose object attribute "setsize".
   aria-sort="ascending" or "descending"		Expose as object attribute "sort"		Expose as object attribute "sort"
   aria-sort="none" (default)		Expose as object attribute "sort"		Expose as object attribute "sort"
   aria-valuemax		Expose via AccessibleValue interface. See Widget values for additional information	Expose the Maximum property in RangeValue Control Pattern See Widget values for additional information	Expose via AccessibleValue interface. See Widget values for additional information	set AXMaxValue attribute See Widget values for additional information
   aria-valuemin		Expose via AccessibleValue interface See Widget values for additional information	Expose the Minimum property in RangeValue Control Pattern See Widget values for additional information	Expose via AccessibleValue interface See Widget values for additional information	Set AXMinValue attribute See Widget values for additional information
   aria-valuenow	If aria-valuetext is not defined, expose via IAccessible::get_accValue	Expose via AccessibleValue interface. If aria-valuetext is undefined, expose a string version of the aria-valuenow in the "valuetext" object attribute. See Widget values for additional information	Expose Value property in RangeValue Control Pattern See Widget values for additional information	Expose via AccessibleValue interface. If aria-valuetext is undefined, expose a string version of the aria-valuenow in the "valuetext" object attribute. See Widget values for additional information	Set AXValue and post NSAccessibilityValueChangedNotification if necessary See Widget values for additional information
   aria-valuetext	Expose via IAccessible::get_accValue	Expose in "valuetext" object attribute See Widget values for additional information	Expose Value property in Value Control Pattern which can co-exist with RangeValue Control Pattern. See Widget values for additional information	Expose in "valuetext" object attribute See Widget values for additional information	Set NSAccessibilityValueDescriptionAttribute to aria-valuetext string. See Widget values for additional information

4.6. Special Processing Requiring Additional Computation

4.7. Actions

Actions are exposed by the following rules:

• Elements which are natively focusable will usually have a default action or pattern specified as part of the native markup language specification. Changing the role with WAI-ARIA may change the default action or patterns, as specified in the tables below.
• User agents SHOULD set the default action to click or set the Invoke pattern for elements that have been made focusable by the author. For example, in HTML, authors indicate elements that are focusable using tabindex=0.
• User agents SHOULD set the default action to click if the element has registered a click event handler
• the element has a WAI-ARIA role allowing action (see the first table below)
• the element has a WAI-ARIA state or property that enables additional actions (see the second table below)

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

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

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

4.8. Events

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

5.1. Documents, Handling frame and iframe elements

Note: This section is specific to HTML only.

Computing the accessible name for an accessibility node for frame elements:

• Accessibility properties for the accessibility node for frame elements are exposed as they normally are for an element.

Computing the accessible name for an accessibility node for contained documents:

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

Computing the accessible description for an accessibility node for contained documents:

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

Computing IAccessible2 or ATK object attributes on any node in a sub-document:

For container-live, container-atomic, container-relevant, and container-busy, contained documents override frame elements from within the same document, because the contained document subtree is the more relevant context. However, frame elements override contained documents, because the frame element author may be different and may wish to define the context for a live iframe. For example, in a mashup scenario, it is usually the nearest parent container with aria-live, aria-atomic, aria-relevant, and aria-busy (state) that decides what object attribute appears on the child for container-live, container-atomic, container-relevant, and container-busy. in the case of a subdocument, the iframe aria-live, aria-atomic, aria-relevant, and aria-busy (state) overrides. This allows the author of the root document to control what gets spoken. They might include an otherwise polite chat program in an iframe and make it assertive.

Therefore:

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

Computing other properties for an accessibility node for contained documents:

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

Note: If the child frame is in a different domain than the parent, do not expose the name to javascript in the parent.

5.2. CSS Selectors

Support for attribute selectors MUST include WAI-ARIA attributes. For example, .fooMenuItem['aria-haspop=true'] would select all elements with class fooMenuItem, and WAI-ARIA property aria-haspopup with value of true. The presentation MUST be updated for dynamic changes to WAI-ARIA attributes. This allows authors to match styling with WAI-ARIA semantics. In the example above, if the aria-haspopup property on an element dynamically changes to a value of false, the style would no longer apply, and the text would no longer be bold.

5.3. Author Errors

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

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

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

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

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

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

If a required aria attribute for a given role is missing, user agents SHOULD process as if the following values were provided:

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

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

6.1. Glossary

This section is normative.

Accessibility API

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

Accessible object

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

Activation behavior

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

Assistive Technologies

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

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

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

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

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

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

Attribute

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

Class

An abstract type of object.

Current node

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

Current total text

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

Element

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

Event

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

Hidden

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

Informative

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

Normative

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

Object

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

Perceivable

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

Property

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

Role

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

Root WAI-ARIA node

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

Semantics

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

State

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

Sub-document

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

Target Element

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

User Agent

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

Valid ID

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

Widget

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

6.2. References

This section is normative.

6.3. Acknowledgments

The following people contributed to the development of this document.