Mapping ARIA properties to UI Automation
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
The table in this section shows how Accessible Rich Internet Applications (ARIA) properties map to Microsoft UI Automation properties. The following notes pertain to the table:
- The UI Automation AriaProperties property specifies an ARIA property and corresponding value in this format: "property=value;". Note that UI Automation doesn't include the "aria-" prefix in the names of ARIA properties. To specify multiple ARIA properties, AriaProperties uses this format: "property1=value1; property2=value2; …".
- HTML elements that do not appear in the UI Automation tree do not appear even if they have an ARIA property (but no ARIA role).
ARIA
UI Automation
Property
Value
Properties of this element
Notes
ID Reference
Not applicable
All descendants of the element have the IsKeyboardFocusable and HasKeyboardFocus properties set to true, even if the element does not include an ARIA role.
"true", "false" (default)
Not applicable
You can apply this property to any element. Only the AriaProperties property is updated. The information in the aria-atomic property is significant only in the context of live regions, and can be parsed and used by assistive technology applications accordingly.
"inline", "list", "both", "none" (default)
Not applicable
This property is not currently supported.
"true", "false" (default)
Not applicable
This property is not currently supported.
"true", "false", "mixed", "undefined" (default)
UI Automation maps "undefined" to ToggleState=Off, and maps "mixed" to ToggleState=Indeterminate. Currently, the mapping works only if the role attribute is set to "checkbox". The role must be explicitly defined.
ID Reference List
You can use this property without an ARIA role, and the referenced elements don't need to define an ARIA role. The ControllerFor property points to the referenced element. If the element doesn't appear in the UI Automation tree, such as a DIV element without an ARIA role, the ControllerFor property is still supported but will be null. If the value of this property is a list of reference IDs separated by spaces, the ControllerFor property points only to IDsthe first element in the list. If the reference are separated by commas or semicolons, the ControllerFor property is supported but is empty. You can define multiplearia-controls each with different values, but only the first aria-controls is taken into account.
ID Reference List
You can use this property without an ARIA role, and the referenced elements don't need to define an ARIA role. The DescribedBy property points to the referenced element. If the element doesn't appear in the UI Automation tree, such as a DIV element without an ARIA role, the DescribedBy property is still supported but will be null. If the value of this property is a list of reference IDs separated by spaces, the DescribedBy property points only to the first element in the list. If the reference IDs are separated by commas or semicolons, the DescribedBy property is supported but is empty. You can define multiple aria-controls each with different values, but only the first aria-controls is taken into account.
"true", "false" (default)
You can use this property without an ARIA role. UI Automation maps "true" to IsEnabled=false, and "false" to IsEnabled=true.
Zero or more of: "copy", "move", "link", "execute", "popup", "none" (default)
Not applicable
This property is not currently supported.
"true", "false", "undefined" (default)
ExpandCollapse.ExpandCollapseState
Currently, this property applies to all descendants of "input", "range", "command", and "section", with the following exceptions:
- All abstract roles.
- All descendants of "landmarks" (except "application"), "article", "definition", "log", "math", "note", and "timer".
UI Automation maps "true" to ExpandCollapseState=Expanded, "false" to ExpandCollapseState=Collapsed, and "undefined" to ExpandCollapseState=LeafNode.
aria-flowto, -ms-aria-flowfrom
ID Reference List
You can use these properties without an ARIA role, and the referenced elements don't need to define an ARIA role. The FlowsTo or FlowsFrom property points to the referenced element. If the element doesn't appear in the UI Automation tree, such as a DIV element without an ARIA role, the FlowsTo or FlowsFrom property is still supported but will be null. If the value of this property is a list of reference IDs separated by spaces, the FlowsTo or FlowsFrom property points only to the first element in the list. If the reference IDs are separated by commas or semicolons, the FlowsTo or FlowsFrom property is supported but is empty. You can define multiple aria-flowto or -ms-aria-flowfrom properties, each with different values, but only the first property is taken into account.
"true", "false", "undefined" (default)
Not applicable
This property is not currently supported.
"true", "false" (default)
Not applicable
This property has no effect other than to update the AriaProperties property.
"true", "false" (default)
Not applicable
An element with this property set to "true" does not appear in the UI Automation tree, and neither do the descendants.
"grammar", "false" (default), "spelling", "true"
Not applicable
This property is not currently supported.
String
This property has precedence over other HTML properties that also set the Name of the element, such as the TITLE and ALT properties.
ID Reference List
The UI Automation Name property for this element takes the value of the Name property of the referenced element. The UI Automation LabeledBy property is never used. You shouldn't use the aria-label and aria-labelledby properties at the same time, but if you do, aria-labelledby takes precedence.
Integer >= 1
Not applicable
Although you can apply this property to any element, it has no effect other than to update the AriaProperties property. Also, you can use this property without an ARIA role.
"off" (default), "polite", "assertive"
If an element includes this property, UI Automation sets the LiveSetting property of the element to "off" unless the element has the "alert", "log", or "status" roles. If an element that has the aria-live property set to "polite" or "assertive", the element becomes a live region. Any change in a live region causes UI Automation to fire LiveRegionChangedevents if the aria-busy property is set to "false".
"true", "false" (default)
Not applicable
Although you can apply this property to any element, it has no effect other than to update the AriaProperties property. Also, you can use this property without an ARIA role.
"true", "false" (default)
UI Automation maps "true" to CanSelectMultiple=true; otherwise, CanSelectMultiple=false. Although you can apply this property to any HTML element or ARIA role (which causes the AriaProperties property to be updated accordingly), the CanSelectMultiple property is updated only if the element already supports the Selection control pattern.
"vertical", "horizontal" (default)
You can apply this property to any element. UI Automation maps "horizontal" to Orientation=1, and "vertical" to Orientation=2. If the element doesn't include the aria-orientation property, UI Automation sets the Orientation property to 0 except for elements that map as Text controls that have no children.
ID Reference List
Not applicable
You can apply this property to any element. UI Automation maps the elements that are referenced by this property as children of the current element. Use this property with caution because it can cause UI Automation to build the automation tree incorrectly.
Integer >= 1
You can apply this property to any element, and you can use it without an ARIA role. UI Automation updates the LegacyIAccessible.Description property to take the form X of Y, where X is the aria-posinset value and Y is the aria-setsize value; and if X is less than one, or if X is greater than Y, LegacyIAccessible.Description will be empty.
"true", "false", "mixed", "undefined" (default)
This property applies only to an element whose role is explicitly defined as "button". UI Automation does the following mapping:
- "true" maps to ToggleState=On
- "false" maps to ToggleState=Off
- "mixed" maps ToggleState=Indeterminate
- "undefined" maps to ToggleState=Off
"true", "false" (default)
UI Automation maps "true" to IsReadOnly=true; otherwise, IsReadOnly=false. Although you can apply this property to any HTML element or ARIA role (which causes the AriaProperties property to be updated accordingly), the IsReadOnly property is updated only if the element already supports the Value control pattern.
Zero or more of: "additions", "removals", "text", "all", "additions text"
Not applicable
You can apply this property to any element. Only the AriaProperties property is updated. The information in the aria-relevant property is significant only in the context of live regions, and can be parsed and used by assistive technology applications accordingly.
"true", "false" (default)
This property currently applies to the "combobox", "radiogroup", "tablist", and "listbox" roles. UI Automation maps "true" to IsSelectionRequired=true; otherwise, IsSelectionRequired=false.
"true", "false", "undefined" (default)
Not applicable
This property is not currently supported.
Integer >= 1
You can apply this property to any element, and you can use it without an ARIA role. UI Automation updates the LegacyIAccessible.Description property to take the form X of Y, where X is the aria-posinset value and Y is the aria-setsize value; and if X is less than one, or if X is greater than Y, LegacyIAccessible.Description will be empty.
"ascending", "descending", "none" (default), "other"
You can apply this property only to elements that map to HeaderItem controls; that is TH elements, and elements that include the "columnheader" and "rowheader" roles. UI Automation maps "ascending" to ItemStatus="Ascending", and "descending" to ItemStatus="Descending". If "none", the ItemStatus property is not supported.
Number
You can apply this property only to descendants of elements with a role of "range" ("progressbar", "scrollbar", "slider", and "spinbutton"). If aria-valuemax is not specified, RangeValue.Maximum=0.
Number
You can apply this property only to descendants of elements with a role of "range" ("progressbar", "scrollbar", "slider", and "spinbutton"). If aria-valuemin is not specified, RangeValue.Minimum=0.
Number
You can apply this property only to descendants of elements with a role of "range" ("progressbar", "scrollbar", "slider", and "spinbutton"). If aria-valuenow is not specified, RangeValue.Value is not supported.
String
You can apply this property only to descendants of the role "range" ("progressbar", "scrollbar", "slider", and "spinbutton"), and to the roles "combobox" and "link".