Editable View labels

Background

Editable items in an app allow users to enter text. Each editable item should have a descriptive label stating its purpose.

Android offers several ways for developers to label Views in an app's user interface. For editable items in an interface, some of these ways of labeling can improve accessibility.

Implementation

To label an editable TextView or EditText, use android:hint to display a descriptive text label within the item when it's empty.


<EditText
    android:id="@+id/email_subject"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:hint="@string/email_subject_hint" />

If an app’s user interface already provides a text label for the editable item, define android:labelFor on the labeling View to indicate which item the label describes.


<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">
    <TextView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/email_subject_label"
        android:labelFor="@id/email_subject" />
    <EditText
        android:id="@+id/email_subject"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content" />
</LinearLayout>

Tip: TextInputLayout in the Android Design Support Library provides an easy way to manage an EditText and an associated text label, and works well with Android's accessibility services.

Defining an android:contentDescription on any EditText or editable TextView may interfere with an accessibility service's ability to describe, navigate, and interact with text that a user enters within the item.

Design

When navigating to editable items with a screen reader, a well-implemented user interface has these elements:

  • If the editable field is empty, it has a descriptive label that the screen reader speaks.
  • If a user has entered text in the editable field, the screen reader speaks the text in place of the label.

These two elements remain true even when navigating at a lower granularity, such as character by character.

Testing

To manually verify that an app contains correctly labeled editable items:

  1. Turn on TalkBack.
  2. Open the app.
  3. Move accessibility focus to the empty editable item.
  4. Listen to TalkBack's spoken description of the empty editable item. Check whether the description contains a label, and whether that descriptive label matches any visual labels in the app.
  5. Type some text in the editable item.
  6. Move accessibility focus to the editable item.
  7. Listen to TalkBack's spoken description of the editable item that now contains text. Check that the description includes the text that you typed.
  8. Open TalkBack's local context menu and switch to the "Character" navigation granularity.
  9. Use swipe gestures to move the editable item's cursor letter-by-letter through the text. Check that TalkBack's spoken description of each navigation action matches the typed characters, not the item's label.

Android's automated testing tools can detect a non-empty contentDescription on editable items. 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.