Skip to content

Latest commit

 

History

History
104 lines (69 loc) · 5.73 KB

accessibility-label.md

File metadata and controls

104 lines (69 loc) · 5.73 KB

Accessibility label

An accessibility label helps users of assistive technologies to identify elements on the screen. The accessibility label is conveyed to assistive technologies. Accessibility labels are announced by the screen reader and presented visually by voice control.

WCAG

Relates to 1.1.1

Android

On Android, you can use the contentDescription attribute to set an accessibility label.

You can also pass any kind of Span for greater control over pronunciation. For example, you can set a language by using LocaleSpan.

If another element is used to display the label, you can link the label by using the labelFor attribute.

// Set accessibility label
element.contentDescription = "Appt"

// Set accessibility label in Dutch language
val locale = Locale.forLanguageTag("nl-NL")
val localeSpan = LocaleSpan(locale)

val string = SpannableString("Appt")
string.setSpan(localeSpan, 0, string.length, Spanned.SPAN_INCLUSIVE_INCLUSIVE)

element.contentDescription = localeSpan

// Link visual label to field
textView.setLabelFor(R.id.editText)

iOS

On iOS, you can use the accessibilityLabel property to set an accessibility label.

You can also use the attributedAccessibilityLabel property for greater control over pronunciation. For example, spell out each character with .accessibilitySpeechPunctuation or set a language using .accessibilitySpeechLanguage.

The accessibility label should be as short as possible, while still being intuitive. When long labels cannot be avoided, you should use accessibilityUserInputLabels to provide alternative labels. The primary label is first in the array, optionally followed by alternative labels in descending order of importance.

If another element is used to display the label, you can link the label by setting isAccessibilityElement to false and setting accessibilityLabel to the value of the label.

// Set accessibility label
element.accessibilityLabel = "Appt"

// Set accessibility label with Dutch speech engine
element.attributedAccessibilityLabel = NSAttributedString(
  string: "Appt", 
  attributes: [.accessibilitySpeechLanguage: "nl-NL"]
)

// Set accessibility label for controls
element.accessibilityUserInputLabels = ["Appt", "Alternative"]

// Link visual label
label.isAccessibilityElement = false
element.accessibilityLabel = label.text

Flutter

In Flutter, the semanticsLabel property is used as accessibility name.

You can also use the attributedLabel property for greater control over pronunciation. For example, spell out each character with SpellOutStringAttribute or set a language using LocaleStringAttribute.

For even more control, you can use the Semantics widget. For example, if you want to ignore the semantics of underlaying widgets, you can set the excludeSemantics attribute to true.

Control(
  semanticsLabel: 'Appt'
)

Semantics(
  label: 'Appt',
  attributedLabel: AttributedString('Appt', attributes: [
    SpellOutStringAttribute(range: const TextRange(start: 0, end: 3))
  ]),
  excludeSemantics: true;
);

React Native

In React Native, you can set an accessibility label by using the accessibilityLabel prop.

<Control
  accessibilityLabel="Appt" />

Xamarin

In Xamarin Forms, you can set an accessibility label by using the AutomationProperties.Name property.

If another element is used to display the label, the AutomationProperties.LabeledBy property be used to link a label. Unfortunately, LabeledBy only works on Android.

As an alternative, you can link a label by setting IsInAccessibleTree to false and setting AutomationProperties.Name the value of the label.

<Control 
  AutomationProperties.Name="Appt" />