Editable View labels

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 users navigate 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 addition to the descriptive label.

When a user navigates at a lower granularity, such as character by character, the screen reader speaks the entered text, or the hint when empty.

Testing

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

1. Turn on TalkBack.
2. In the app, move accessibility focus to the empty editable item.
   • Check whether TalkBack's spoken description of the empty editable item contains a label, and whether that descriptive label matches any visual labels in the app.
3. Type some text in the editable item.
4. Move accessibility focus to the editable item.
   • To check that the spoken description includes your typed text, listen to TalkBack's description of the editable item.

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.