[contents]
Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document describes how user agents should support keyboard navigation and respond to roles, states, and properties provided in Web content via WAI-ARIA [ARIA]. These features are used by authors creating accessible rich internet applications. Users often access the content using assistive technologies that rely on platform accessibility APIs to obtain and interact with information from the page. The WAI-ARIA User Agent Implementation Guide defines how implementations should expose content to accessibility APIs, helping to ensure that this information appears in a manner consistent with author intent. This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is a Public Working Draft by the Protocols & Formats Working Group of the Web Accessibility Initiative. It supports the Accessible Rich Internet Applications (WAI-ARIA) [ARIA] specification, providing information about how user agents should expose ARIA features to platform accessibility APIs. Implementers of mainstream user agents that work in concert with third party assistive technologies should follow the approaches in this document.
The Protocols and Formats Working Group intends to make the advice in this document normative, meaning user agents that conform to ARIA must conform to this document. However, at present, this document is not on the W3C Recommendation Track. The Working Group expects the next publication will be a First Public Working Draft on the Recommendation Track.
This document includes general information for user agents to handle WAI-ARIA roles, states, and properties. It also includes host-language specific requirements where necessary to complete the accessibility model. In the future, the PFWG may split out technology-specific versions of this guide, moving some requirements out but retaining this document as the general ARIA implementation guide.
Feedback on the information provided here is essential to the ultimate success of Rich Internet Applications that afford full access to their information and operations. The PFWG asks in particular:
Follow the instructions for commenting page to submit comments. Submit comments online (preferred) or by email to to public-pfwg-comments@w3.org (Archive). Comments should be made by 2 February 2010. In-progress updates to the document may be viewed in the publicly visible editors' draft.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The disclosure obligations of the Participants of this group are described in the charter.
This section is informative.
In traditional desktop graphical user interface (GUI) applications, elements of the user interface (UI) are displayed when needed and hidden when not needed based on user interactions. Accessibility application programming interfaces (APIs) are used to communicate semantic information about the user interface to assistive technology software used by people with disabilities. These APIs constitute a contract between applications and assistive technologies, such as screen readers, magnifiers, alternate input devices, and speech command and control, to enable them to access the appropriate semantics needed to produce a usable alternative to interactive applications. For example, screen reading software for the blind can determine whether a particular UI element is a menu, button, text field, list box, etc.
In traditional static Web pages, the HTML elements provided the necessary semantic information. Assistive technologies obtain the information from the Document Object Model (DOM) or, in the case of form elements, through the Accessibility API. In both cases, the assistive technology expects that nothing changes until a new page is loaded based on a user action. Yet, technologies such as JavaScript, Ajax, and CSS have enabled Web pages to look and behave more like interactive desktop GUI applications without the need to reload the page with each user interaction. Developers can now repurpose HTML elements into UI elements not previously defined in HTML. For example, Javascript can be used with CSS to modify a <div>
element based on user interactions to make it look and behave like a popup menu. Unfortunately, the <div>
element does not provide the author with a vehicle to add semantic metadata that can be exposed through the DOM and mapped to Accessibility APIs so that a screen reader can understand that it is a menu.
WAI-ARIA enables rich Internet applications to have the same accessibility features as desktop GUI applications by adding metadata to markup technologies such as (X)HTML. Authors include WAI-ARIA in their markup and user agents translate the WAI-ARIA markup to the platform accessibility APIs.
The WAI-ARIA User Agent Implementation Guide is intended to provide readers with an understanding of how to implement WAI-ARIA in user agents. As explained in the WAI-ARIA Primer [ARIA-PRIMER], accessibility deficiencies in traditional markup render rich Internet applications unusable by people who use assistive technologies (AT) or who rely on keyboard navigation. The W3C Web Accessibility Initiative's (WAI) Protocols and Formats working group (PFWG) has addressed these deficiencies through several W3C standards efforts, with a focus on the WAI-ARIA specifications.
The WAI-ARIA User Agent Implementation Guide is part of a set of resources that support the WAI-ARIA specification. For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Primer [ARIA-PRIMER] provides a basic introduction to the concepts behind and reason for WAI-ARIA. The WAI-ARIA Authoring Practices Guide [ARIA-PRACTICES] describes recommended usage patterns for Web content developers. The User Agent Implementation Guide describes how WAI-ARIA roles, states, and properties should be supported in user agents using platform accessibility APIs. The WAI-ARIA Suite fills gaps identified by the Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap) [ARIA-ROADMAP]. These documents serve as important places of clarification where topics appear to be unclear.
With the conceptual basis provided in the WAI-ARIA Primer [ARIA-PRIMER], you should have a good understanding of how WAI-ARIA provides for interoperability with assistive technologies and support for a more usable, accessible experience. This guide begins by providing a general overview of accessibility APIs and the accessible object hierarchy known as the accessible tree. The following sections give guidance on supporting keyboard navigation and mapping WAI-ARIA roles, states, and properties to accessibility APIs. Other sections give guidance on calculating text alternatives, mapping actions to events, event processing, special document handling procedures, and error handling.
This guide assumes that a user agent already exposes static content to ATs via the accessibility API on a given platform. Most of the additional work to enable WAI-ARIA can be divided into three parts:
In general, WAI-ARIA properties should only affect how content is mapped to platform accessibility APIs. They should not affect the visual rendering of content or the behavior of mainstream desktop browsers, except when style sheets are deliberately keyed off of WAI-ARIA attributes as recommended in the specification. This allows one of the primary principles of WAI-ARIA to be upheld—that content still renders and behaves the same for the majority of users in legacy browsers which do not support WAI-ARIA.
The Document Object Model (DOM) is used to represent the structure and state of the elements in the document being rendered by the user agent. The elements of the document are organized into a hierarchy of nodes known as the DOM tree. Developers use APIs to manipulate the objects in the DOM tree enabling the concept of rich Internet applications.
For traditional Web pages, assistive technologies, such as screen readers, interact with user agents using the DOM. In order to make a Web application behave like a desktop application, 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 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. Originally, screen readers used heuristic techniques to determine the meaning of the user interface and built an alternative off screen model of the user interface. 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 to assistive technologies. When developers use WAI-ARIA to provide the semantic role, state, and property information for elements in a rich Internet Application (RIA), the user agent must then map the information to the appropriate accessibility API for the platform.
Accessibility APIs covered by this document are:
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.
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.
This section is normative.
This specification indicates whether a section is normative or informative and the classification applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.
Normative sections provide requirements that must be followed for an implementation to conform to this specification. The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Keywords for use in RFCs to indicate requirement levels [RFC2119].
Informative sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow such recommendations in order to conform to this specification.
This section is normative.
Enabling keyboard navigation in web applications is a necessary step toward making accessible web applications possible. User agents MUST ensure all renderable elements are focusable and may be focusable without having to be placed in a pre-defined tabbing order. All focusable elements must also provide for programmatic access. This allows for device-independent access, is needed to conform to the User Agent Accessibility Guidelines, and is vital for a successful implementation of WAI-ARIA.
Usable keyboard navigation in a rich Internet application is different from the tabbing paradigm among interactive elements such as links and form controls in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant complex widgets and uses the arrow keys to navigate within a complex widget, such as a menu or spreadsheet. The changes that WAI-ARIA introduces in keyboard navigation make this enhanced accessibility possible. In WAI-ARIA, any element can be keyboard focusable.
There are two mechanisms that allow for keyboard operation of accessible script widgets: tabindex
and aria-activedescendant
. Most other aspects of WAI-ARIA widget development depend on keyboard navigation functioning properly.
Assistive technologies often need to set the focus. For example, voice input software, onscreen keyboards and screen readers supply their own structured navigation modes, providing additional commands for moving to elements in a page. Both the user agent and web pages need to handle this gracefully. Script container widgets cannot expect that focus changes occur only from the keyboard or a mouse click. They need to listen for focus or aria-activedescendant
changes and update their state when that occurs.
tabindex
User agents that support WAI-ARIA 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 can be focused 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, tree view or spreadsheet.
The user agent implementation MUST to do the following to enable tabindex
on all elements:
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.tabindex="0"
, the user agent MUST allow the element to be focused and MUST include the element in the sequential tab order.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 for details. tabindex
attribute MUST expose the element.tabIndex
property.focus
and blur
methods MUST be added to the HTMLElement
interface (available to script for every type of element).focus
and blur
events.keydown
event MUST also cancel the keypress
event, for purposes of compatibility with other browsers.FOCUSED
and FOCUSABLE
accessibility API states, and FOCUS
events for any element in the accessible tree as described in State and Property Mapping.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.click
on the element. The steps to simulate a click
include:
click
eventNote: Over time, user agents have provided differing implementations and levels of support for the tabindex
attribute. Examples include: the Gecko documentation on Key-navigable custom DHTML widgets; the documentation for Internet Explorer's's tabindex
behavior in MSDN: tabindex
Property, and Opera simple testcases. The HTML 5 spec documents what the extended behavior of tabindex
should be ([HTML5]) and user agent implementations.
aria-activedescendant
Editorial note: In current implementations as described below, user agents keep the desktop focus on the container but communicate focus events and states to the AT as if the active descendant has focus.
Alternatively, the actual desktop focus could move to the active descendant. This would be a less complex scenario for user agents to implement and would be a better scenario for users who have customized the appearance of their desktop keyboard focus. There is some concern that if the desktop focus is placed on the active descendant, some keyboard events might get dropped.
The User Agent Implementation task force seeks feedback from reviewers on this issue.
The aria-activedescendant
property could also be used to enable keyboard accessibility on any type of WAI-ARIA element. 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 tabindex="0"
on the container element 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
:
tabindex
recommendations in Controlling focus with tabindex
. Support for tabindex="0"
on all elements is still necessary for authors to use the aria-activedescendant
system, because the container widget MUST be in the tab order.aria-activedescendant
which points to a valid ID, the user agent MUST not mark it as focused in the accessibility API.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.aria-activedescendant
attribute, the user agent MUST apply the following states to the target to ensure the object is accessible:
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.ACTIVE
, whenever the container element sets aria-activedescendant
to match the ID of this descendantFOCUSED
, if ACTIVE
and the container widget with aria-activedescendant
has true DOM focusaria-activedescendant
, the user agent MUST change the value of aria-activedescendant
to point to that item.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.
MSAA | UIA | ATK | MAC Accessibility |
---|---|---|---|
accSelect(SELFLAG_TAKEFOCUS) | RaiseAutomationEvent | AtkComponent::grab_focus |
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.This section is normative.
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:
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.presentation
role before any other mappable role (see Role Mapping below). If the presentation
role is used, the element must still be exposed if it is focusable, so that focus events can be fired (focus must never be lost).aria-hidden
property set to "true". Hidden elements are not exposed to assistive technology.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.presentation
from an owning element. If the presentation
role is computed, the element must still be exposed if it is focusable, so that focus events can be fired (focus must never be lost).The following elements are not exposed via the accessibility API and user agents SHOULD NOT include them in the accessible tree:
role="presentation"
. In the case of structural container elements that have "presentation
", such as HTML tables or lists, child elements that are required owned elements of the container inherit the presentation
role and SHOULD 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.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.
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 MUST use the WAI-ARIA semantics to define how it exposes the element to accessibility APIs, not the native semantics. To achieve this the following rules MUST be followed:
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.
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 raw WAI-ARIA data as a text string. User agents MAY also expose the raw WAI-ARIA information 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 that an accessibility API does not have a specific interface for. 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.
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.
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.
WAI-ARIA includes some roles, such as landmarks and advanced widgets, that are not traditionally part of accessibility APIs. Because landmarks do not generally have mappings in platform accessibility APIs, they may occur anywhere within the role string without affecting how the first widget role is exposed. In addition, future versions of WAI-ARIA may allow for author-defined roles to be used in the role string. In that case, it is expected that a fallback role may be provided after the custom role, in the role string.
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:
The following steps will correctly identify the applicable WAI-ARIA role:
role=string
)AriaRole
property. The AriaRole property
can also support secondary roles using a space as a separator.role=string
)WAI-ARIA role | MSAA role | IAccessible2 role and other IAccessible2 features | UIA Control Pattern Type | ATK role | MAC Accessibility Role |
---|---|---|---|---|---|
alert | ROLE_SYSTEM_ALERT | Text | ATK_ROLE_ALERT | AXGroup , AXRoleDescription="alert" | |
alertdialog | ROLE_SYSTEM_DIALOG | Window | ATK_ROLE_DIALOG | AXGroup , AXRoleDescription="alert dialog" | |
application | ROLE_SYSTEM_APPLICATION | Pane | ATK_ROLE_EMBEDDED | AXGroup , AXRoleDescription="application" | |
article | ROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY | ATK_ROLE_DOCUMENT_FRAME + do not expose ATK_STATE_EDITABLE | AXGroup , AXRoleDescription"article" | ||
banner | Object attribute role="banner" | Expose as text string in AriaRole | Object attribute role="banner" | AXGroup , AXRoleDescription="banner" | |
button | ROLE_SYSTEM_PUSHBUTTON . If aria-haspopup ="true" it SHOULD be exposed as a ROLE_SYSTEM_BUTTONMENU | If aria-pressed is not undefined, it SHOULD be exposed as IA2_ROLE_TOGGLE_BUTTON | Button | ATK_ROLE_PUSH_BUTTON | AXButton |
checkbox | ROLE_SYSTEM_CHECKBUTTON | object attribute checkable="true" | Checkbox | ATK_ROLE_CHECK_BOX + object attribute checkable="true" | AXCheckBox |
columnheader | ROLE_SYSTEM_COLUMNHEADER | used to help support AccessibleTable for the container grid role | DataItem | ATK_ROLE_COLUMN_HEADER | AXCell |
combobox | ROLE_SYSTEM_COMBOBOX + STATE_SYSTEM_HASPOPUP . If aria-expanded is not "true", expose STATE_SYSTEM_COLLAPSED | Combobox | ATK_ROLE_COMBO_BOX + ATK_STATE_EXPANDABLE + object attribute haspopup="true" | AXComboBox | |
complementary | Object attribute role="complementary" | Expose as text string in AriaRole | Object attribute role="complementary" | AXGroup , AXRoleDescription="complementary" | |
contentinfo | Object attribute role="contentinfo" | Expose as text string in AriaRole | Object attribute role="contentinfo" | AXGroup , AXRoleDescription="content" | |
definition | Object attribute role="definition" | Expose as text string in AriaRole | Object attribute role="definition" | ||
dialog | ROLE_SYSTEM_DIALOG | Window | ATK_ROLE_DIALOG | AXGroup , AXRoleDescription="dialog" | |
directory | ROLE_SYSTEM_LIST | List | AXList | ||
document | ROLE_SYSTEM_DOCUMENT + STATE_SYSTEM_READONLY | Document | ATK_ROLE_DOCUMENT_FRAME + readonly | AXGroup , AXRoleDescription="document" | |
grid | ROLE_SYSTEM_TABLE | Use IAccessibleTable2 interface | DataGrid | ATK_ROLE_TABLE | AXTable |
gridcell | ROLE_SYSTEM_CELL | DataItem | ATK_ROLE_TABLE_CELL | AXCell | |
group | ROLE_SYSTEM_GROUPING | Group | ATK_ROLE_PANEL | AXGroup | |
heading | ROLE_SYSTEM_TEXT or use xml-roles | IA2_ROLE_HEADING | Text | ATK_ROLE_HEADING | AXHeading |
img | ROLE_SYSTEM_GRAPHIC | Image | ATK_ROLE_IMAGE | AXImage | |
link | ROLE_SYSTEM_LINK . Also, apply special rule to expose STATE_LINKED to link and all its descendants. | HyperLink | ATK_ROLE_LINK | AXLink | |
list | ROLE_SYSTEM_LIST + STATE_SYSTEM_READONLY | List | ATK_ROLE_LIST + do not expose ATK_STATE_EDITABLE | AXList | |
listbox . If child of or owned by a combobox , expose as menu | ROLE_SYSTEM_LIST | List | ATK_ROLE_LIST . Special case: if a listbox has a parent or is owned by (via aria-owns ) a combobox , it SHOULD be exposed with ATK_ROLE_MENU . | AXList | |
listitem | ROLE_SYSTEM_LISTITEM + STATE_SYSTEM_READONLY | ListItem | ATK_ROLE_LISTITEM + do not expose ATK_STATE_EDITABLE | AXGroup | |
log | ROLE_SYSTEM_PANE | Expose as object attribute role="log" | Pane | AXGroup , AXRoleDescription="log" | |
main | Object attribute role="main" | Expose as text string in AriaRole | Object attribute role="main" | AXGroup , AXSubrole: AXLandmarkMain , AXRoleDescription="main" | |
marquee | ROLE_SYSTEM_ANIMATION or use xml-roles | Expose as object attribute role="marquee" | Text | ATK_ROLE_PANEL | AXGroup , AXRoleDescription="marquee" |
math | ROLE_SYSTEM_EQUATION | ATK_ROLE_UNKNOWN | AXGroup , AXRoleDescription="math" | ||
menu | ROLE_SYSTEM_MENUPOPUP | Menu | ATK_ROLE_MENU . These objects SHOULD NOT be exposed for a submenu if there is a parent menu item spawning the submenu | AXMenu | |
menubar | ROLE_SYSTEM_MENUBAR | MenuBar | ATK_ROLE_MENU_BAR | AXMenuBar | |
menuitem | ROLE_SYSTEM_MENUITEM | MenuItem | ATK_ROLE_MENU_ITEM
| If the option's parent has a If the option's parent has a
| |
menuitemcheckbox | ROLE_SYSTEM_CHECKBUTTON or ROLE_SYSTEM_MENUITEM | IA2_ROLE_CHECK_MENU_ITEM + object attribute checkable="true" | Checkbox | ATK_ROLE_CHECK_MENU_ITEM + object attribute checkable="true" | AXMenuItemRole |
menuitemradio | ROLE_SYSTEM_RADIOBUTTON or ROLE_SYSTEM_MENUITEM | IA2_ROLE_RADIO_MENU_ITEM + object attribute checkable="true" | RadioButton | ATK_ROLE_RADIO_MENU_ITEM + object attribute checkable="true" | AXMenuItemRole |
navigation | Expose as object attribute role="navigation" | AXGroup , AXRoleDescription="navigation" | |||
note | IA2_ROLE_NOTE | AXGroup , AXRoleDescription="note" | |||
option | ROLE_SYSTEM_LISTITEM | If aria-checked is not undefined, support object attribute checkable="true" | ListItem | ATK_ROLE_LIST_ITEM
| If the option's parent has a If the option's parent has a
|
presentation | ROLE_SYSTEM_PANE . Do not expose this object unless it is focusable | Pane | Do not expose this object unless it is focusable | AXGroup , AXRoleDescription="presentation" | |
progressbar | ROLE_SYSTEM_PROGRESSBAR + STATE_SYSTEM_READONLY | ProgressBar | ATK_ROLE_PROGRESS_BAR + do not expose ATK_EXTENDED_STATE_EDITABLE | AXProgressIndicator | |
radio | ROLE_SYSTEM_RADIOBUTTON | RadioButton | ATK_ROLE_RADIO_BUTTON | AXRadioButton | |
radiogroup | ROLE_SYSTEM_GROUPING | Group | ATK_ROLE_PANEL | AXRadioGroup | |
region | ROLE_SYSTEM_PANE | Pane | ATK_ROLE_PANEL | AXGroup , AXRoleDescription="region" | |
row | ROLE_SYSTEM_ROW unless inside a "tree" or "treegrid", in which case ROLE_SYSTEM_OUTLINEITEM | used to help support: IAccessibleTable2 interface for the container grid role | DataItem | ATK_ROLE_LIST_ITEM | AXRow |
rowheader | ROLE_SYSTEM_ROWHEADER | Used to help support IAccessibleTable2 interface for the container grid role | DataItem | ATK_ROLE_ROW_HEADER | AXCell |
scrollbar | ROLE_SYSTEM_SCROLLBAR | ||||
search | AXGroup , AXRoleDescription="search" | ||||
separator | ROLE_SYSTEM_SEPARATOR | Separator | ATK_ROLE_SEPARATOR | AXSplitter | |
slider | ROLE_SYSTEM_SLIDER | Slider | ATK_ROLE_SLIDER | AXSlider | |
spinbutton | ROLE_SYSTEM_SPINBUTTON | Spinner | ATK_ROLE_SPIN_BUTTON | AXProgressIndicator | |
status | ROLE_SYSTEM_STATUSBAR | StatusBar | ATK_ROLE_STATUSBAR | AXGroup , AXRoleDescription="status" | |
tab | ROLE_SYSTEM_PAGETAB . Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby . | TabItem | ATK_ROLE_PAGE_TAB . Expose SELECTED state if focus is inside tabpanel associated with aria-labelledby . | AXRadioButton , AXRoleDescription="tab" | |
tablist | ROLE_SYSTEM_PAGETABLIST | Tab | ATK_ROLE_PAGE_TAB_LIST | AXTabGroup | |
tabpanel | ROLE_SYSTEM_PANE or ROLE_SYSTEM_PROPERTYPAGE | Pane | ATK_ROLE_SCROLL_PANE | AXTabGroup | |
textbox | ROLE_SYSTEM_TEXT | IA2_STATE_SINGLE_LINE if aria-multiline is not "true" | Document | ATK_ROLE_ENTRY + ATK_STATE_SINGLE_LINE if aria-multiline is not "true" | AXTextArea |
timer | Expose as object attribute role="timer" | AXGroup , AXRoleDescription="timer" | |||
toolbar | ROLE_SYSTEM_TOOLBAR | ToolBar | ATK_ROLE_TOOL_BAR | AXToolbar | |
tooltip | ROLE_SYSTEM_TOOLTIP | ToolTip | ATK_ROLE_TOOL_TIP | AXGroup , AXRoleDescription="tooltip" | |
tree | ROLE_SYSTEM_OUTLINE | Tree | ATK_ROLE_TREE | AXOutline | |
treegrid | ROLE_SYSTEM_OUTLINE | Use IAccessibleTable2 interface
Expose as object attribute | DataGrid | ATK_ROLE_TREE_TABLE | AXOutline |
treeitem | ROLE_SYSTEM_OUTLINEITEM | If aria-checked is not undefined, support object attribute checkable="true" | TreeItem | ATK_ROLE_LIST_ITEM + if aria-checked is not undefined, support object attribute checkable="true" | AXRow , AXRoleDescription="outline row" |
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.
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
.aria-checked
should not be exposed as CHECKED
on <div role="grid">
AriaProperties
property directly corresponds to the ARIA states and properties when an element is exposed in the accessible tree. UIA AriaProperties
is a string property formatted as a name and value pair. For example, "checked=true;disabled=false". Deliminators are the equal sign ("=") and the semicolon (";"). A backslash (\) is used as an escape when the deliminator 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. Full mapping from ARIA states to MSAA and UIA properties are available at MSDN UIA SDK Appendix.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. See also ID Reference Error Processing in Relations.
In cases, however, the focus can be transparent in an accessible tree as it may 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 | See Controlling focus with aria-activedescendant and Handling focus changes from the Assistive Technology. See also ID Reference Error Processing in Relations.
In cases, however, the focus can be transparent in an accessible tree as it may 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 | If AXFocused is true, post "NSAccessibilityFocusedUIElementChangedNotification " notification when aria-activedescendant value changes | ||
| 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. | |||
(default) | |||||
, "list" , or "both" | Expose as object attribute autocomplete
Expose the | Expose as object attribute autocomplete
Expose the | |||
(default) | |||||
(state) | Expose the STATE_SYSTEM_BUSY state | Expose the ATK_STATE_BUSY state | |||
(state) (default) | Clear the STATE_SYSTEM_BUSY state | Clear the ATK_STATE_BUSY state | |||
(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" |
(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" |
(state) | 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 | 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 |
(state) | Set STATE_SYSTEM_UNAVAILABLE
Expose Propagate to all descendants of the element with | Set IsEnabled to "false" | Set AXEnabled to "false" | ||
(state) (default) | Clear STATE_SYSTEM_UNAVAILABLE | Set IsEnabled to "true" | Expose ATK_STATE_ENABLED | Set AXEnabled to "true" | |
aria-dropeffect (state) | Expose as object attribute "dropeffect" | Expose as object attribute "dropeffect" | |||
(state) (default) | Expose as object attribute "dropeffect" | Expose as object attribute "dropeffect" | |||
(state) | Set STATE_SYSTEM_EXPANDED | Expose as ExpandCollapseState property of ExpandCollapse Control Pattern | Expose ATK_STATE_EXPANDABLE and ATK_STATE_EXPANDED | ||
(state) | Set STATE_SYSTEM_COLLAPSED | Expose as ExpandCollapseState property of ExpandCollapse Control Pattern | Expose ATK_STATE_EXPANDABLE | ||
aria-expanded is undefined (state) (default) | The object is neither expandable or collapsible. | ||||
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. | ||
or "false" | Expose object attribute grabbed="true" | Expose object attribute grabbed="true" | |||
aria-grabbed is undefined (default) | Expose object attribute grabbed="false" | Expose object attribute grabbed="false" | |||
| 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. | Expose as object attribute haspopup="true" | Expose AXShowMenu action | |
(default) | Clear the HASPOPUP state. If on a push button, change the role to ROLE_SYSTEM_BUTTONMENU | ||||
(state) | This is not used in mapping to platform accessibility APIs. Instead, use information from the browser core to determine if the element is hidden or not. Advisory: it is incorrect use of WAI-ARIA if an element with is visible. The aria-hidden property is exposed only so that DOM-based assistive technologies can be informed of visibility changes. However, the browser core will be able to provide the most complete set of all truly hidden nodes. | ||||
(state) (default) | This is not used in mapping to platform accessibility APIs. Instead, use information from the browser core to determine if the element is hidden or not. Advisory: it is incorrect use of WAI-ARIA if an element with is visible. The aria-hidden property is exposed only so that DOM-based assistive technologies can be informed of visibility changes. However, the browser core will be able to provide the most complete set of all truly hidden nodes. | ||||
, "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). | ||
(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 | The tree hierarchy should be represented in the Automation Element structure as directed by aria-level . | Expose as object attribute "level" | |
or "assertive" | Expose as object attribute "live" .
Expose a | Expose as object attribute "live" .
Expose a | |||
(default) | Expose as object attribute "live" .
Expose a | Expose as object attribute "live" .
Expose a | |||
| Set the IA2_MULTI_LINE state and clear IA2_SINGLE_LINE | Expose ATK_STATE_MULTI_LINE | Report "textbox" role as AXTextArea | ||
(default) | Clear the IA2_MULTI_LINE state, and set IA2_SINGLE_LINE | Report "textbox" role as AXTextArea | |||
| 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 | |
(default) | Clear the MULTISELECTABLE state. Expose STATE_SYSTEM_EXTSELECTABLE to exactly match MULTISELECTABLE . | Expose the AccessibleSelection interface. See Selection. | |||
| Set IA2_STATE_HORIZONTAL | Set ATK_STATE_HORIZONTAL | |||
(default) | Clear IA2_STATE_HORIZONTAL | Set ATK_STATE_VERTICAL | |||
aria-owns | the structure should be reflected in the accessible tree as directed by aria-owns . | IA2_RELATION_PARENT_WINDOW_OF
Expose reverse relations as described in Relations | The structure should be reflected in the accessible tree as directed by aria-owns . | RELATION_PARENT_WINDOW_OF
Expose reverse relations as described in Relations | |
aria-posinset . | 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 ="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 | 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 | |
(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 | 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 | |
(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 | 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 | |
aria-pressed is undefined (state) (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 | ||
(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 | ||
, "removals" , "text" , or "all" | Expose as object attribute "relevant" .
Expose a | Expose as object attribute "relevant" .
Expose a | |||
(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 | Expose IA2_STATE_REQUIRED | Expose as IsrequiredForForm property. | Expose ATK_STATE_REQUIRED | ||
(state) | Expose STATE_SYSTEM_SELECTED
Expose | 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 | 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 |
(state) | Clear STATE_SYSTEM_SELECTED
Expose | 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 | Expose object attribute "setsize" and in groupPosition . | Expose object attribute "setsize" . | |||
or "descending" | Expose as object attribute "sort" | Expose as object attribute "sort" | |||
(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 |
The text alternative is reused in both the name and description computation, as described below. 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 2D (which is recursive), using the full set of rules to retrieve text from its own children.
To compute the text alternative for an element:
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 information.aria-label
attribute, which defines an explicit text string, takes precedence as the element's text alternative.aria-label
is empty or undefined, the aria-labelledby
attribute is used unless this computation is already occurring as the result of a recursive aria-labelledby
declaration (in other words, aria-labelledby
is not recursive, so it will not cause loops). 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).aria-label
and aria-labelledby
are empty or undefined, 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.spinbutton
or slider
), use the value of the aria-valuetext
attribute if available, or otherwise the value of the aria-valuenow
attribute.title
attribute in HTML). This is used only if nothing else, including subtree content, has provided results.:before
and :after
pseudo-elements, it is necessary for user agents to combine such content with the text referenced by the text nodes to produce a complete text alternative.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.
If aria-label
is not present but aria-labelledby
is present, the user agent MUST compute the name by concatenating the text alternative of each element referenced by the IDs in the aria-labelledby
attribute, in sequential order, with a space delimeter between each text alternative.
Otherwise, aria-labelledby
will not be used, and the accessible name MUST be computed using the text alternative computation on the current element.
If the element is an <img> and the computed text alternative is empty, then check for the presence of role presentation
or any labeling attribute, 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 AT to do its own heuristic processing to repair the missing accessible name.
To compute the accessible description for an element, start with an empty string:
If aria-describedby
is present, collect the description from the elements pointed to by aria-describedby
. Process the IDs in aria-describedby
in the order they occur. Ignore IDs that are not specified on an element in the document. For each ID use the text alternative computation.
Widgets that have a particular value within a range of values, such as 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 current value SHOULD return an error.
When the user or assistive technology sets the value on an object that is not readonly
or disabled
, the user agent SHOULD set aria-valuenow
to reflect the new value. The implementation SHOULD reject values which are less than the aria-valuemin
or greater than the aria-valuemax
. In the case of an invalid aria-valuenow
attribute, an error may be reported to the debugging console but should not be reported through the API. If the value cannot be set because the object is readonly
or disabled
or the new value would be out of bounds, the user agent SHOULD throw an exception rather than set the value.
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
, expose the string in aria-valuetext
as specified in State and Property Mapping, but return an error for any value getter that only returns a numeric type.
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. Therefore, it is not important to check the role before computing them.
Both forward and reverse relationship can be defined. A forward relation exists when an element has properties that refer to the ID of another element. User agents MUST map forward relations to accessibility APIs as defined in State and Property Mapping. A reverse relation exists when an element's ID is referenced by a property in another element. The following table defines the API mapping when an element's ID is referenced by a relation property of another element.
WAI-ARIA Relation | MSAA | IAccessible2 (if different from MSAA) | UI Automation | ATK | MAC Accessibility |
---|---|---|---|---|---|
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_DESCRIPTION_FOR | |||
aria-labelledby references the element's ID | IA2_RELATION_LABEL_FOR | RELATION_DESCRIPTION_FOR | |||
aria-owns references the element's ID | IA2_RELATION_NODE_CHILD_OF | RELATION_DESCRIPTION_FOR |
If both aria-labelledby
and HTML <label for=> are used, the WAI-ARIA relation wins and the HTML label relation is ignored.
In addition to the explicit relationships defined by WAI-ARIA properties, IAccessible2 and ATK reverse relations are implied in two other situations: elements with role="treeitem"
where the ancestor does not have an aria-owns
property and descendents of elements with aria-atomic
property.
In the case of role="treeitem"
, when aria-owns
is not used:
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.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
:
aria-atomic
="true". If found, user agents SHOULD set the RELATION_MEMBER_OF
relation to point to the ancestor that sets aria-atomic
="true".User agents should ignore ID references that do 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. If more than one ID is specified for aria-activedescendant
, the user agent should use the whole string to search for an element that has that ID. For instance, aria-activedescendant
="foo bar" would match an element with id="foo bar".
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
is larger than aria-setsize
, use aria-setsize
for aria-posinset
.
If aria-level
is not provided or inherited for an element of role treeitem
, user agents MUST compute it by following the explicit or computed RELATION_NODE_CHILD_OF
relations as described in Relations.
If aria-posinset
and aria-setsize
are not provided, user agents MUST compute them as follows:
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.aria-posinset
includes the current item and items before it in the group. aria-setsize
adds to that the number of items in the same group after the current item.Because these values are 1-based, the current item must be included in the computation. For aria-posinset
, add items only if they are before the current item in the DOM. For aria-setsize
, also add items after the current item in the DOM.
Actions are exposed by the following rules
click
event handlerxlink
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.
WAI-ARIA Role | Default action | MSAA Event | UIA Event |
---|---|---|---|
button | press | EVENT_OBJECT_STATECHANGE | |
checkbox | check/uncheck | EVENT_OBJECT_STATECHANGE | |
combobox | open/close | ||
link | jump | ||
listitem | select/unselect if parent role is listbox | ||
menuitem | click | DoDefaultAction | |
menuitemcheckbox | click | ||
menuitemradio | click | ||
option | select/unselect | ||
radio | select | ||
scrollbar (sub-parts) | scroll | EVENT_OBJECT_CONTENTSCROLLED | VerticalScrollPercentProperty or HorizontalScrollPercentProperty property change on the associated scroll bars |
tab | switch | ||
textbox | activate | ||
treeitem | activate + expand/collapse |
WAI-ARIA State or Property | Actions | Events | Notes |
---|---|---|---|
aria-activedescendant | click, activate, invoke (UIA) | focus, blur | Add focused and focusable API states |
aria-dropeffect | Shift-F10, right click | focus, blur | popup collection of actions the user can perform focusable Should have a navigation dialog for all hit targets and landmarks Should have style sheet to highlight all targets |
aria-expanded | click, arrow key | expansion events | Editorial note: interested in exploring expand/collapse |
aria-grabbed | if grabbable, expose grab action if grabbed, targets become focusable | MSAA: EVENT_SYSTEM_DRAGDROPSTART , EVENT_SYSTEM_DRAGDROPEND | focusable, selectable if aria-grabbed="true", change to focused, collection of drop targets will become focusable |
aria-haspopup | display popup menu | See Menus in MSAA/IAccessible2/UIA | |
aria-live | update | ||
aria-relevant | live region, what's relevant to listen for? what events the API should be supporting | ||
aria-selected | selection | ||
aria-sort | click |
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.
For dynamic WAI-ARIA state and property changes, user agents MUST expose an event, such as state change, to indicate the change occurred. For simplicity and performance the user agent MAY trim out change events for state or property changes that assistive technologies typically ignore. An event MUST be fired for changes in:
aria-disabled
: this will affect ENABLED
and SENSITIVE
statesaria-checked
or aria-pressed
: this will affect the CHECKED
state. A state change for MIXED
/INDETERMINATE
SHOULD also be fired when the value changes to or from "mixed".aria-invalid
: this will affect the INVALID_ENTRY
state. Note that this is different from the INVALID
state in some APIs which means no valid state.aria-expanded
, aria-readonly
, aria-required
: these will affect the states of similar names in the accessibility APIsOther types of changes:
aria-activedescendant
changes affect focus events as described in Controlling focus with aria-activedescendant
aria-valuenow
changes should be exposed via value change events. See Widget Values for more information.aria-multiselectable
changes SHOULD cause the destruction and recreation of a new accessible object for the element, because it is a major change where the interfaces exposed via accessibility APIs change as well.aria-selected
changes SHOULD affect selection events as described in SelectionState or Property | MSAA event | IAccessible2 event (if different from MSAA) | UIA event | ATK event | Apple Event |
---|---|---|---|---|---|
aria-busy | |||||
aria-checked | EVENT_OBJECT_STATECHANGE | ToggleStateProperty | |||
aria-disabled | EVENT_OBJECT_STATECHANGE | ||||
aria-expanded | EVENT_OBJECT_STATECHANGE | ||||
aria-grabbed | EVENT_OBJECT_SELECTION | ||||
aria-hidden | EVENT_OBJECT_SELECTION , EVENT_OBJECT_HIDE , EVENT_OBJECT_SHOW | StructureChangedEvent | |||
aria-invalid | |||||
aria-pressed | |||||
aria-readonly | EVENT_OBJECT_STATECHANGE | ||||
aria-required | |||||
aria-selected | |||||
aria-valuenow | ValueProperty property change |
Processing document changes is important regardless of WAI-ARIA. It is described here, however, because it is so crucial to enable Ajax and other use cases that often go along with WAI-ARIA markup.
In UIA, fire the extChangedEvent
, TextSelectionChangedEvent
, or PropertyChanged
event for the corresponding property. For example, when there is a change to the inner text of an element that supports the Text
Control Pattern, fire the TextChangedEvent
. For an element that supports the Value
Pattern, and maps the inner text to the Value
property of the pattern, fire the PropertyChanged
event for the Value
property.
Scenario | MSAA event | IAccessible2 event (if different from MSAA) | UIA event | ATK event | Apple Event |
---|---|---|---|---|---|
When text is removed | IA2_EVENT_TEXT_REMOVED | TextPattern..::.TextChangedEvent | text_changed:delete | ||
When text is inserted | IA2_EVENT_TEXT_INSERTED | extPattern..::.TextChangedEvent | text_changed:insert | ||
When text is changed | fire a removal event followed by an insertion event | fire a removal event followed by an insertion event | fire a removal event followed by an insertion event | fire a removal event followed by an insertion event | fire a removal event followed by an insertion event |
Fire these events for node changes where the node in question is an element and has an accessible object:
Scenario | MSAA event | IAccessible2 event (if different from MSAA) | UIA event | ATK event | Apple Event |
---|---|---|---|---|---|
When a subtree is hidden Depends on aria-relevant? | EVENT_OBJECT_HIDE The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and ATs avoid 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 | ||
When a subtree is removed Depends on aria-relevant? | EVENT_OBJECT_REORDER The MSAA event called EVENT_OBJECT_DESTROY is not used because this has a history of stability issues and ATs avoid 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 | ||
When a subtree is shown | EVENT_OBJECT_SHOW | children_changed:add | |||
When a subtree is inserted | EVENT_OBJECT_REORDER | children_changed:add | |||
When a subtree is moved | treat it as a removal from one place and insertion in another and fire EVENT_OBJECT_REORDER on the parent | 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 | |
When a subtree is changed (e.g. replaceNode) | treat it as a removal and insertion and fire EVENT_OBJECT_REORDER on the parent | treat it as a removal and insertion | treat it as a removal and insertion | treat it as a removal and insertion |
For node changes where the node is not an element or has no accessible object:
AccessibleText
interface. Compute and fire relevant text change events as described above.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 AT 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:
Exposing additional useful information about the context of the change:
RELATION_MEMBER_OF
relation on the accessible event object SHOULD point to any ancestor with aria-atomic
="true"
(if any).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:
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.There are two cases for selection:
In the single selection case, it is not always necessary to manage selection events and states separate from focus, since selection mirrors focus. One exception is for tab lists. In the case of a tab, if either the tab or its associated tabpanel has focus, then the tab is considered to be SELECTED
. To implement this, the user agent can walk up the parent chain from the focus until it finds a tabpanel, then traverse the aria-labelledby
relation from the tabpanel to the related tab, and mark the found tab as focused.
The multiple selection case occurs when aria-multiselectable
="true" on an element with a role that supports that property. There are several important aspects:
MULTISELECTABLE
and, in MSAA, it is also EXTSELECTABLE
AccessibleSelection
interface on the container with aria-multiselectable
.aria-selected
is undefined, which indicates the element is not SELECTABLE
. It SHOULD also fail if the specified descendant is DISABLED
or READONLY
for any reason. When clearing selection on an item, set aria-selected
="false" but do not remove the attribute, so that it is still SELECTABLE
.aria-selected
changes on a descendant, as follows:Scenario | MSAA/IA2 | UI Automation | ATK/AT-SPI |
---|---|---|---|
Toggle aria-selected | EVENT_OBJECT_SELECTIONADD /EVENT_OBJECT_SELECTIONREMOVE on the current container + EVENT_OBJECT_STATECHANGE on the item | SelectionItem Control Pattern ; ElementSelected , ElementRemovedFromSlection , ElementAddedToSelection | object::selection_changed + atk_object_notify_state_change on the item |
Selection follows focus | EVENT_OBJECT_SELECTION then state change event on newly focused item, but arrange events so state change does not occur on focused item, to avoid extra selection change announcements | FocusChangedEvent should fired but individual selection event may not happen, to avoid redundancy. | object:selection_changed + atk_object_notify_state_change , but arrange events so state change does not occur on focused item, to avoid extra selection change announcements |
Select or deselect many items at once: | EVENT_OBJECT_SELECTIONWITHIN is all that is necessary. The state change events MAY be trimmed out for performance. | Selection Control Pattern Invalidated event can be used when the container has bulk of changes or when an exact selection is not clear. | object:selection_changed . The state change events MAY be trimmed out for performance |
This section is normative.
frame
and iframe
elementsComputing the accessible name for an outer document accessible:
Computing the accessible name for an inner document accessible:
aria-labelledby
from the <frame> or <iframe>. If the name is still empty, use the title attribute from the <frame> or <iframe>.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.Computing the accessible description for an inner document accessible:
aria-describedby
from the <frame> or <iframe>.aria-describedby
on the document's root WAI-ARIA node.Computing container-foo on any node in a sub document: For container-live
, container-atomic
, container-relevant
, and container-busy
, inner nodes override outer nodes from within the same document, because the inner subtree is the more relevant context. However, outer documents override inner documents, because the outer document author may be different and may wish to define the context for a live iframe. Therefore:
aria-live
, aria-atomic
, aria-relevant
, and aria-busy
into the container-[property] object attributeComputing other properties for an inner document accessible:
aria-selected
, aria-valuenow
, aria-valuetext
, aria-activedescendant
), use the WAI-ARIA markup on the root WAI-ARIA node onlySupport for attribute selectors MUST include WAI-ARIA attributes. For example, .fooMenuItem['aria-haspop=true'] would select all elements with class "fooMenuItem", and WAI-ARIA attribute "aria-haspopup
" with value true. The presentation MUST be updated for dynamic changes to WAI-ARIA attributes. This allows authors to match styling with WAI-ARIA semantics.
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:
aria-activedescendant
being a DOM-descendant of the element with the relation.checkbox
actually behaves like a checkbox.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:
If a WAI-ARIA property contains an unknown or disallowed value, expose to platform accessibility APIs as follows:
If a required aria property for a given role is missing, supply a default value as follows:
WAI-ARIA role | Required State/Property | Default value |
---|---|---|
checkbox | aria-pressed | undefined |
combobox | aria-expanded | undefined |
slider | aria-valuemax | 0 |
slider | aria-valuemin | 0 |
slider | aria-valuenow | ? |
spinbutton | aria-valuemax | 0 |
spinbutton | aria-valuemin | 0 |
spinbutton | aria-valuenow |
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.
This section is normative.
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.
An visible user interface object whose basic accessibility is exposed to assistive technology.
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.
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:
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.
An abstract type of object.
The DOM node currently traversed in order to compute the text alternative.
When computing the text alternative, the text alternative that has been computed up until arrival at the current DOM node.
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.
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.
Indicates that the element is not visible or perceivable to any user.
Content provided for information purposes and not required for conformance. Content required for conformance is referred to as normative.
the accessible object representing the root WAI-ARIA node for the spawned document. It is a child of the outer document accessible.
Required for conformance. By contrast, content identified as informative or "non-normative" is not required for conformance.
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.
the accessible object representing the <frame>/<iframe>
Presentable to users in ways they can sense. References in this document relate to WCAG 2 Principle 1; content must be perceivable [WCAG20].
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.
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.
the <body> or <frameset> in HTML, or the document element in all other languages.
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.
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.
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.
An element specified in a WAI-ARIA relation. For example, in aria-controls
=”elem1”, “elem1” is the target element.
Any software that retrieves and renders web content for users, such as web browsers, media players, plug-ins, and other programs including assistive technologies.
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.
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).
The following people contributed to the development of this document.
Special thanks to Aaron Leventhal for effort and insight as he implemented a working prototype of accessibility API bindings. Special thanks to Al Gilman for his work while chair of the PFWG in bringing the ARIA technology to fruition.
Simon Bates, Chris Blouch (AOL), Judy Brewer (W3C/MIT), Christian Cohrs, Donald Evans (AOL), Becky Gibson (IBM), Alfred S. Gilman, Andres Gonzalez (Adobe), Jeff Grimes (Oracle), Barbara Hartel, Earl Johnson (Sun), Jael Kurz, Aaron Leventhal (IBM Corporation), Alex Li (SAP), Linda Mao (Microsoft), Shane McCarron (ApTest), Lisa Pappas (Society for Technical Communication (STC)), Dave Pawson (RNIB), Marc Silbey (Microsoft Corporation), Henri Sivonen (Mozilla), Vitaly Sourikov, Mike Squillace (IBM), Ryan Williams (Oracle), Tom Wlodkowski.
This publication has been funded in part with Federal funds from the U.S. Department of Education, National Institute on Disability and Rehabilitation Research (NIDRR) under contract number ED05CO0039. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.