state-in-name
Mobile validation
Assistive technologies announce an element's accessible name together with its role and its state, such as checked, selected, or on. When the state is also part of the accessible name, for example “Agree, checked” on a checked checkbox, screen readers announce it twice, which adds noise and slows users down. The state in the name is also static, while the element's actual state changes. As soon as users toggle the element, the name contradicts its state. Remove the state from the accessible name, and let the element's state be announced on its own.
Note: When the state in the name already contradicts the element's actual state, see the related conflicting-state-in-name validation.
Pass Patterns
Android
The checkbox's contentDescription identifies it without any state text.
<CheckBox
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:checked="true"
android:text="Agree"
android:contentDescription="Agree to terms"/>The checkbox's contentDescription identifies it without any state text.
Checkbox(
checked = true,
onCheckedChange = {},
modifier = Modifier.semantics {
contentDescription = "Agree"
},
)Cross Platform
// The state is included in the accessible name as well as the checked state
child: Semantics(
label: 'Passing example',
checked: true,
excludeSemantics: true,
child: Checkbox(
value: true,
onChanged: (_) {},
),
),<Checkbox
accessibilityLabel="State In Name - Pass correctly"
value={checked}
onValueChange={setChecked}
style={styles.checkbox}
/>Fail Patterns
Android
The checkbox is checked, and its contentDescription repeats the state, “checked”.
<!-- If the state is only in the content description -->
<CheckBox
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:checked="true"
android:text="Agree"
android:contentDescription="Agree, checked"/>The checkbox is checked, and its contentDescription repeats the state, “checked”.
Checkbox(
checked = true,
onCheckedChange = {},
modifier = Modifier.semantics {
contentDescription = "Agree, checked"
},
)Cross Platform
// The state is included in the accessible name as well as the checked state
child: Semantics(
label: 'Failing example, Checked',
checked: true,
excludeSemantics: true,
child: Checkbox(
value: true,
onChanged: (_) {},
),
),{/* If the state is in the accessibilityLabel */}
<Checkbox
accessibilityLabel="State In Name - Fail, checked"
value={checked}
onValueChange={setChecked}
style={styles.checkbox}
/>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 element.
- Listen to the element's name and its state.
Expected results: The screen reader announces the element's state once, for example “Agree, checked, checkbox”.
Actual results: The screen reader announces the state twice, once from the name and once from the element, for example “Agree, checked, checked, checkbox”.
Tip: To hear the state more easily, set the screen reader to announce it first. On Android, open TalkBack settings > Advanced settings > Element description order and choose "State, name, type". On iOS, open Settings > Accessibility > VoiceOver > Verbosity > Controls and choose "Speak Before".
Using developer tools
- iOS: In Xcode, open Xcode > Open Developer Tool > Accessibility Inspector, select the simulator or device, and point at the element. Check its Label.
- 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 name contains no state text.
Actual results: The name contains state text, such as “checked” or “on”.
FAQ
Why is this issue marked as Minor?
It does not block use of the element. The repeated state adds noise and makes announcements longer, and it can become confusing once the name and the actual state are out of sync, but people can still understand and operate the element, so it is rated minor.
How does this issue relate to 4.1.2 Name, Role, Value
WCAG 4.1.2 requires that each component expose a programmatic accessible name, role, and current state or value so assistive technologies can announce them accurately. When you place the state inside the accessible name, you mix information that should be separate
Assistive technologies already announce the accessible name together with the role and state. If the name also includes words like checked, selected, or on, users hear the state twice. When the control toggles, the name can also contradict the actual state
To align with 4.1.2, keep the accessible name focused on purpose, not state. Expose the current state through semantics, such as the checked property or selected state. This lets assistive technologies relay up-to-date information without duplication or confusion
Standards and Regulations
| Standard | Success Criterion | Reference |
|---|---|---|
| WCAG 2.2 | 4.1.2 Name, Role, Value (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | 11.4.1.2 Name, Role, Value | Same as the WCAG text. |