Users of accessibility services, such as screen readers, rely on content labels to understand the meaning of elements in an interface.
In some cases, such as when information is conveyed graphically within an element, content labels can provide a text description of the meaning or action associated with the element.
If elements in a user interface don't provide content labels, it can be difficult for some users to understand the information presented to them or to perform actions in the interface.
When certain types of
Views are used in an interface, they should provide content labels that describe the purpose or action associated with that
How to provide content labels
When using an
CheckBox, or other
View that conveys information graphically, use an
android:contentDescription attribute to provide a content label for that
A content label sometimes depends on information only available at runtime, or the meaning of a
View might change over time. For example, a Play button might change to a Pause button during music playback. In these cases, use
View#setContentDescription(CharSequence contentDescription) to update the content label at the appropriate time.
Typically, when an accessibility service describes a
ViewGroup, it combines content labels from it’s child
Views. To override this behavior and indicate that you want to provide your own description for that item and its non-focusable child
Views, set a
contentDescription on the
ViewGroup. You might need to include content labels from child
Views within a
contentDescription when set on a
android:labelFor attribute to indicate that a
View should act as a content label for another
Cases that don't require content labels
In certain cases, content labels should not be specifically provided:
- Text rendered in
TextView(or its subclasses) is automatically provided to accessibility services. Additional content labels are usually unnecessary.
- Decorative images or images that don't convey meaningful information graphically do not require content labels. In these cases, set an
When designing a user interface, think carefully about how graphically represented content should be labeled for users of accessibility services. Content labels should follow these principles:
- Be succinct and clearly describe the meaning or action associated with an element.
- Don't include an element's type or state in its content label.
- If the element is associated with an action, describe the action, not the graphical representation.
- Don't instruct the user how to specifically interact with the element.
To learn more, read Material Design Accessibility Writing Guidelines.
To manually verify that an app's user interface isn't missing content labels:
- Turn on TalkBack.
- Open the app.
- Use linear navigation gestures to move accessibility focus to each element on the screen.
- If TalkBack moves focus to some element, but doesn't speak a meaningful representation of that element, or speaks an "unlabeled" message, that element might be missing a content label.
Android's automated testing tools can detect missing content labels. Consider using Accessibility Scanner for Android for manual testing of your app on-device. For automated tests, turn on accessibility checking in Espresso and Robolectric.