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

aria-activedescendant

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.

aria-atomic

"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.

aria-autocomplete

"inline", "list", "both", "none" (default)

Not applicable

This property is not currently supported.

aria-busy

"true", "false" (default)

Not applicable

This property is not currently supported.

aria-checked

"true", "false", "mixed", "undefined" (default)

Toggle.ToggleState

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.

aria-controls

ID Reference List

ControllerFor

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.

aria-describedby

ID Reference List

DescribedBy

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.

aria-disabled

"true", "false" (default)

IsEnabled

You can use this property without an ARIA role. UI Automation maps "true" to IsEnabled=false, and "false" to IsEnabled=true.

aria-dropeffect

Zero or more of: "copy", "move", "link", "execute", "popup", "none" (default)

Not applicable

This property is not currently supported.

aria-expanded

"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

FlowsTo, FlowsFrom

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.

aria-grabbed

"true", "false", "undefined" (default)

Not applicable

This property is not currently supported.

aria-haspopup

"true", "false" (default)

Not applicable

This property has no effect other than to update the AriaProperties property.

aria-hidden

"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.

aria-invalid

"grammar", "false" (default), "spelling", "true"

Not applicable

This property is not currently supported.

aria-label

String

Name

This property has precedence over other HTML properties that also set the Name of the element, such as the TITLE and ALT properties.

aria-labelledby

ID Reference List

Name

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.

aria-level

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.

aria-live

"off" (default), "polite", "assertive"

LiveSetting

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".

aria-multiline

"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.

aria-multiselectable

"true", "false" (default)

Selection.CanSelectMultiple

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.

aria-orientation

"vertical", "horizontal" (default)

Orientation

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.

aria-owns

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.

aria-posinset

Integer >= 1

LegacyIAccessible.Description

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.

aria-pressed

"true", "false", "mixed", "undefined" (default)

Toggle.ToggleState

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

aria-readonly

"true", "false" (default)

Value.IsReadOnly

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.

aria-relevant

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.

aria-required

"true", "false" (default)

Selection.IsSelectionRequired

This property currently applies to the "combobox", "radiogroup", "tablist", and "listbox" roles. UI Automation maps "true" to IsSelectionRequired=true; otherwise, IsSelectionRequired=false.

aria-selected

"true", "false", "undefined" (default)

Not applicable

This property is not currently supported.

aria-setsize

Integer >= 1

LegacyIAccessible.Description

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.

aria-sort

"ascending", "descending", "none" (default), "other"

ItemStatus

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.

aria-valuemax

Number

RangeValue.Maximum

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.

aria-valuemin

Number

RangeValue.Minimum

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.

aria-valuenow

Number

RangeValue.Value

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.

aria-valuetext

String

Value.Value

You can apply this property only to descendants of the role "range" ("progressbar", "scrollbar", "slider", and "spinbutton"), and to the roles "combobox" and "link".

Mapping HTML and ARIA properties to UI Automation

UI Automation