label-in-name

Many elements have both a visible label and an accessible name, the programmatic name that assistive technologies use. Voice input users activate elements by speaking the words they see on screen. When the accessible name does not include the visible label, those words do not match the element, and users cannot find or activate it by voice. Screen reader users who can also see the screen hear a name that differs from what is shown. Include the visible label text, in the same order, in the accessible name. You can add extra context after the label. The simplest way is to not override the name at all, so it comes from the visible label.

Pass Patterns

Android

<Button
    android:id="@+id/refreshButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Refresh" />

iOS

let refreshButton = UIButton(type: .system)
refreshButton.setTitle("Refresh", for: .normal)
refreshButton.accessibilityLabel = "Refresh the list"

Button("Refresh") {
    refresh()
}

Cross Platform

ElevatedButton(
  onPressed: refresh,
  child: const Text('Refresh', semanticsLabel: 'Refresh the list'),
),

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Refresh the list"
  onPress={refresh}
>
  <Text>Refresh</Text>
</Pressable>

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Label In Name — Pass because they start the same"
  style={styles.button}
  onPress={ ... }
>
  <Text style={styles.label}>Label In Name — Pass</Text>
</Pressable>

Fail Patterns

Android

<Button
    android:id="@+id/refreshButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Refresh"
    android:contentDescription="Reload" />

iOS

let refreshButton = UIButton(type: .system)
refreshButton.setTitle("Refresh", for: .normal)
refreshButton.accessibilityLabel = "Reload"

Button("Refresh") {
    refresh()
}
.accessibilityLabel("Reload")

Cross Platform

ElevatedButton(
  onPressed: refresh,
  child: const Text('Refresh', semanticsLabel: 'Reload'),
),

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Reload"
  onPress={refresh}
>
  <Text>Refresh</Text>
</Pressable>

<Pressable
  accessibilityRole="button"
  accessibilityLabel="No label in name"
  style={styles.button}
  onPress={ ... }
>
  <Text style={styles.label}>Label In Name — Fail</Text>
</Pressable>

Try It Yourself

Using voice input

1. Turn on Voice Control on iOS, or Voice Access on Android. On Android, make sure Voice Access is listening, from the notifications panel.
2. Say “Show names” on iOS, or “Show labels” on Android.
3. Compare the name shown for each element with its visible label.
4. Say “Tap” followed by the element's visible label, for example “Tap Refresh”.

Expected results: The name shown for each element includes its visible label, and the element is activated when you say its visible label.

Actual results: The name shown does not include the visible label, for example “Reload” for a button labeled “Refresh”, and saying the visible label does not activate the element.

Using developer tools

1. iOS: In Xcode, open Xcode > Open Developer Tool > Accessibility Inspector, select the simulator or device, and point at the element. Check its Label.
2. Android: In Android Studio, open the Layout Inspector and select the element. Check its contentDescription, for Views, or its semantics, for Jetpack Compose.

Expected results: The accessible name is empty, so the visible label is used, or it includes the visible label.

Actual results: The accessible name does not include the visible label.

FAQ

Standards and Regulations

Personas impacted by this issue

• Voice Input

Learn More

• Understanding Success Criterion 2.5.3: Label in Name

Related Issues

• accessible-name
• accessible-name-starts-with-label
• invalid-labeling-attribute
• meaningful-button
• special-characters
• visible-labels