instruction-in-name
Mobile validation
Use the accessible name to state the control's purpose. Don't include gestures, input methods, or other instructions, such as “double tap”, “tap”, “long press”, “swipe up”, or “use the rotor”. Assistive technologies already tell users how to operate a control, based on its role and state. When the name also contains instructions, screen readers announce them twice, once from the name and once from the control itself, and the two may even contradict each other. Users can also change the gestures their assistive technology uses, so instructions in the name may simply be wrong for them.
Note: If users need extra guidance, put it in the platform's hint instead of the name, for example accessibilityHint on iOS and in React Native, hint in Flutter's Semantics, or onClickLabel in Jetpack Compose.
Pass Patterns
Android
The button's name comes from its text, “Mute”, with no instructions.
<Button
android:id="@+id/muteButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Mute" />The button's name comes from its text, “Mute”, with no instructions.
Button(onClick = { toggleMute() }) {
Text("Mute")
}iOS
The button's name comes from its title, “Mute”, with no instructions.
let muteButton = UIButton(type: .system)
muteButton.setTitle("Mute", for: .normal)The button's name comes from its title, “Mute”, with no instructions.
Button("Mute") {
toggleMute()
}Cross Platform
React Native
The button's name comes from its text, “Mute”, with no instructions.
<Pressable accessibilityRole="button" onPress={toggleMute}>
<Text>Mute</Text>
</Pressable>Fail Patterns
Android
The contentDescription adds the instruction “double tap to toggle” to the name.
<Button
android:id="@+id/muteButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Mute"
android:contentDescription="Mute, double tap to toggle" />The contentDescription adds the instruction “double tap” to the name.
Button(
onClick = { toggleMute() },
modifier = Modifier.semantics {
contentDescription = "Mute, double tap"
},
) {
Text("Mute")
}iOS
The accessibilityLabel adds the instruction “double tap to toggle” to the name.
let muteButton = UIButton(type: .system)
muteButton.setTitle("Mute", for: .normal)
muteButton.accessibilityLabel = "Mute, double tap to toggle"The accessibilityLabel adds the instruction “double tap to toggle” to the name.
Button("Mute") {
toggleMute()
}
.accessibilityLabel("Mute, double tap to toggle")Cross Platform
React Native
The accessibilityLabel adds the instruction “double tap to toggle” to the name.
<Pressable
accessibilityRole="button"
accessibilityLabel="Mute, double tap to toggle"
onPress={toggleMute}
>
<Text>Mute</Text>
</Pressable>Try It Yourself
Using a screen reader
New to screen reader testing, or need a refresher?
Review this article first: Practical guides for using screen readers
- Turn on VoiceOver on iOS, or TalkBack on Android.
- Swipe right or left to move to the control.
- Listen to the control's name, before its role and the screen reader's own usage hint.
Expected results: The name states only the control's purpose, for example “Mute, button”.
Actual results: The name includes instructions, and the screen reader repeats them in its own hint, for example “Mute, double tap to toggle, button, double tap to activate”.
Using developer tools
- iOS: In Xcode, open Xcode > Open Developer Tool > Accessibility Inspector, select the simulator or device, and point at the control. Check its Label.
- Android: In Android Studio, open the Layout Inspector and select the control. Check its
contentDescription, for Views, or its semantics, for Jetpack Compose.
Expected results: The name contains no gestures or instructions.
Actual results: The name contains gestures or instructions, such as “double tap” or “swipe up”.
FAQ
Why is this issue marked as Best Practice?
The control can still be found and operated, so users are not blocked. However, the repeated or contradicting instructions make announcements longer and can confuse users, especially when they have customized their gestures, so it is rated best practice.