Basic accessibility support

TheRealJasonSmithTheRealJasonSmith USXamarin Team Xamurai
edited January 2017 in Xamarin.Forms


Xamarin.Forms currently lacks first party support for basic a11y functions like the identifier and hints. This proposal is intended to add support for those features on all platforms. Due to the desire to cover A11Y in the best way possible for all platforms, properties are added that are relatively platforms specific and are just ignored on platforms which don't support them.

This feature is not intended to fully cover a11y navigation as that API is significantly more complex.

API Changes

Option 1: Direct Inclusion

public class Element
    public string AccessibilityIdentifier { get; set; } // BP
    public string AccessibilityHint { get; set; } //BP
    // other properties as described below


  • Shows up in intellisense easily
  • Immediately clear and obvious
  • Potentially more likely to get more developers to use this


  • Could lead to API bloat as A11y API grows. (accessibilityLabel, accessibilityHint, accessibilityValue, accessibilityLanguage, accessibilityTraits... etc)
  • Very strongly bound to VisualElement, making future changes more difficult

Option 2: Attached Property

public static class Accessibility
    public static readonly BindableProperty Identifier; // attached with get_set on Element
    public static readonly BindableProperty Hint; // attached with get_set on Element
    // other properties as described below


  • Does not bloat API at all
  • Easily extended with new features
  • Easily revised without much difficulty (deprecation/replacement of API becomes easier)


  • Harder to discover
  • Potentially fewer developers using due to discovery issues

Supported Properties


Basic name for element. Contains a short (couple word) description of the element.

public static void SetName (Element element, string name)


Contains a longer description of the element if the Name is not able to fully encapsulate the intended use of the element.

public static void SetHint (Element element, string hint)


Indicates whether the element is available to an accessible app.

public static void SetIsInAccessibleTree (Element element, bool value)


A pointer to a different element which is intended to label this element. For example, a label placed next to a Slider labeling what the slider represents.

public static void SetLabeledBy (Element element, Element labeledBy)

May not be possible to support on all platforms?

Issues with AutomationId

Xamarin.Forms.Element already contains an AutomationId property which due to the nature of automation on some platforms maps to a11y properties already. A solution to properly dealing with this conflict is not yet known.

Exploration of A11y API's on platforms

Difference between UIAccessibilityLabel and UIAccessibilityIdentifier?
Android ContentDescription == UIAccessibilityIdentifier or at least close enough?
UWP AutomationProperties.Name == UIAccessibilityIdentifier && ContentDescription?

Initial mapping

Forms Property Android API iOS API UWP API
Accessibility.Name SetContentDescription UIAutomationIdentifier AutomationProperties.Name
Accessibility.Hint UIAutomation.Hint AutomationProperties.HelpText
Accessibility.LabeledBy LabelFor AutomationProperties.LabeledBy
Accessibility.IsInAccessibleTree Focusable IsAccessibilityElement AutomationProperties.AccessibilityView

Android at first blush appears to be missing a Hint API, or rather munges the Hint and the Name into ContentDescription.


Intended Use Case

A potential user of a Xamarin.Forms app with a visual disability, they should be able to navigate the application using the built in screen reading features of the native OS. Developers should be able to add correct names and hints that the screen reader understands without having to resort to external libraries.

My initial thoughts are that proposal 2 is the best idea for us here. We still need to flush out other properties that might need to exist in here and I need to dig into the iOS a11y support much deeper since I am almost 100% positive I am misinterpreting some of their docs on the matter. As a non-a11y user this is something that we are really looking for feedback on from people who not only have developed a11y software in the past, but have actually used the features for their own needs.


Completed · Last Updated

Merged with


  • ChaseFlorellChaseFlorell CAInsider, University mod
    edited January 2017

    IMHO, I think proposal 2 is really the best approach here. There is the potential for far too many properties to exist on each element, so attaching Accessibility to an element is far better.

    <Label Text="Foo">
        <Label.Accessibility Identifier="FooId" Name="FooName" Hint="FooHint" />
  • TheRealJasonSmithTheRealJasonSmith USXamarin Team Xamurai

    Actually that represents a third proposal, where Accessibility is a non static class which is then attached to an Element.

  • ChaseFlorellChaseFlorell CAInsider, University mod

    @TheRealJasonSmith said:
    Actually that represents a third proposal, where Accessibility is a non static class which is then attached to an Element.

    Oh, didn't read it that closely. With your Option 2 proposal, how would you handle it via XAML?

  • TheRealJasonSmithTheRealJasonSmith USXamarin Team Xamurai
    <Label Accessibility.Name="FooName" Accessibility.Hint="The labels hint here" />
  • ChaseFlorellChaseFlorell CAInsider, University mod

    @TheRealJasonSmith with your experience within the innards of the product, do you see a benefit of one over another?

  • TheRealJasonSmithTheRealJasonSmith USXamarin Team Xamurai

    The fewer objects the better is my general experience. Also by having the properties be their own thing rather than a bag, its easier to do incremental updates at runtime.

  • Josh.1093Josh.1093 USUniversity ✭✭

    @TheRealJasonSmith said:
    Android at first blush appears to be missing a Hint API, or rather munges the Hint and the Name into ContentDescription. This is almost certainly due to the

    You didn't complete this thought. It sounds like an interesting/educational one, if you'd care to edit and complete it.

  • StephaneDelcroixStephaneDelcroix USInsider, Beta ✭✭✭✭

    I prefer the second option. The discovery issue could be solved by adding a set of extensions methods (Extension Properties, where are you ?)

Sign In or Register to comment.