4.1. Focus States and Events Table

#

The following table defines the accessibility API keyboard focus states and events used in later sections of the document.

• If the context is controlling focus with tabindex, the DOM focus (document.activeElement) is in sync with the focus states and events listed in the table.
• If the context is controlling focus with aria-activedescendant, the DOM focus is separate from the focus states and events for the MSAA, and ATK/AT-SPI columns of the table.

  Note: An example is a single-selection listbox that controls focus using aria-activedescendent instead of tabindex. The option children are all marked with the focusable state in the accessibility API. As the user navigates from one option child to the next, DOM focus is maintained on the listbox parent, but the accessibility API emits a focus event and exposes the focused state for the option child that the listbox references as the active descendant.

4.2. Controlling focus with tabindex

#

Editorial Note: this section is specific to HTML only and may be moved to the HTML Implementation Guide.

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.

Note: refer to the Table of accessibility APIs for focus states and events for the rules in this section.

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

1. Where tabindex equals a negative integer, set the focusable state, but do not include the element in the sequential tab order.
2. Where tabindex="0", set the focusable state and include it in the sequential tab order.
3. Where tabindex is greater than zero, set the focusable state, and 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. Expose the element.tabIndex property for every HTML element that supports the tabindex attribute.
5. Add the focus and blur methods to the HTMLElement interface (available to script for every type of element).
6. Fire focus, blur, DOMFocusIn, and DOMFocusOut events for any element that can receive focus.
7. When a keydown event is cancelled, also cancel the keypress event.
8. Expose the focusable states for any element in the accessibility tree.
9. When any object has focus, expose the focused state. When it loses focus, remove the focused state.

4.3. Controlling focus with aria-activedescendant

#

When implementing aria-activedescendant as described below, the user agent keeps the DOM focus on the container element but communicates desktop focus events and states to the assistive technology as if the active descendant has focus. It is the responsibility of the user agent to ensure that keyboard events are processed at the container element that has DOM focus. Any keyboard events directed at the active descendant bubble up to the DOM element with focus, the container element, for processing.

The aria-activedescendant property may 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 other keys, typically arrow keys, 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. The author cannot use :focus to style the currently active descendant since actual focus is on the container.

Note: Refer to the Table of accessibility APIs for focus states and events for the rules in this section.

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 platforms that expose desktop focus or accessibility API focus separately from DOM focus, do not expose the focused state in the accessibility API for any element when it has DOM focus and also has aria-activedescendant which points to a valid ID.
3. When the aria-activedescendant attribute changes on an element that currently has DOM focus, remove the focused state from the previously focused object and fire an accessibility API desktop focus event on the new active descendant. If aria-activedescendant is cleared or does not point to an element in the current document, fire a desktop 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, apply the following accessibility API 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 HTML elements that would be focusable would already have the focusable state.
   2. Focused, whenever the container element sets aria-activedescendant to match the ID of this descendant and the container widget with aria-activedescendant has DOM focus.

4.4. Handling focus changes from the Assistive Technology

#

Assistive technologies, such as screen readers, voice input software and on-screen keyboards, might request that the keyboard focus be moved using the following accessibility APIs:

• MSAA: accSelect(SELFLAG_TAKEFOCUS)
• ATK/AT-SPI: AtkComponent::grab_focus
• Mac OS X Accessibility: Notification: AXFocusedUIElementChanged

Note: Refer to the Table of accessibility APIs for focus states and events for the rules in this section.

When an assistive technology requests a change of focus using one of the above APIs, user agents MUST do the following:

• Remove the focused state from the previously focused object.
• If the element can take 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. When it is not possible for the user agent to set DOM focus to the containing element with aria-activedescendant, the user agent MAY attempt to set DOM focus to the child element itself.
• If the current element has an ID and an ancestor with the aria-activedescendant attribute present, the user agent MUST set the accessibility API focused state and fire an accessibility API desktop focus event on the new active descendant.

Note: the inability to set DOM focus to the containing element indicates an author error.

5.1. General rules for exposing WAI-ARIA semantics

#

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

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

5.2. Conflicts between native markup semantics and WAI-ARIA

#

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

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

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

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

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

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

#

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

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

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

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

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

5.4. Role mapping

#

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

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

1. The user agent MUST use the first token in the sequence of tokens in the role attribute value which matches, on comparison, the name of any non-abstract WAI-ARIA role according to rules that are specified in the Role Mapping Table below. See Conflicts between native markup semantics and WAI-ARIA for additional information. Note that when WAI-ARIA roles override host language semantics, there are no changes in the DOM, only in the accessibility tree. In the absence of author-supplied scripts, the presence of WAI-ARIA roles might not make sense. But user agents MUST map WAI-ARIA roles even in the absence of author-supplied scripts.

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

   1. Use the rules of the host language to detect that an element has a role attribute and to identify the attribute value string for it.
   2. Separate the attribute value string for that attribute into a sequence of whitespace-free substrings by separating on whitespace.
   3. Do a comparison of the substrings to all the names of the non-abstract WAI-ARIA roles. Case-sensitivity of the comparison inherits from the case-sensitivity of the host language.
   4. Use the first such substring in textual order that matches the name of a non-abstract WAI-ARIA role for the API role mapping. See the Role Mapping Table below for details.
2. User agents MUST NOT map roles defined in the WAI-ARIA specification as "abstract" via the standard role mechanism of the accessibility API. The abstract roles are:
   • command
   • composite
   • input
   • landmark
   • range
   • roletype
   • section
   • sectionhead
   • select
   • 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 use the element name table to determine what platform accessibility API role to use according to the host language's role mapping. For , use the platform accessibility API for a text input.
   When an explicit or inherited role of presentation is applied to an element, the user agent MUST implement the rules for presentation role defined in Accessible Rich Internet Applications (WAI-ARIA) 1.0 [ARIA].
   User agents MUST expose the WAI-ARIA role string if the API supports a mechanism to do so. This allows assistive technologies to do their own additional processing of roles.

   • MSAA: not supported
   • IAccessible2: expose as an object attribute pair (xml-roles:"string")
   • UIA Express: expose as AriaRole property. The AriaRole property can also support secondary roles using a space as a separator.
   • ATK/AT-SPI: expose as an object attribute pair (xml-roles:"string")
   Platform accessibility APIs typically do not provide a vehicle to notify assistive technologies that a role has changed. Due to this and document caching, assistive technologies are unlikely to process a change in role attribute value. Authors who wish to change a role are advised by the WAI-ARIA specification to delete the associated element and its children and replace it with a new element having the appropriate role. If a role is changed, however, user agents SHOULD update the mapping in order to reflect the content in the DOM. Since assistive technologies will not know that the role has changed, user agents MAY address this error condition by treating it as removing a subtree item and inserting a new one as described in Changes to document content or node visibility.

   5.4.1. Role Mapping Table

   #

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

   Table describing mapping of WAI-ARIA roles to accessibility APIs.

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

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

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

5.5.1. State and Property Mapping Table

#

5.6.1. Name and Description

#

5.6.2. Widget Values

#

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

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

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

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

5.6.3. Relations

#

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

5.6.4. Group Position

#

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

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

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

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

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

5.8.1. State and Property Change Events

#

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

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

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

5.8.2. Changes to document content or node visibility

#

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

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

In some cases, node changes may occur where the node is not an element or has no accessible object. For example, a numbered list bullet ("12.") may have a node in the accessibility tree but not in the DOM tree. For text within a paragraph marked in HTML as , the element has a node in the DOM tree but may not have one in the accessibility tree. The text itself will of course be in the accessibility tree along with the identification of the range of text that is formatted as strong. If any of the changes described in the table above occur on such a node, user agents SHOULD compute and fire relevant text change events as described above.