Success Criterion 4.1.2 - Level A
Name, Role, Value
Ensure it is clear for users of assistive technologies what actions can be performed.
Set a name. The name is used for identification. By setting a name, assistive technologies such as voice control can perform targeted actions.
Set a role. With the role “button” it is clear that an action takes place upon activation. With the role “link” it is clear that you will be referred to another location. By setting a role, it is clear to users of assistive technologies what they can do.
Set a value. A check box should have the value “selected” or “not selected”. With a volume control, the value can be “50%”. By setting a value, this text value can be passed to assistive technologies.
Impact
People who use assistive technologies depend on a correct name, role and value.
If a button has no name then it is not clear what action will take place.
If a button does not have the role button, then a user will not know that it can be clicked.
If the value of a switch is not indicated to assistive technologies, a user will not know whether it is on or off.
Check
“Are the name, rol and value set correctly?“
This can be tested with the screen reader.
Solution
Set accessibility name
On Android, the contentDescription
property is used as accessibility name.
Set accessibility role
On Android, you can use the setAccessibilityDelegate
method of ViewCompat
to get a reference to AccessibilityNodeInfoCompat
. This object contains many useful accessibility related methods.
You can set a role using the setRoleDescription
method. However, we recommend using the setClassName
method over setRoleDescription
to support multilingual roles. For example, set Button::class.java.name
if an element behaves like a button. The role will be set to Button
in English, and to its respective translation in other languages.
You can indicate a heading by using the setHeading
method. ViewCompat
also contains a convenience method: setAccessibilityHeading
.
ViewCompat.setAccessibilityDelegate(
element,
object : AccessibilityDelegateCompat() {
override fun onInitializeAccessibilityNodeInfo(
host: View,
info: AccessibilityNodeInfoCompat
) {
super.onInitializeAccessibilityNodeInfo(host, info)
// Custom
info.roleDescription = "Custom role"
// Button
info.className = Button::class.java.name
// Heading
info.isHeading = true
// Image
info.className = ImageView::class.java.name
}
}
)
// Convenience method
ViewCompat.setAccessibilityHeading(view, true)
Set accessibility value
Android has limited support to provide a dedicated accessibility value for assistive technologies. The AccessibilityNodeInfoCompat
object contains a couple of methods, such as the setChecked
method.
Unfortunately the desired value is often not available. If your desired value is not included, you can append it to the contentDescription
attribute.
ViewCompat.setAccessibilityDelegate(
element,
object : AccessibilityDelegateCompat() {
override fun onInitializeAccessibilityNodeInfo(
host: View,
info: AccessibilityNodeInfoCompat
) {
super.onInitializeAccessibilityNodeInfo(host, info)
info.isChecked = true
}
}
)
element.contentDescription = "Name (Value)"
Set accessibility state
On Android, you can use the setAccessibilityDelegate
method of ViewCompat
to get a reference to AccessibilityNodeInfoCompat
. This object contains many useful accessibility related methods.
You can set an accessibility state by using the setStateDescription
method. A convenience method is available in ViewCompat
, which is also named setStateDescription
.
You can also use the setChecked
method to indicate a checked state and the setSelected
method to indicate a selected state.
ViewCompat.setStateDescription(view, "Expanded")
ViewCompat.setAccessibilityDelegate(
view,
object : AccessibilityDelegateCompat() {
override fun onInitializeAccessibilityNodeInfo(
host: View,
info: AccessibilityNodeInfoCompat
) {
super.onInitializeAccessibilityNodeInfo(host, info)
// Custom state
info.stateDescription = "Expanded"
// Checked
info.isChecked = true
// Selected
info.isSelected = true
}
}
)