1. Perceivable · 1.3 Adaptable

1.3.3 — Sensory Characteristics

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.

Add accessibility hint

On Android, you can use setHint) to set a hint. Keep in mind that this hint is not only used for accessibility, but also shown visually in editable views.

kotlin

view.hint = "Opens the Appt website"

xml

<Button
    android:hint="Opens the Appt website">
</Button>

In Jetpack Compose, you can use contentDescription.contentDescription()) parameter inside semantics.semantics(kotlin.Boolean,kotlin.Function1)) modifier block to set a hint.

For the TextField) composable, you can use the placeholder parameter to set a hint.

kotlin

// Set hint for a Button
Button(
    onClick = { /*Handle button click*/ },
    modifier = Modifier.semantics { contentDescription = "Opens the Appt website" }
) {
    // Button content...
}

// Set hint for a TextField
TextField(
    value = "",
    onValueChange = { /* State update logic */ },
    placeholder = { Text("Opens the Appt website") }
)

In SwiftUI, you can use the accessibilityHint-3i2vu) view modifier to provide an accessibility hint. When using VoiceOver, the accessibility hint is read after the element’s label and value, following a brief pause. This hint provides additional context about what will happen when the user interacts with the element. Use the hint to give users extra information about the outcome or the purpose of the element's action.

Note: Users have the option to disable accessibility hints in their device settings. Therefore, you should never place essential information in the hint.

swift

Button(action: {}, label: {
    Text("Search")
})
.accessibilityHint("Searches for accessibility articles")

In Xamarin Forms you can set an accessibility hint by using the AutomationProperties.HelpText property.

xml

<Button
  AutomationProperties.HelpText="Opens the Appt website" />

csharp

AutomationProperties.SetHelpText(button, "Opens the Appt website");

Add accessibility action

On Android, you can add custom actions for assistive technologies using the ViewCompat.addAccessibilityAction) helper method.

You can also use the addAction) method of AccessibilityNodeInfoCompat to override labels for default actions.

kotlin

// Add custom action
ViewCompat.addAccessibilityAction(view, "Add bookmark") { view, arguments ->
    // Bookmark logic
    true
}

// Override click action label
ViewCompat.setAccessibilityDelegate(view, new AccessibilityDelegateCompat() {
    @Override
    public void onInitializeAccessibilityNodeInfo(
        View host,
        AccessibilityNodeInfoCompat info)
    {
        super.onInitializeAccessibilityNodeInfo(host, info)
        AccessibilityActionCompat action = new AccessibilityActionCompat(
            AccessibilityNodeInfoCompat.ACTION_CLICK,
            "Add bookmark"
        )
        info.addAction(action)
    }
})

In Jetpack Compose, you can add custom actions for assistive technologies using the customActions.customActions()) property inside the semantics.semantics(kotlin.Boolean,kotlin.Function1)) block modifier.

kotlin

// add custom action
Button(
    onClick = { /* Your click handler */ },
    modifier = Modifier
        .wrapContentSize()
        .semantics {
            customActions = listOf(
                // your custom action
                CustomAccessibilityAction(label = "Add bookmark") {
                    // Bookmark logic
                    true
                }
            )
        }
) {
    Text("Bookmark button")
}

kotlin

// override label for button
val buttonClickHandler: () -> Unit = { /* Your click handler */ }
Button(
    onClick = buttonClickHandler,
    modifier = Modifier
        .semantics {
            onClick(label = "Add bookmark") {
                buttonClickHandler.invoke()
                true
            }
        }
) {
    // Button content
}

On iOS, you can use UIAccessibilityCustomAction to add custom actions for assistive technologies. You can also use UIAccessibilityCustomRotor to add custom actions to the VoiceOver rotor. Furthermore, you can use the accessibilityActivate method to override the action that happens when a user activates an element, e.g. by double tapping with the screen reader.

swift

// Custom action
let customAction = UIAccessibilityCustomAction(
    name: "Appt action",
    actionHandler: { (action: UIAccessibilityCustomAction) -> Bool in
        // Logic
        return true
    }
)
accessibilityCustomActions = [customAction]

// Custom rotor
let customRotor = UIAccessibilityCustomRotor(name: "Appt rotor") { predicate in
    // Logic
}
accessibilityCustomRotors = [customRotor]

// Custom activation
override func accessibilityActivate() -> Bool {
    // Logic
    return true // True if the element was activated, false if not
}

In SwiftUI, you can add the accessibility action) modifier to provide a custom action to the view when assistive technologies are activated. You can add multiple custom actions by calling the same method on the view multiple times.

Additionally, you can define multiple custom actions by using the accessibility actions) view modifier.

swift

// Single custom accessibility action
var body: some View {
    ContentView()
        // Custom action
        .accessibilityAction(named: "Appt action") {
            // Logic
        }
}

swift

// Multiple accessibility actions
var body: some View {
    ContentView()
        // Custom actions
        .accessibilityActions {
            Button("Appt action one") {
                // Logic
            }

            Button("Appt action two") {
                // Logic
            }
        }
}

With Flutter, you can use CustomSemanticsAction to add custom actions for assistive technologies. To implement specific functionality for assistive technologies it is also possible to add onTap, onLongPress or other callbacks to the Semantics widget. When you do this, it is important to make sure the child nodes do not implement a touch listener, or to use excludeSemantics to ignore these with the assistive technologies.

dart

Semantics(
    customSemanticsActions: <CustomSemanticsAction, VoidCallback>{
        CustomSemanticsAction(label: 'Increment'): _incrementCounter,
    },
    onTap: () {
        _incrementCounter
    },
    excludeSemantics: true,
    child: TextButton(...)
);

In React Native, you can add accessibility actions using the accessibilityActions and onAccessibilityAction properties.

jsx

<View
  accessible
  accessibilityRole="adjustable"
  accessibilityActions={[{name: 'increment', label: 'Increment'}]}
  onAccessibilityAction={event => {
    if (event.nativeEvent.actionName === 'increment') {
      handleIncrement();
    }
  }}
/>

In MAUI, there is no built-in way to create a custom action, but you can achieve this via Platform Behavior. See the code below for an example of usage.

csharp

public class AccessibilityCustomActionBehavior
#if IOS
    : PlatformBehavior<View, UIKit.UIView>
#elif ANDROID
    : PlatformBehavior<View, Android.Views.View>
#endif

{
    private int androidActionId = -1;

    public static readonly BindableProperty NameProperty =
        BindableProperty.Create(
            nameof(Name), 
            typeof(string), 
            typeof(AccessibilityCustomActionBehavior), null, 
            BindingMode.TwoWay
        );

    public static readonly BindableProperty ActionProperty =
        BindableProperty.Create(
            nameof(Action), 
            typeof(Func<bool>), 
            typeof(AccessibilityCustomActionBehavior), 
            null, 
            BindingMode.TwoWay
        );

    public string Name
    {
        get => (string)GetValue(NameProperty);
        set => SetValue(NameProperty, value);
    }

    public Func<bool> Action
    {
        get => (Func<bool>)GetValue(ActionProperty);
        set => SetValue(ActionProperty, value);
    }

    protected override void OnAttachedTo
#if IOS
        (View bindable, UIKit.UIView platformView)
#elif ANDROID
        (View bindable, Android.Views.View platformView)
#endif
    {
        base.OnAttachedTo(bindable, platformView);

#if IOS
        var customAction = new UIKit.UIAccessibilityCustomAction(Name, probe: (sender) =>
        {
            return Action?.Invoke() ?? false;
        });

        platformView.AccessibilityCustomActions = new[]
        {
            customAction
        };
#elif ANDROID
        androidActionId = AndroidX.Core.View.ViewCompat.AddAccessibilityAction(
            platformView, 
            Name, 
            new CustomAndroidAccessibilityAction(Action)
        );
#endif
    }

    protected override void OnDetachedFrom
#if IOS
        (View bindable, UIKit.UIView platformView)
#elif ANDROID
        (View bindable, Android.Views.View platformView)
#endif
    {
        base.OnDetachedFrom(bindable, platformView);

#if IOS
        platformView.AccessibilityCustomActions = null;
#elif ANDROID
        if (androidActionId != -1)
        {
            AndroidX.Core.View.ViewCompat.RemoveAccessibilityAction(
                platformView, 
                androidActionId
            );
        }
#endif
    }

#if ANDROID

    public class CustomAndroidAccessibilityAction : 
        Java.Lang.Object, 
        AndroidX.Core.View.Accessibility.IAccessibilityViewCommand
    {
        Func<bool> action;

        public CustomAndroidAccessibilityAction(Func<bool> action)
        {
            ArgumentNullException.ThrowIfNull(action);

            this.action = action;
        }

        public bool Perform(
            Android.Views.View view, 
            AndroidX.Core.View.Accessibility.AccessibilityViewCommandCommandArguments? arguments)
        {
            return action();
        }
    }

#endif
}

xml

<Image
    Source="dotnet_bot.png"
    HeightRequest="185">
    <Image.Behaviors>
        <local:AccessibilityCustomActionBehavior
            BindingContext="{Binding BindingContext, Source={Reference Parent}}"
            Name="{Binding Title}"
            Action="{Binding CustomAction}" />
    </Image.Behaviors>
</Image>

csharp

var image = new Image();
image.Behaviors.Add(new AccessibilityCustomActionBehavior
{
    Name = "",
    Action = () =>
    {
        // Custom action logic
        return true;
    }
});

← Back to Engineering Support

1.3.3 — Sensory Characteristics

Add accessibility hint

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

.NET MAUI

Xamarin

Add accessibility action

Android

Jetpack Compose

iOS

SwiftUI

Flutter

React Native

.NET MAUI

Xamarin