4. Robust · 4.1 Compatible

4.1.2 — Name, Role, Value

Level A

Engineering guidance on this page is adapted from Appt.org (Appt Foundation), used under the CC BY-SA 4.0 license. In keeping with that license, the adapted content on this page is likewise available under CC BY-SA 4.0. "Appt" is a registered trademark of the Appt Foundation; this page is not affiliated with or endorsed by Appt.

Set accessibility name

In Jetpack Compose, the contentDescription.contentDescription()) attribute is used to set an accessibility name.

kotlin

Box(modifier = Modifier.semantics {
    contentDescription = "Appt"
}) {
    // Box content...
}

In SwiftUI, the accessibilityLabel-7rljm) property is used as accessibility name.

swift

Button {
    // Button action
} label: {
    Image(systemName: "magnifyingglass")
        // Set accessibility label
        .accessibilityLabel("Search")
}

Set accessibility role

On Android, you can use the setAccessibilityDelegate) method of ViewCompat to get a reference to AccessibilityNodeInfoCompat. This object contains many useful accessibility related methods.

You can set a role using the setRoleDescription) method. However, we recommend using the setClassName) method over setRoleDescription to support multilingual roles. For example, set Button::class.java.name if an element behaves like a button. The role will be set to Button in English, and to its respective translation in other languages.

|Element type | Class name | |---------------|------------------------------| |Button | android.widget.Button | |Checkbox | android.widget.CompoundButton| |Drop down list | android.widget.Spinner | |Edit box | android.widget.EditText | |Image | android.widget.ImageView | |Toggle button | android.widget.ToggleButton | |Radio button | android.widget.RadioButton | |Progress bar | android.widget.ProgressBar | |Value picker | android.widget.NumberPicker |

To indicate other element types, such as Switch or Tab, use setRoleDescription.

You can indicate a heading by using the setHeading) method. ViewCompat also contains a convenience method: setAccessibilityHeading).

kotlin

ViewCompat.setAccessibilityDelegate(
    element,
    object : AccessibilityDelegateCompat() {
        override fun onInitializeAccessibilityNodeInfo(
            host: View,
            info: AccessibilityNodeInfoCompat
        ) {
            super.onInitializeAccessibilityNodeInfo(host, info)

            // Button
            info.className = Button::class.java.name

            // Image
            info.className = ImageView::class.java.name
            
            // Heading
            info.isHeading = true

            // Custom
            info.roleDescription = "Custom role"
        }
    }
)

// Convenience method
ViewCompat.setAccessibilityHeading(view, true)

kotlin

if (ClassLoadingCache.checkInstanceOf(className, android.widget.EditText.class)) {
    if (node.isEnabled() && !node.isEditable()) {
        // Developers may want to provide extra information
        // when an EditText is enabled but not editable.
        return ROLE_NONE;
    } else {
        return ROLE_EDIT_TEXT;
    }
}

kotlin

ViewCompat.setAccessibilityDelegate(
    element,
    object : AccessibilityDelegateCompat() {
        override fun onInitializeAccessibilityNodeInfo(
            host: View,
            info: AccessibilityNodeInfoCompat
        ) {
            super.onInitializeAccessibilityNodeInfo(host, info)

            // EditText
            info.className = EditText::class.java.name
            info.isEditable = true
        }
    }
)

// Convenience method
ViewCompat.setAccessibilityHeading(view, true)

In Jetpack Compose you can use role to set the role of an element.

The following constants are defined for the Role:

Button): this element is a button
Checkbox): this element is checkbox with two states (checked / unchecked)
DropdownList): this element is drop down menu
Image): this element is an image
RadioButton): this element is a radio button
Switch): this element is a switch
Tab): this element is a tab which represents a single page of content using a text label and/or icon
ValuePicker: this element is a value picker and should support accessibility scroll events

For more information about the mapping, view the Role class, Role.toLegacyClassName() method and populateAccessibilityNodeInfoProperties() method in the Compose source code.

kotlin

Box(modifier = Modifier.semantics {
    role = Role.Button
})

On iOS, the accessibilityTraits attribute is used to indicate an accessibility role. The UIAccessibilityTraits structure contains all options, such as header, button, link and image, among others.

You can also combine multiple traits. For example, for a selected button you can can pass both traits as an array: [.button, .selected].

swift

element.accessibilityTraits = .button
element.accessibilityTraits = .header
element.accessibilityTraits = .link
element.accessibilityTraits = .image

element.accessibilityTraits = [.button, .selected]

In SwiftUI, you can set an accessibility role by using the accessibility traits on views. This is done by using the accessibilityAddTraits) modifier, which allows you to specify the role a view should play in the user interface. Traits can make a view act as a button, header, link, image, and more. You can also combine multiple traits to define complex roles.

swift

// Button Trait
Text("Tap Me")
    .accessibilityAddTraits(.isButton)

// Header Trait
Text("Section Header")
    .font(.headline)
    .accessibilityAddTraits(.isHeader)

// Link Trait
Text("Visit Website")
    .foregroundColor(.blue)
    .underline()
    .accessibilityAddTraits(.isLink)

// Image Trait
Image(systemName: "star.fill")
    .accessibilityAddTraits(.isImage)

// Combined Traits: Button and Selected
Text("Selected Button")
    .accessibilityAddTraits([.isButton, .isSelected])

swift

// View containing an image that acts as a decorative element
Image(systemName: "envelope")
    .accessibilityRemoveTraits(.isImage)

For some widgets in Flutter, the role is assignd automatically. This happens, for example, with Flutter's buttons and text fields. If this is not the case, you can use Semantics to indicate a role. The Semantics constructor contains all available options, such as button, header, link and image, among others.

dart

Semantics(
  button: true,
  header: true,
  link: true,
  image: true,
  child: Widget(...)
);

In React Native you can use the accessibilityRole prop to set the accessibility role of an element. Available roles include button, header, link and image, among others.

jsx

<Pressable 
  accessibilityRole="button|header|link|image" />

In MAUI, there is no built-in support for setting an accessibility role.

By intercepting the handler changed event, you can change the role of a custom component.

HandlerChanged event in XAML:

xml

<StackLayout>
  <BindableLayout.ItemTemplate>
    <DataTemplate>
      <controls:BorderedFrame
        HandlerChanged="Frame_HandlerChanged">
        <Grid...>
        </Grid>
        <Frame.GestureRecognizers>
          <TapGestureRecognizer/>
        </Frame.GestureRecognizers>
      </controls:BorderedFrame>
    </DataTemplate>
  </BindableLayout.ItemTemplate>
</StackLayout>

csharp

public partial class Component
{
  void Frame_HandlerChanged(System.Object sender, System.EventArgs e)
  {
    if (sender is Frame frame && frame.Handler?.PlatformView is Android.Widget.FrameLayout view)
    {
      ViewCompat.SetAccessibilityDelegate(view, new CustomFrameDelegate(ViewCompat.GetAccessibilityDelegate(view)));
    }
  }
}

public class CustomFrameDelegate : AccessibilityDelegateCompatWrapper
{
    public CustomFrameDelegate(AccessibilityDelegateCompat? originalDelegate) : base(originalDelegate)
    {
    }

    public override void OnInitializeAccessibilityNodeInfo(Android.Views.View host, AccessibilityNodeInfoCompat info)
    {
        base.OnInitializeAccessibilityNodeInfo(host, info);
        if (info != null)
            info.ClassName = "android.widget.Button";
    }
}

csharp

public partial class Component
{
  void Frame_HandlerChanged(System.Object sender, System.EventArgs e)
  {
    if (sender is Frame frame && frame.Handler != null)
    {
      var view = (UIView)frame.Handler.PlatformView!;
      view.AccessibilityTraits = UIAccessibilityTrait.Button;
    }
  }
}

Xamarin Forms does not have built-in support for setting an accessibility role.

By using Effects it is possible to implement platform specific behaviour.

The SemanticEffect file inside the Xamarin.CommunityToolkit defines various methods to set accessibility roles.

xml

<controls:CustomFontLabel
    xct:SemanticEffect.HeadingLevel="1"
    xct:SemanticEffect.Description="Button" />

Set accessibility value

Android has limited support to provide a dedicated accessibility value for assistive technologies. The AccessibilityNodeInfoCompat object contains a couple of methods, such as the setChecked method.

Unfortunately the desired value is often not available. If your desired value is not included, you can append it to the contentDescription attribute.

kotlin

ViewCompat.setAccessibilityDelegate(
    element,
    object : AccessibilityDelegateCompat() {
        override fun onInitializeAccessibilityNodeInfo(
            host: View,
            info: AccessibilityNodeInfoCompat
        ) {
            super.onInitializeAccessibilityNodeInfo(host, info)
            info.isChecked = true
        }
    }
)

element.contentDescription = "Name (Value)"

In Jetpack Compose, you can use the clearAndSetSemantics.clearAndSetSemantics(kotlin.Function1)) to override existing semantics and set new properties.

kotlin

// Override so label and value will be read out together
val label = "Text label"
val value = "Text value"
Text(
    text = value,
    modifier = Modifier.clearAndSetSemantics {
        text = AnnotatedString("$label, $value")
    }
)

On iOS, you can set an accessibility value with the accessibilityValue or accessibilityAttributedValue property.

When using the semantically correct element, you usually do not need to modify the accessibilityValue. For example, a UISwitch sets the accessibilityValue to selected or not selected and a UISlider sets the accessibilityValue to the current value. If the default value is incorrect or unclear, you can override the value manually.

swift

element.accessibilityValue = "Custom"

In SwiftUI, you can set an accessibility value with the accessibilityValue-2bwuz) view modifier by providing a Text value description.

When using the semantically correct element, you usually do not need to modify the accessibilityValue. For example, a Toggle sets the accessibilityValue to On or Off and a Slider sets the accessibilityValue to the current value. If the default value is incorrect or unclear, you can override the value manually.

swift

@State private var progress: Double = 0

var body: some View {
    CustomSlider(value: $progress)
        .accessibilityValue("\(progress)")
}

With Flutter, you can set an accessibility value by using the value or attributedValue property of Semantics.

When using the semantically correct element, you usually do not need to modify the accessibility value. For example, Slider, Switch and CheckBox, and others automatically assign accessibiluty values.

It is also possible to set an increasedValue and decreasedValue or attributedDecreasedValue and attributedIncreasedValue to indicate what the value will become when the user decreases or increases the value.

Some widgets include additional methods, such as semanticFormatterCallback.

dart

Semantics(
  value: 'Custom',
  increasedValue: 'Custom + 1',
  decreasedValue: 'Custom - 1',
  child: Widget(),
);

In React Native you can use the accessibilityValue and accessibilityState props to set an accessibility value. The accessibilityValue indicates the current value of a component. You can indicate a range, using min, max, and no, or text using text. The accessibilityState indicates the current state of a component, for example disabled or checked.

jsx

<View
  accessibilityValue={{min: 0, max: 100, now: 50}}
  accessibilityState="busy" />

<View 
  accessibilityValue={{text: "Custom"}}
  accessibilityState="disabled" />

In MAUI, elements such as Button and Entry automatically include an accessibility value. When you create custom elements you have to set these properties yourself.

However, there is no dedicated property to set an accessibility value. You can embed the value inside the label by using MultiBinding inside the SemanticProperties.Description property.

xml

<Label>
  <SemanticProperties.Description>
    <MultiBinding StringFormat="{}{0}, {1}">
      <Binding Source="The value is: " />
      <Binding Source="{BindingValue}" />
    </MultiBinding>
  </SemanticProperties.Description>
</Label>

Xamarin Forms elements such as Button and Entry automatically include an accessibility value. When you make custom elements you have to set these properties yourself.

However, there is no dedicated property to set an accessibility value. You can embed the value inside the label by using MultiBinding inside the AutomationProperties.Name property.

xml

<Label
    <AutomationProperties.Name>
        <MultiBinding StringFormat="{}{0}, {1}">
            <Binding Source="The value is: " />
            <Binding Source="{BindingValue}" />
        </MultiBinding>
    </AutomationProperties.Name>
</Label>

Set accessibility state

On Android, you can use the setAccessibilityDelegate) method of ViewCompat to get a reference to AccessibilityNodeInfoCompat. This object contains many useful accessibility related methods.

You can set an accessibility state by using the setStateDescription) method. A convenience method is available in ViewCompat, which is also named setStateDescription).

You can also use the setChecked) method to indicate a checked state and the setSelected) method to indicate a selected state.

kotlin

ViewCompat.setStateDescription(view, "Expanded")

ViewCompat.setAccessibilityDelegate(
    view,
    object : AccessibilityDelegateCompat() {
        override fun onInitializeAccessibilityNodeInfo(
            host: View,
            info: AccessibilityNodeInfoCompat
        ) {
            super.onInitializeAccessibilityNodeInfo(host, info)

            // Custom state
            info.stateDescription = "Expanded"

            // Checked
            info.isChecked = true

            // Selected
            info.isSelected = true
        }
    }
)

In Jetpack Compose, you can use the semantics.semantics(kotlin.Boolean,kotlin.Function1)) modifier to set various accessibility properties.

You can set an accessibility state by using the stateDescription.stateDescription()) property. You can also use the selected.selected()) property to indicate a selected state.

kotlin

Box(
    modifier = Modifier.semantics {
        // Custom state
        stateDescription = "Expanded"

        // Selected
        selected = true
    }
)

On iOS, the accessibilityTraits attribute can be used to indicate the accessibility state. The traits selected and notEnabled can be used to indicate the current state.

If your state is not selected or notEnabled, we recommended using the accessibilityValue attribute to indicate the state.

swift

element.accessibilityTraits = .selected
element.accessibilityTraits = .notEnabled

element.accessibilityValue = "Expanded"
element.accessibilityValue = "Collapsed"

In SwiftUI, the AccessibilityTraits attribute can be used to indicate the accessibility state. The traits isSelected can be used to indicate the current state.

swift

@State private var isSelected: Bool = false

var body: some View {
    CustomCheckbox(isSelected: $isSelected)
        .accessibilityAddTraits(isSelected ? [.isSelected] : [])
}

swift

@State private var isExpanded = false

var body: some View {
    ExpandableView()
        // Accessibility value indicates the state
        .accessibilityValue(isExpanded ? "Expanded": "Collapsed")
}

With Flutter, you can use Semantics to indicate the accessibility state. The Semantics constructor contains all available options, such as checked, enabled, hidden, selected and toggled, among others.

dart

Semantics(
  checked: true,
  enabled: true,
  hidden: true,
  selected: true,
  toggled: true,
  child: Widget(...)
);

In React Native you can use the accessibilityState object to set the accessibility state of an element. Available states include disabled, selected, checked, busy and expanded, among others.

jsx

<Pressable 
  accessibilityState="{{ expanded: true }}" />

← Back to Engineering Support

4.1.2 — Name, Role, Value

Set accessibility name

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

.NET MAUI

Xamarin

Set accessibility role

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

.NET MAUI

Xamarin

Set accessibility value

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

.NET MAUI

Xamarin

Set accessibility state

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

Xamarin