Giving your XAML element an accessible name: Part 2 – Set the AutomationProperties.Name

The AutomationProperties class is a really, really handy way to set some accessibility-related properties on an element in XAML. Its Name property can mean it can take only a couple of minutes to set a localized string as the accessible name on a button, and that can make the difference between your customer wanting to use your app, or not wanting to.

So when thinking about how you’ll add an accessible name to an element, first consider setting the AutomationProperties.Name property. Exactly how you do that, depends on how you’ve defined your UI. Hopefully one of the approaches below will work for you.

1. Use the Uid of your element to have a localized resource string applied to your element 

This is similar to how you might set a string to be the visual text shown on an element.

For example:

XAML

    <Button ...

        x:Uid="IdentifyPlantButton" />

Localizable resource file

Figure 1: Visual Studio showing the set of localizable string resources in my app.

Opening the resource file as XML might show this:

    <data

      name="IdentifyPlantButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name"

      xml:space="preserve">

        <value>Identify plant</value>

        <comment>Accessible name of the Identify Plant button</comment>

    </data>

2. Bind an element’s accessible name to a view model property 

Just as visual text can be bound to view model properties, so can an element's accessible name.

    AutomationProperties.Name=

        "{Binding <your view model's accessible name property> }">

For example, say I have a button showing an image of a particular plant, and this image is set through binding to a CurrentPlant object in my view model. If the image is not purely decorative, and it’s conveying some useful information to your sighted customers, then it’s also necessary to bind the accessible name of the button to some view model property too.

Note: "Mode=OneTime" should be used in the binding if appropriate.

This binding might be done by binding the accessible name to the same view model property that’s used for binding the visual image, but different value converters are used. One converter would convert the view model property to an image, and the other to a localized string resource. For example:

    AutomationProperties.Name="{Binding CurrentPlant,

        Converter={StaticResource 

            CurrentPlantToAutomationPropertiesNameConverter}}">

Alternatively, your view model might expose a string property for the accessible name of the button, and the button binds directly to it.

    AutomationProperties.Name="{Binding CurrentPlantAccessibleName}">

If your element has a style containing a ControlTemplate, then the binding might need to be added to the ControlTemplate itself. For example:

<Style TargetType="customControls:MyControl">

    <Setter Property="Template">

        <Setter.Value>

            <ControlTemplate TargetType="customControls:MyControl">

                <Grid>

                    <Button ...

                        AutomationProperties.Name=

                            "{TemplateBinding CurrentPlantAccessibleName}" />

                </Grid>

            </ControlTemplate>

        </Setter.Value>

    </Setter>

</Style>

The accessible name of a custom control can be bound to some property specific to that control, by specifying a RelativeSource of Self. For example, in the following case the accessible name is always to be set from a custom search-related control's PlaceholderText property.

    <customControls:PlaceholderTextButton ...

        PlaceholderText="{CustomResource <Some placeholder text string>}"

        AutomationProperties.Name=

            "{Binding PlaceholderText, RelativeSource={RelativeSource Self}}" />

Tip for TextBox Headers: Binding to a RelativeSource of Self can also be useful for setting the accessible name of a TextBox from its Header, regardless of whether any view model is involved. For example, the following snippet sets the accessible name of a TextBox from its Header.

     <TextBox ...

         Header=" <Some localized string> "

         AutomationProperties.Name=

             "{Binding Header, RelativeSource={RelativeSource Self}}" />

3. Reference a localized CustomResource string in the XAML for your element 

Typically, the approaches described in #1 or #2 above will get the accessible name set on your element that your customer needs. But if for some reason you want to set a localized CustomResource string directly on the AutomationProperties.Name in your XAML, you can do that.

For example, (assuming you’ve defined your CustomResource somewhere)…

    AutomationProperties.Name=

        "{CustomResource IdentifyPlantButtonAccessibleName}">

And if a custom style is applied to your element, then an accessible name might be set through a property on that style. For example:

    <Setter

        Property="AutomationProperties.Name"

        Value="{CustomResource IdentifyPlantButtonAccessibleName}" />

Other posts in this series:

    Giving your XAML element an accessible name: Part 1 - Introduction

    Giving your XAML element an accessible name: Part 3 – Other interesting ways