Mapping ARIA properties to UI Automation
Collapse the table of content
Expand the table of content

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).
ARIAUI Automation
PropertyValueProperties of this elementNotes
aria-activedescendant ID ReferenceNot applicableAll 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 applicableYou 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 applicableThis property is not currently supported.
aria-busy "true", "false" (default)Not applicableThis property is not currently supported.
aria-checked "true", "false", "mixed", "undefined" (default)Toggle.ToggleStateUI 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 ListControllerForYou 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 ListDescribedByYou 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)IsEnabledYou 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 applicableThis property is not currently supported.
aria-expanded "true", "false", "undefined" (default)ExpandCollapse.ExpandCollapseStateCurrently, 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-flowfromID Reference ListFlowsTo, 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 applicableThis property is not currently supported.
aria-haspopup "true", "false" (default)Not applicableThis property has no effect other than to update the AriaProperties property.
aria-hidden "true", "false" (default)Not applicableAn 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 applicableThis property is not currently supported.
aria-label StringNameThis 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 ListNameThe 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 >= 1Not applicableAlthough 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"LiveSettingIf 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 applicableAlthough 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.CanSelectMultipleUI 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)OrientationYou 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 ListNot applicableYou 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 >= 1LegacyIAccessible.DescriptionYou 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.ToggleStateThis 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.IsReadOnlyUI 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 applicableYou 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.IsSelectionRequiredThis 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 applicableThis property is not currently supported.
aria-setsize Integer >= 1LegacyIAccessible.DescriptionYou 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"ItemStatusYou 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 NumberRangeValue.MaximumYou 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 NumberRangeValue.MinimumYou 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 NumberRangeValue.ValueYou 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 StringValue.ValueYou can apply this property only to descendants of the role "range" ("progressbar", "scrollbar", "slider", and "spinbutton"), and to the roles "combobox" and "link".

 

Related topics

Mapping HTML and ARIA properties to UI Automation
UI Automation

 

 

Show:
© 2017 Microsoft