Content labels

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.

Implementation

View

When certain types of Views are used in an interface, they should provide content labels that describe the purpose or action associated with that View.

How to provide content labels

android:contentDescription

When using an ImageView, ImageButton, CheckBox, or other View that conveys information graphically, use an android:contentDescription attribute to provide a content label for that View.

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 ViewGroup.

android:hint

For EditTexts or editable TextViews, use an android:hint attribute to indicate the purpose of the text field. An android:contentDescription should not be used as a content label for editable Views.

android:labelFor

Use an android:labelFor attribute to indicate that a View should act as a content label for another View.

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 android:contentDescription attribute of "@null" or an android:importantForAccessibility attribute of "no".

To learn more, read about implementing content labels in Android Developer Training and API Guides.

Compose

When certain types of composables are used in an interface, they should contain content labels that describe the purpose or action associated with that composable.

How to provide content labels

Content descriptions

To provide a content label for Image, Icon, or another low-level composable that conveys graphical information, set the content description.

A content label may depend on runtime information and the composable’s meaning might change. For example, during music playback, a Play button might change to a Pause button.
- In these cases, use state so Compose can observe changes in the content description and recompose it with the new value. Learn how to use State and Jetpack Compose.

In some cases, you may want to merge elements into a single focusable element that combines the content labels from its descendant elements. Learn how to merge elements.

Label parameter

Some composables, like TextField, support an optional label parameter. When the label is set, the element displays the composable passed to label. Accessibility services can be used to describe the composable.

Cases that don't require content labels

In certain cases, content labels shouldn’t be added:

Text rendered in Text, or other composables that contain Text, is automatically provided to accessibility services.
Decorative images or images that don't convey meaningful graphical information.
- In these cases, set the contentDescription parameter or Modifier.semantics#contentDescription property to null or call Modifier#clearAndSetSemantics.

Design

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.

Testing

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.