Text fields let users enter and edit text.
Contents
Before you can use Material text fields, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.
<com.google.android.material.textfield.TextInputLayout
android:id="@+id/textField"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:hint="@string/label">
<com.google.android.material.textfield.TextInputEditText
android:layout_width="match_parent"
android:layout_height="wrap_content"
/>
</com.google.android.material.textfield.TextInputLayout>
Note: A text field is composed of a TextInputLayout
and a
TextInputEditText
as a direct child. Using an EditText
as the child might
work, but TextInputEditText
provides accessibility support for the text field
and allows TextInputLayout
greater control over the visual aspects of the
input text. If an EditText
is being used, make sure to set its
android:background
to @null
so that TextInputLayout
can set the proper
background on it.
Android's text field component APIs support both label text and helper text for informing the user as to what information is requested for a text field. While optional, their use is strongly encouraged.
When using custom icons, you should set a content description on them so that screen readers like TalkBack are able to announce their purpose or action, if any.
For the leading icon, that can be achieved via the
app:startIconContentDescription
attribute or setStartIconContentDescription
method. For the trailing icon, that can be achieved via the
app:endIconContentDescription
attribute or setEndIconContentDescription
method.
When setting an error message that contains special characters that screen
readers or other accessibility systems are not able to read, you should set a
content description via the app:errorContentDescription
attribute or
setErrorContentDescription
method. That way, when the error needs to be
announced, it will announce the content description instead.
If you are using a custom EditText
as TextInputLayout
's child and your text
field requires different accessibility support than the one offered by
TextInputLayout
, you can set a TextInputLayout.AccessibilityDelegate
via the
setTextInputAccessibilityDelegate
method. This method should be used in place
of providing an AccessibilityDelegate
directly on the EditText
.
<com.google.android.material.textfield.TextInputLayout
...
app:startIconDrawable="@drawable/ic_favorite_24dp"
app:startIconContentDescription="@string/content_description_end_icon">
...
</com.google.android.material.textfield.TextInputLayout>
Password toggle:
If set, an icon is displayed to toggle between the password being displayed as
plain-text or disguised (when the TextInputEditText
is set to display a
password).
<com.google.android.material.textfield.TextInputLayout
...
app:endIconMode="password_toggle">
<com.google.android.material.textfield.TextInputEditText
...
android:inputType="textPassword"
/>
</com.google.android.material.textfield.TextInputLayout>
Clear text:
If set, an icon is displayed when text is present and pressing it clears the input text.
<com.google.android.material.textfield.TextInputLayout
...
app:endIconMode="clear_text">
...
</com.google.android.material.textfield.TextInputLayout>
Custom icon:
It is possible to set a custom Drawable
as the text field's trailing icon via
app:endIconMode="custom"
. You should specify a drawable and content
description for the icon, and, optionally, specify custom behaviors.
In the layout:
<com.google.android.material.textfield.TextInputLayout
...
app:endIconMode="custom"
app:endIconDrawable="@drawable/ic_check_circle_24dp"
app:endIconContentDescription="@string/content_description_end_icon">
...
</com.google.android.material.textfield.TextInputLayout>
Optionally, in code:
textField.setEndIconOnClickListener {
// Respond to end icon presses
}
textField.addOnEditTextAttachedListener {
// If any specific changes should be done when the edit text is attached (and
// thus when the trailing icon is added to it), set an
// OnEditTextAttachedListener.
// Example: The clear text 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.
}
textField.addOnEndIconChangedListener {
// If any specific changes should be done if/when the endIconMode gets
// changed, set an OnEndIconChangedListener.
// Example: If the password toggle icon is set and a different EndIconMode
// gets set, the TextInputLayout has to make sure that the edit text's
// TransformationMethod is still PasswordTransformationMethod. Because of
// that, an OnEndIconChangedListener is used.
}
Note: You should opt to use the EndIconMode
API instead of setting an
end/right compound Drawable
on the TextInputEditText
. The same applies to
the now-deprecated passwordToggle*
attributes.
See the full list of end icon modes.
In the layout:
<com.google.android.material.textfield.TextInputLayout
...
style="@style/Widget.MaterialComponents.TextInputLayout.*.ExposedDropdownMenu">
<AutoCompleteTextView
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:inputType="none"
/>
</com.google.android.material.textfield.TextInputLayout>
In code:
val items = listOf("Material", "Design", "Components", "Android")
val adapter = ArrayAdapter(requireContext(), R.layout.list_item, items)
(textField.editText as? AutoCompleteTextView)?.setAdapter(adapter)
In the item layout (list_item.xml
):
<TextView
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:padding="16dp"
android:ellipsize="end"
android:maxLines="1"
android:textAppearance="?attr/textAppearanceSubtitle1"
/>
<com.google.android.material.textfield.TextInputLayout
...
app:helperTextEnabled="true"
app:helperText="@string/helper_text">
...
</com.google.android.material.textfield.TextInputLayout>
<com.google.android.material.textfield.TextInputLayout
...
app:counterEnabled="true"
app:counterMaxLength="20">
...
</com.google.android.material.textfield.TextInputLayout>
In the layout:
<com.google.android.material.textfield.TextInputLayout
...
app:errorEnabled="true">
...
</com.google.android.material.textfield.TextInputLayout>
In code:
// Set error text
passwordLayout.error = getString(R.string.error)
// Clear error text
passwordLayout.error = null
Note: Non-null error text will replace any existing helper text.
<com.google.android.material.textfield.TextInputLayout
...
app:prefixText="@string/prefix"
app:suffixText="@string/suffix">
...
</com.google.android.material.textfield.TextInputLayout>
If you construct the TextInputEditText
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
edit text.
val textInputLayout = TextInputLayout(context)
val editText = TextInputEditText(textInputLayout.context)
There are two types of text fields: 1. Filled text field, 2. Outlined text field
Filled text fields have more visual emphasis than outlined text fields, making them stand out when surrounded by other content and components.
Note: The filled text field is the default style if the style is not set.
API and source code:
TextInputLayout
TextInputEditText
The following examples shows a filled text field with a label.
In the layout:
<com.google.android.material.textfield.TextInputLayout
android:id="@+id/filledTextField"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:hint="@string/label">
<com.google.android.material.textfield.TextInputEditText
android:layout_width="match_parent"
android:layout_height="wrap_content"
/>
</com.google.android.material.textfield.TextInputLayout>
In code:
// Get input text
val inputText = filledTextField.editText?.text.toString()
filledTextField.editText?.doOnTextChanged { inputText, _, _, _ ->
// Respond to input text change
}
See the using text fields section above for more examples.
A filled text field has a filled container, input text, a label, an activation indicator, optional helper/error text and optional leading/trailing icons.
- Container
- Leading icon
- Label
- Input text
- Trailing icon
- Activation indicator
- Helper/error/counter text
- Prefix/suffix/placeholder (not shown)
Note: All the attributes on the tables below should be set on the
TextInputLayout
, with the exception of the input text attributes (which should
be set on the TextInputEditText
).
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Color | app:boxBackgroundColor |
setBoxBackgroundColor setBoxBackgroundColorResource getBoxBackgroundColor |
?attr/colorOnSurface at 12% opacity (see all states) |
Shape | app:shapeAppearance |
N/A | ?attr/shapeAppearanceSmallComponent |
Text field enabled | android:enabled |
setEnabled |
true |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Icon | app:startIconDrawable |
setStartIconDrawable getStartIconDrawable |
null |
Content description | app:startIconContentDescription |
setStartIconContentDescription getStartIconContentDescription |
null |
Color | app:startIconTint |
setStartIconTintList |
colorOnSurface at 54% opacity (see all states) |
Checkable | app:startIconCheckable |
setStartIconCheckable isStartIconCheckable |
false |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Text | android:hint |
setHint getHint |
null |
Color | android:textColorHint |
setDefaultHintTextColor getDefaultHintTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Collapsed (floating) color | app:hintTextColor |
setHintTextColor getHintTextColor |
?attr/colorPrimary |
Typography | app:hintTextAppearance |
setHintTextAppearance |
?attr/textAppearanceCaption |
Animation | app:hintAnimationEnabled |
setHintAnimationEnabled isHintAnimationEnabled |
true |
Expanded enabled | app:expandedHintEnabled |
setExpandedHintEnabled isExpandedHintEnabled |
true |
Note: The android:hint
should always be set on the TextInputLayout
instead of on the EditText
in order to avoid unintended behaviors.
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Input text | android:text |
setText getText |
@null |
Typography | android:textAppearance |
setTextAppearance |
?attr/textAppearanceSubtitle1 |
Input text color | android:textColor |
setTextColor getTextColors getCurrentTextColor |
?android:textColorPrimary |
Cursor color | N/A (color comes from the theme attr ?attr/colorControlActivated ) |
N/A | ?attr/colorPrimary |
Note: The input text attributes should be set on the TextInputEditText
.
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Mode | app:endIconMode |
setEndIconMode getEndIconMode |
END_ICON_NONE |
Color | app:endIconTint |
setEndIconTintList |
colorOnSurface at 54% opacity and colorPrimary (activated) (see all states) |
Custom icon | app:endIconDrawable |
setEndIconDrawable getEndIconDrawable |
null |
Custom icon content description | app:endIconContentDescription |
setEndIconContentDescription getEndIconContentDescription |
null |
Custom icon checkable | app:endIconCheckable |
setEndIconCheckable isEndIconCheckable |
true |
Error icon | app:errorIconDrawable |
setErrorIconDrawable getErrorIconDrawable |
@drawable/mtrl_ic_error |
Error icon color | app:errorIconTint |
setErrorIconTintList |
?attr/colorError (see all states) |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Color | app:boxStrokeColor |
setBoxStrokeColor setBoxStrokeColorStateList getBoxStrokeColor |
?attr/colorOnSurface at 42% opacity and ?attr/colorPrimary (focused) (see all states) |
Error color | app:boxStrokeErrorColor |
setBoxStrokeErrorColor getBoxStrokeErrorColor |
?attr/colorError (see all states) |
Width | app:boxStrokeWidth |
N/A | 1dp |
Focused width | app:boxStrokeWidthFocused |
N/A | 2dp |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Helper text enabled | app:helperTextEnabled |
setHelperTextEnabled isHelperTextEnabled |
false |
Helper text | app:helperText |
setHelperText getHelperText |
null |
Helper text color | app:helperTextColor |
setHelperTextColor getHelperTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Helper text typography | app:helperTextAppearance |
setHelperTextAppearance |
?attr/textAppearanceCaption |
Error text enabled | app:errorEnabled |
setErrorEnabled isErrorEnabled |
false |
Error text | N/A | setError getError |
null |
Error text color | app:errorTextColor |
setErrorTextColor getErrorCurrentTextColors |
?attr/colorError (see all states |
Error text typography | app:errorTextAppearance |
setErrorTextAppearance |
?attr/textAppearanceCaption |
Counter text enabled | app:counterEnabled |
setCounterEnabled isCounterEnabled |
false |
Counter text length | app:counterMaxLength |
setCounterMaxLength getCounterMaxLength |
-1 |
Counter text typography | app:counterTextAppearance app:counterOverflowTextAppearance |
setCounterTextAppearance setCounterOverflowTextAppearance |
?attr/textAppearanceCaption |
Counter text color | app:counterTextColor app:counterOverflowTextColor |
setCounterTextColor setCounterOverflowTextColor getCounterTextColor getCounterOverflowTextColor |
?attr/colorOnSurface at 60% (app:counterTextColor ) (see all states)?attr/colorError (app:counterOverflowTextColor ) (see all states |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Prefix | app:prefixText |
setPrefixText getPrefixText |
null |
Prefix color | app:prefixTextColor |
setPrefixTextColor getPrefixTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Prefix typography | app:prefixTextAppearance |
setPrefixTextAppearance |
?attr/textAppearanceSubtitle1 |
Suffix | app:suffixText |
setSuffixText getSuffixText |
null |
Suffix color | app:suffixTextColor |
setSuffixTextColor getSuffixTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Suffix typography | app:suffixTextAppearance |
setSuffixTextAppearance |
?attr/textAppearanceSubtitle1 |
Element | Style |
---|---|
Default style | Widget.MaterialComponents.TextInputLayout.FilledBox |
Dense style | Widget.MaterialComponents.TextInputLayout.FilledBox.Dense |
Exposed dropdown menu style | Widget.MaterialComponents.TextInputLayout.FilledBox.ExposedDropdownMenu |
Dense exposed dropdown menu style | Widget.MaterialComponents.TextInputLayout.FilledBox.Dense.ExposedDropdownMenu |
Default style theme attribute: ?attr/textInputStyle
See the full list of styles and attrs.
Outlined text fields have less visual emphasis than filled text fields. When they appear in places like forms, where many text fields are placed together, their reduced emphasis helps simplify the layout.
API and source code:
TextInputLayout
TextInputEditText
The following examples shows an outlined text field.
In the layout:
<com.google.android.material.textfield.TextInputLayout
android:id="@+id/outlinedTextField"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:hint="@string/label"
style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox">
<com.google.android.material.textfield.TextInputEditText
android:layout_width="match_parent"
android:layout_height="wrap_content"
/>
</com.google.android.material.textfield.TextInputLayout>
In code:
// Get input text
val inputText = outlinedTextField.editText?.text.toString()
outlinedTextField.editText?.doOnTextChanged { inputText, _, _, _ ->
// Respond to input text change
}
See the using text fields section above for more examples.
An outlined text field has a stroked container, input text, a label, optional helper/error text and optional leading/trailing icons.
- Container
- Leading icon
- Label
- Input text
- Trailing icon
- Helper/error/counter text
- Prefix/suffix/placeholder (not shown)
Note: All the attributes on the tables below should be set on the
TextInputLayout
, with the exception of the input text attributes (which should
be set on the TextInputEditText
).
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Stroke color | app:boxStrokeColor |
setBoxStrokeColor setBoxStrokeColorStateList getBoxStrokeColor |
?attr/colorOnSurface at 38% opacity and ?attr/colorPrimary (focused) (see all states) |
Stroke error color | app:boxStrokeErrorColor |
setBoxStrokeErrorColor getBoxStrokeErrorColor |
?attr/colorError (see all states) |
Stroke width | app:boxStrokeWidth |
N/A | 1dp |
Stroke focused width | app:boxStrokeWidthFocused |
N/A | 2dp |
Shape | app:shapeAppearance |
N/A | ?attr/shapeAppearanceSmallComponent |
Text field enabled | android:enabled |
setEnabled |
true |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Icon | app:startIconDrawable |
setStartIconDrawable getStartIconDrawable |
null |
Content description | app:startIconContentDescription |
setStartIconContentDescription getStartIconContentDescription |
null |
Color | app:startIconTint |
setStartIconTintList |
colorOnSurface at 60% opacity (see all states) |
Checkable | app:startIconCheckable |
setStartIconCheckable isStartIconCheckable |
false |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Text | android:hint |
setHint getHint |
null |
Color | android:textColorHint |
setDefaultHintTextColor getDefaultHintTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Collapsed (floating) color | app:hintTextColor |
setHintTextColor getHintTextColor |
?attr/colorPrimary |
Typography | app:hintTextAppearance |
setHintTextAppearance |
?attr/textAppearanceCaption |
Note: The android:hint
should always be set on the TextInputLayout
instead of on the EditText
in order to avoid unintended behaviors.
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Input text | android:text |
setText getText |
@null |
Typography | android:textAppearance |
setTextAppearance |
?attr/textAppearanceSubtitle1 |
Input text color | android:textColor |
setTextColor getTextColors getCurrentTextColor |
?android:textColorPrimary |
Cursor color | N/A (color comes from the theme attr ?attr/colorControlActivated ) |
N/A | ?attr/colorPrimary |
Note: The input text attributes should be set on the TextInputEditText
.
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Mode | app:endIconMode |
setEndIconMode getEndIconMode |
END_ICON_NONE |
Color | app:endIconTint |
setEndIconTintList |
colorOnSurface at 60% opacity and colorPrimary (activated) (see all states) |
Custom icon | app:endIconDrawable |
setEndIconDrawable getEndIconDrawable |
null |
Custom icon content description | app:endIconContentDescription |
setEndIconContentDescription getEndIconContentDescription |
null |
Custom icon checkable | app:endIconCheckable |
setEndIconCheckable isEndIconCheckable |
true |
Error icon | app:errorIconDrawable |
setErrorIconDrawable getErrorIconDrawable |
@drawable/mtrl_ic_error |
Error icon color | app:errorIconTint |
setErrorIconTintList |
?attr/colorError (see all states) |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Helper text enabled | app:helperTextEnabled |
setHelperTextEnabled isHelperTextEnabled |
false |
Helper text | app:helperText |
setHelperText getHelperText |
null |
Helper text color | app:helperTextColor |
setHelperTextColor getHelperTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Helper text typography | app:helperTextAppearance |
setHelperTextAppearance |
?attr/textAppearanceCaption |
Error text enabled | app:errorEnabled |
setErrorEnabled isErrorEnabled |
false |
Error text | N/A | setError getError |
null |
Error text color | app:errorTextColor |
setErrorTextColor getErrorCurrentTextColors |
?attr/colorError (see all states |
Error text typography | app:errorTextAppearance |
setErrorTextAppearance |
?attr/textAppearanceCaption |
Counter text enabled | app:counterEnabled |
setCounterEnabled isCounterEnabled |
false |
Counter text length | app:counterMaxLength |
setCounterMaxLength getCounterMaxLength |
-1 |
Counter text typography | app:counterTextAppearance app:counterOverflowTextAppearance |
setCounterTextAppearance setCounterOverflowTextAppearance |
?attr/textAppearanceCaption |
Counter text color | app:counterTextColor app:counterOverflowTextColor |
setCounterTextColor setCounterOverflowTextColor getCounterTextColor getCounterOverflowTextColor |
?attr/colorOnSurface at 60% (app:counterTextColor ) (see all states)?attr/colorError (app:counterOverflowTextColor ) (see all states) |
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
Prefix | app:prefixText |
setPrefixText getPrefixText |
null |
Prefix color | app:prefixTextColor |
setPrefixTextColor getPrefixTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Prefix typography | app:prefixTextAppearance |
setPrefixTextAppearance |
?attr/textAppearanceSubtitle1 |
Suffix | app:suffixText |
setSuffixText getSuffixText |
null |
Suffix color | app:suffixTextColor |
setSuffixTextColor getSuffixTextColor |
?attr/colorOnSurface at 60% opacity (see all states) |
Suffix typography | app:suffixTextAppearance |
setSuffixTextAppearance |
?attr/textAppearanceSubtitle1 |
Element | Style |
---|---|
Default style | Widget.MaterialComponents.TextInputLayout.OutlinedBox |
Dense style | Widget.MaterialComponents.TextInputLayout.OutlinedBox.Dense |
Exposed dropdown menu style | Widget.MaterialComponents.TextInputLayout.OutlinedBox.ExposedDropdownMenu |
Dense exposed dropdown menu style | Widget.MaterialComponents.TextInputLayout.OutlinedBox.Dense.ExposedDropdownMenu |
Default style theme attribute: ?attr/textInputStyle
See the full list of styles and attrs.
Text fields support Material Theming and can be customized in terms of color, typography and shape.
API and source code:
TextInputLayout
TextInputEditText
The following example shows filled and outlined text field types with Material Theming.
Using theme attributes and styles in res/values/styles.xml
(themes all text
fields and affects other components):
<style name="Theme.App" parent="Theme.MaterialComponents.*">
...
<item name="colorPrimary">@color/shrine_pink_100</item>
<item name="colorOnSurface">@color/shrine_pink_900</item>
<item name="colorError">@color/shrine_red</item>
<item name="textAppearanceSubtitle1">@style/TextAppearance.App.Subtitle1</item>
<item name="textAppearanceCaption">@style/TextAppearance.App.Caption</item>
<item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
</style>
<style name="TextAppearance.App.Subtitle1" parent="TextAppearance.MaterialComponents.Subtitle1">
<item name="fontFamily">@font/rubik</item>
<item name="android:fontFamily">@font/rubik</item>
</style>
<style name="TextAppearance.App.Caption" parent="TextAppearance.MaterialComponents.Caption">
<item name="fontFamily">@font/rubik</item>
<item name="android:fontFamily">@font/rubik</item>
</style>
<style name="ShapeAppearance.App.SmallComponent" parent="ShapeAppearance.MaterialComponents.SmallComponent">
<item name="cornerFamily">cut</item>
<item name="cornerSize">4dp</item>
</style>
or using default style theme attributes, styles and theme overlays (themes all text fields but does not affect other components):
<style name="Theme.App" parent="Theme.MaterialComponents.*">
...
<item name="textInputStyle">@style/Widget.App.TextInputLayout</item>
</style>
<style name="Widget.App.TextInputLayout" parent="Widget.MaterialComponents.TextInputLayout.*">
<item name="materialThemeOverlay">@style/ThemeOverlay.App.TextInputLayout</item>
<item name="shapeAppearance">@style/ShapeAppearance.App.SmallComponent</item>
<item name="hintTextColor">?attr/colorOnSurface</item>
</style>
<style name="ThemeOverlay.App.TextInputLayout" parent="">
<item name="colorPrimary">@color/shrine_pink_100</item>
<item name="colorOnSurface">@color/shrine_pink_900</item>
<item name="colorError">@color/shrine_red</item>
<item name="textAppearanceSubtitle1">@style/TextAppearance.App.Subtitle1</item>
<item name="textAppearanceCaption">@style/TextAppearance.App.Caption</item>
<item name="editTextStyle">@style/Widget.MaterialComponents.TextInputEditText.*</item>
</style>
or using one the style in the layout (affects only this text field):
<com.google.android.material.textfield.TextInputLayout
...
style="@style/Widget.App.TextInputLayout">
...
</com.google.android.material.textfield.TextInputLayout>
Note: When setting a materialThemeOverlay
on a custom TextInputLayout
style, don't forget to set editTextStyle
to either a
@style/Widget.MaterialComponents.TextInputEditText.*
style or to a custom one
that inherits from that.
The TextInputLayout
styles set materialThemeOverlay
that overrides
editTextStyle
with the specific TextInputEditText
style needed. Therefore,
you don't need to specify a style tag on the edit text.