accessible-name-starts-with-label

Many elements have both a visible label and an accessible name, the programmatic name that assistive technologies use. Voice control users activate elements by speaking what they see on screen, and voice control software works best when the spoken words match the start of the accessible name. Make sure the accessible name contains the visible label and, whenever possible, begins with it. The simplest way is to not override the name at all, so it comes from the visible label.

Pass Patterns

Android

<Button
    android:layout_width="..."
    android:layout_height="..."
    android:layout_gravity="center"
    android:text="Order" />

iOS

let orderButton = UIButton(type: .system)
orderButton.setTitle("Order", for: .normal)
orderButton.accessibilityLabel = "Order items"

Button("Order") {
    placeOrder()
}

Cross Platform

ElevatedButton(
  onPressed: placeOrder,
  child: const Text('Order', semanticsLabel: 'Order items'),
),

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Order items"
  onPress={...}
>
  <Text>Order</Text>
</Pressable>

Fail Patterns

Android

<Button
    android:layout_width="..."
    android:layout_height="..."
    android:text="Place order"
    android:contentDescription="Order" />

iOS

let orderButton = UIButton(type: .system)
orderButton.setTitle("Order", for: .normal)
orderButton.accessibilityLabel = "Place order"

Button("Order") {
    placeOrder()
}
.accessibilityLabel("Place order")

Cross Platform

ElevatedButton(
  onPressed: placeOrder,
  child: const Text('Order', semanticsLabel: 'Place order'),
),

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Place order"
  onPress={...}
>
  <Text>Order</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.

Expected results: The name shown for each element starts with the element's visible label.

Actual results: The name shown contains the visible label later in the text, for example “Place order” for a button labeled “Order”.

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 starts with the visible label.

Actual results: The accessible name starts with other words, and the visible label appears only later.

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
• label-in-name