This spec has been deprecated, please see the Accessibility Object Model Explainer and index to specs for up to date information.


This document is the spec for Phase 2 of the Accessibility Object Model spec. For background, please refer to the Accessibility Object Model Explainer for the background and motivation, and then Phase 1.

Phase 2: Accessible Actions

In this phase, we extend AccessibleNode so that it's also an EventTarget. AccessibleNodes receive special accessibility input events or accessible actions that represent explicit intents to control the user agent via an accessibility API

          interface AccessibleNode : EventTarget {

Accessibility input events are needed for two reasons.

          interface AccessibleSetValueEvent : Event {
            attribute DOMString value;
Accessibility event table
event name type valid roles fallback behavior (see below)
"accessibleclick" Event all roles Fire "click" event on DOM node
"accessiblefocus" Event all roles Focus the associated DOM element
"accessiblesetvalue" AccessibleSetValueEvent "combobox", "scrollbar", "slider", "textbox" Change value of INPUT or TEXTAREA element
"accessibleincrement" Event "scrollbar", "slider" Change value of INPUT type="range", otherwise fire "keypress" with a RightArrow key code
"accessibledecrement" Event "scrollbar", "slider" Change value of INPUT type="range", otherwise fire "keypress" with a LeftArrow key code
"accessibleselect" Event "cell", "option" Change selectedIndex of SELECT otherwise fire "click" event
"accessiblescrollintoview" Event all roles scroll DOM node into view
"accessibledismiss" Event all roles fire "keypress" with a Escape key code
"accessiblecontextmenu" Event all roles fire "keypress" with a Context Menu key code, or simulate a right-click on the target node.

Accessibility input events go through capture and bubble phases, just like DOM events. The only difference is that the capture and bubble phases happen entirely in the accessibility tree. If the event is not canceled (by calling preventDefault()) after completely going through the capture and bubble phases in the accessibility tree, the event executes its fallback behavior, as defined in the accessibility attribute table.

When an event's fallback behavior involves firing a DOM event, the event's target will be the associated DOM node of the target AccessibleNode, or the associated DOM node of the nearest ancestor of the target AccessibleNode that has one. Fallback DOM events will go through capture and bubble phases just like any other DOM events.

As an example, suppose an accessible click event is received on a button. Here's the sequence of what will occur:

  1. Capturing event listeners are called, starting with the root of the accessibility tree, and continuing along the ancestor chain until reaching the target AccessibleNode in the accessibility tree.
  2. If none of the capturing event listeners stop propagation, normal (non-capturing) event listeners on the target AccessibleNode are called, and if stopPropagation() is not called, the event bubbles up to all event listeners on ancestors of the target.
  3. After capture and bubble phases in the accessibility tree, if preventDefault() was not called, the event's fallback behavior is triggered. In this case it fires a DOM "click" event on the targer AccessibleNode's associated DOM node, going through capture and bubble phases in the DOM tree.

The following were considered as possible accessibility input events but were deferred for a future version of the spec. Please file a bug if you have a compelling use case for one of these.

Platform compatibility table

The following table shows proposed accessible actions and the native actions or methods they correspond to on each platform with an accessibility API.

When an action maps cleanly to a method or action on all or nearly all platforms, that's good evidence that it's a good candidate for an accessible action in the Accessibility Object Model. When an action doesn't map cleanly, that means it's potentially more risky for compatibility.

In the table below, Tier 1 actions appear to have broad support across almost all platforms. Tier 2 actions are supported on at least 2 unrelated platforms. The remaining native actions are shown below.

Tier Action Mac iOS MSAA + IAccessible2 UIA Android ATK
1 Activate AXPressAction accessibilityActivate IAccessible::accDoDefaultAction InvokeProvider::Invoke
ACTION_CLICK atk_action_do_action
1 Focus set AXFocused true IAccessible::accSelect SELFLAG_TAKEFOCUS ACTION_FOCUS
1 ScrollByPage accessibilityScroll IScrollProvider::Scroll ACTION_SCROLL_BACKWARD
1 ScrollIntoView AXScrollToVisible,
set AXVisibleCharacterRange
IScrollItemProvider::ScrollIntoView ACTION_SHOW_ON_SCREEN
1 SecondaryClick AXShowMenuAction accessibilityPerformMagicTap ACTION_LONG_CLICK
1 Select AXPickAction
set AXSelected,
set AXSelectedChildren
set AXSelectedRows
ACTION_SELECT atk_selection_add_selection
1 SetNumericValue set AXValue IAccessibleValue::setCurrentValue IRangeValueProvider::SetValue ACTION_SET_PROGRESS atk_value_set_value
1 SetTextValue set AXValue
ACTION_SET_TEXT atk_editable_text_set_text_contents
2 Cancel AXCancelAction accessibilityPerformEscape IWindowProvider::Close ACTION_DISMISS
2 Collapse IExpandCollapseProvider::Collapse ACTION_COLLAPSE
2 CopyText IAccessibleEditableText::copyText ACTION_COPY atk_editable_text_copy_text
2 CutText IAccessibleEditableText::cutText ACTION_CUT atk_editable_text_cut_text
2 Decrement AXDecrementAction accessibilityDecrement
2 Expand IExpandCollapseProvider::Expand ACTION_EXPAND
2 Increment AXIncrementAction accessibilityIncrement
2 InsertText IAccessibleEditableText::insertText atk_editable_text_insert_text
2 PasteText IAccessibleEditableText::pasteText ACTION_PASTE atk_editable_text_paste_text
2 ReplaceText IAccessibleEditableText::replaceText atk_editable_text_set_text_contents,
2 DeleteText IAccessibleEditableText::deleteText atk_editable_text_delete_text
2 ScrollToPoint IAccessible2::scrollToPoint
IScrollProvider::SetScrollPercent ACTION_SCROLL_TO_POSITION
2 SetSelectedTextRange set AXSelectedText
set AXSelectedTextMarkerRange
set AXSelectedTextRange
3 SetTextAttributes IAccessibleEditableText::setAttributes atk_editable_text_set_run_attributes

Actions unique to macOS:

Actions unique to UIA

Actions unique to Android:

Privacy concerns

This phase raises some potential privacy concerns. If a web app receives an accessibility input event, it now knows for a fact that assistive technology or some other client of a native accessibility API is running. There is potential that this could be used to track or discriminate against some users.

To address these concerns, a web site should not be able to receive these events until the user has explicitly opted in to allow those events to be received by that web site.

A new web permission should be added, "accessibility-events", with a default value of "ask".

A website can add event listeners to AOM nodes without triggering any permission checks. However, as soon as an accessibility event would trigger an AOM event listener, at that point the user is prompted to see if they want to enable the site to be able to listen for accessibility events.

Example permission dialog text: "The site would like to respond to accessibility events." [Allow] [Block]

Because of the potential privacy concerns, maybe this permission should only be available on secure sites? Many other permissions have gone that route.

Phase 3: Virtual Accessibility Nodes

See Phase 3

Phase 4: Computed Accessibility Tree

See Phase 4