UWP XAML: Setting the accessible name on a custom control

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 to the custom control, its announcement does not include the purpose of the custom control. As such, my customer may be blocked from completing their task.

Suggested Fix

The purpose of a control is conveyed through the control's UI Automation Name property as exposed through the UI Automation (UIA) API. The Name property must be accurate, concise, unambiguous and localized. If the custom control does not expose an appropriate accessible name by default, then specific action must be taken to ensure an appropriate UIA Name property is exposed by the control.

Important

The UIA Name property conveys the purpose of the control. The UIA LocalizedControlType property conveys the type of control. As such, the type of control should not be conveyed through the UIA Name property. For example, say an Alarms app presents a custom control representing an alarm. All alarms shown in the app might expose a LocalizedControlType property of "Alarm", but expose specific localized Name properties of (say) "Submit report", "Weekly status meeting", and so on.

If the custom control has an associated TextBlock control which describes the purpose of the custom control, consider having the custom control'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 custom control.

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

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 custom control'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 x:Uid="SubmitReportAlarmControlLabel" Name="SubmitReportAlarmControlLabel" />
<local:AlarmControl AutomationProperties.LabeledBy="{Binding ElementName=SubmitReportAlarmControlLabel}" />

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

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

<!-- In the XAML markup. -->
<local:AlarmControl x:Uid="SubmitReportAlarmControl" />

<!-- In the above example, the associated localized resource string might 
     be as follows:
  <data name="SubmitReportAlarmControl.AutomationProperties.Name" xml:space="preserve">
    <value>Submit Report</value>
  </data>
 -->