UWP XAML: Setting the accessible name on a list

This article is referenced directly by Microsoft Accessibility Insights for Windows. Microsoft Accessibility Insights for Windows can help spotlight many accessibility issues in UI, and guide you to the relevant UI framework-specific code sample to help you resolve the issue. Learn more about Microsoft Accessibility Insights for Windows.

Problem

When a screen reader moves into a list and is configured to announce both the list item and the name of the list containing the item, its announcement does not include the name of the list. The fact that my customer is not made aware of exactly which list they've encountered, can disrupt the flow of completing their task.

Suggested Fix

The purpose of a control is conveyed through the control's Name property as exposed through the UI Automation (UIA) API. The Name property must be accurate, concise, unambiguous and localized. By default for some types of UWP XAML controls, the controls' Text or Content property is repurposed as the UIA Name property. These properties are not available for ListBox or ListView controls, and so special attention must be paid to ensure an appropriate UIA Name property is exposed by the control.

If the list has an associated TextBlock control which describes the purpose of the list, consider having the list's UIA Name property set from the TextBlock's text. This approach avoids the need to add a localized string specifically for the accessible name of the list.

If the list has no associated TextBlock control, consider adding a TextBlock in order for your sighted customers to efficiently learn of the purpose of the list, and then reference the TextBlock as described above. If that is not practical, explicitly set an accessible name on the list through its AutomationProperties.Name property.

The approaches shown below work for both UWP XAML ListBox and ListView controls.

Note

While setting the accessible properties of a control is typically achieved through markup, in some situations it could be achieved through code-behind. Setting the accessible properties of a control in code-behind

Code Sample 1: Setting the List's accessible name from a nearby TextBlock.

The localization steps for strings exposed through UIA are the same as that used for strings shown visually in the UWP XAML app. In this example the strings are associated through use of x:Uid.

<TextBlock Name="ServerNamesLabel" x:Uid="ServerNamesLabel" />
<ListView AutomationProperties.LabeledBy="{Binding ElementName=ServerNamesLabel}" ... />

<!-- In the above example, the associated localized resource string might 
     be as follows:
  <data name="ServerNamesLabel.Text" xml:space="preserve">
    <value>Server names:</value>
  </data>
-->

Code Sample 2: Setting the List's accessible name explicitly because it has no associated TextBlock.

<ListView x:Uid="ServerNamesList" ... />

<!-- In the above example, the associated localized resource string might 
     be as follows. Note that the name should not include the control type, 
	 so the name would not include the text "list" in this case.
  <data name="ServerNamesList.AutomationProperties.Name" xml:space="preserve">
    <value>Server names</value>
  </data>
-->