Content labels

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.

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.