material-components_material-components-android/docs/components/TextInputLayout.md

Text Fields

TextInputLayout provides an implementation for Material text fields. Used in conjunction with a TextInputEditText, TextInputLayout makes it easy to include Material text fields in your layouts.

TextInputLayout also provides an implementation for the Exposed Dropdown Menu when used in conjuction with an AutoCompleteTextView and a Widget.MaterialComponents.TextInputLayout.*.ExposedDropdownMenu style. For information on the Exposed Dropdown Menu usage, see the Menu documentation.

Design & API Documentation

• Material Design guidelines: Text Fields
• Class definition
• Class overview

Usage

To create a material text field, add a TextInputLayout to your XML layout and a TextInputEditText as a direct child.

<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/hint_text">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>

</com.google.android.material.textfield.TextInputLayout>

Note: A TextInputEditText should be used instead of an EditText as your input text component. An EditText might work, but TextInputEditText provides accessibility support for the text field and allows TextInputLayout greater control over the visual aspects of the input text.

Material Styles

Using TextInputLayout with an updated Material theme (Theme.MaterialComponents) will provide the correct updated Material styles to your text fields by default. If you need to use an updated Material text field and your application theme does not inherit from an updated Material theme, you can apply one of the updated Material styles directly to your widget in XML.

Filled Box (Default)

Filled text fields have a solid background color and draw more attention, especially in layouts where the field is surrounded by other elements. To use a filled text field, apply the following style to your TextInputLayout:

style="@style/Widget.MaterialComponents.TextInputLayout.FilledBox"

To change the background color of a filled text field, you can set the boxBackgroundColor attribute on your TextInputLayout.

Note: When using a filled text field with an EditText child that is not a TextInputEditText, make sure to set the EditText's android:background to @null. This allows TextInputLayout to set a filled background on the EditText.

Outlined Box

Outlined text fields have a stroked border and are less emphasized. To use an outlined text field, apply the following style to your TextInputLayout:

style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox"

To change the stroke color and width for an outline text field, you can set the boxStrokeColor and boxStrokeWidth attributes on your TextInputLayout, respectively.

Note: When using an outlined text field with an EditText child that is not a TextInputEditText, make sure to set the EditText's android:background to @null. This allows TextInputLayout to set an outline background on the EditText.

Height Variations

TextInputLayout provides two height variations for filled and outline text fields, standard and dense. Both box styles default to the standard height.

In order to reduce the height of a text box, you can use a dense style, which will reduce the vertical padding within the text box. You can achieve this by applying the appropriate styles to your TextInputLayout and TextInputEditText, depending on whether you are using a filled or outline text field:

Dense Filled Box

Apply this style to your TextInputLayout: xml style="@style/Widget.MaterialComponents.TextInputLayout.FilledBox.Dense"

Dense Outline Box

Apply this style to your TextInputLayout: xml style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox.Dense"

To change a text box's internal padding and overall dimensions, you can adjust the android:padding attributes on the TextInputEditText.

Corner Radius

• boxCornerRadiusTopStart
• boxCornerRadiusTopEnd
• boxCornerRadiusBottomStart
• boxCornerRadiusBottomEnd

Common features

TextInputLayout provides functionality for a number of Material text field features. These are some commonly used properties you can update to control the look of your text field:

Text field element	Relevant attributes/methods
Label (also called a “Floating Label”)	android:hint app:hintEnabled
Error message	app:errorEnabled #setError(CharSequence)
Error icon	app:errorIconDrawable #setErrorIconDrawable(Drawable)
Helper text	app:helperTextEnabled app:helperText
Placeholder text	app:placeholderText
Character counter	app:counterEnabled app:counterMaxLength
Prefix text	app:prefixText
Suffix text	app:suffixText
End icon mode (password redaction, text clearing and custom mode)	app:endIconMode

Notes about setting the hint

The hint should be set on TextInputLayout, rather than the TextInputEditText or EditText. If a hint is specified on the child EditText in XML, the TextInputLayout might still work correctly; TextInputLayout will use the EditText's hint as its floating label. However, future calls to modify the hint will not update TextInputLayout's hint. To avoid unintended behavior, call setHint() and getHint() on TextInputLayout, instead of on EditText.

Notes about using TextInputLayout programmatically

If you construct the EditText child of a TextInputLayout programmatically, you should use TextInputLayout's context to create the view. This will allow TextInputLayout to pass along the appropriate styling to the TextInputEditText or EditText.

TextInputEditText editText = new TextInputEditText(textInputLayout.getContext());

End Icon Modes

The TextInputLayout provides certain pre-packaged EndIconModes that come with specific behaviors. However, their appearance and behaviors can be customized via the end icon API and its attributes. The TextInputLayout also provides support for a custom end icon, with custom appearance and behaviors.

Note: You should opt to use the EndIconMode API instead of setting an end/right compound drawable on the EditText.

Pre-packaged EndIconModes

Password redaction

If set, a button is displayed to toggle between the password being displayed as plain-text or disguised when the EditText is set to display a password.

<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/hint_text"
    app:endIconMode="password_toggle">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:inputType="textPassword"/>

</com.google.android.material.textfield.TextInputLayout>

Text clearing

If set, a button is displayed when text is present and clicking it clears the EditText field.

<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/hint_text"
    app:endIconMode="clear_text">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>

</com.google.android.material.textfield.TextInputLayout>

Custom EndIconMode

It is possible to set a custom drawable or button as the EditText's end icon via app:endIconMode="custom". You should specify a drawable and content description for the icon, and, optionally, specify custom behaviors.

<com.google.android.material.textfield.TextInputLayout
    android:id="@+id/custom_end_icon"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/hint_text"
    app:endIconMode="custom"
    app:endIconDrawable="@drawable/custom_icon"
    app:endIconContentDescription="@string/custom_content_desc">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>

</com.google.android.material.textfield.TextInputLayout>

Optionally, in code (more info on the section below):

TextInputLayout textInputCustomEndIcon = view.findViewById(R.id.custom_end_icon);

// If the icon should work as button, set an OnClickListener to it
textInputCustomEndIcon
    .setEndIconOnClickListener(/* custom OnClickListener */);

// If any specific changes should be done when the EditText is attached (and
// thus when the end icon is added to it), set an OnEditTextAttachedListener
textInputCustomEndIcon
    .addOnEditTextAttachedListener(/* custom OnEditTextAttachedListener */);

// If any specific changes should be done if/when the endIconMode gets changed,
// set an OnEndIconChangedListener
textInputCustomEndIcon
    .addOnEndIconChangedListener(/* custom OnEndIconChangedListener */);

Customizing the end icon

The following elements can be customized.

End icon element	Relevant attributes/methods
Drawable	app:endIconDrawable
Content description	app:endIconContentDescription
Tint	app:endIconTint
Tint mode	app:endIconTintMode
Functionality	#setEndIconOnClickListener(OnClickListener)
Behavior that depends on the EditText*	#addOnEditTextAttachedListener(OnEditTextAttachedListener)
Behavior if EndIconMode changes**	#addOnEndIconChangedListener(OnEndIconChangedListener)

* Example: The clear text end icon's visibility behavior depends on whether the EditText has input present. Therefore, an OnEditTextAttachedListener is set so things like editText.getText() can be called.

** Example: If the password toggle end icon is set and a different EndIconMode gets set, the TextInputLayout has to make sure that the EditText's TransformationMethod is still PasswordTransformationMethod. Because of that, an OnEndIconChangedListener is used.

Related concepts

• TextView
• Specifying the Input Type (Android Developers Guide)
• Copy and Paste (Android Developers Guide)