Skip to content

Latest commit

 

History

History
784 lines (586 loc) · 46.2 KB

File metadata and controls

784 lines (586 loc) · 46.2 KB

Text fields

Text fields let users enter and edit text.

"Text fields on a screen"

Contents

Using text fields

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.

Making text fields accessible

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.

Content description

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.

Custom EditText

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.

Adding a leading icon to a text field

"Text field with a leading icon."

<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>

Adding a trailing icon to a text field

Password toggle:

"Text field with a password toggle trailing icon."

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:

"Text field with a clear text trailing icon."

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:

"Text field with a custom trailing 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.

Implementing an exposed dropdown menu

"Text field with an exposed dropdown menu."

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"
/>

Adding helper text to a text field

"Text field with helper text."

<com.google.android.material.textfield.TextInputLayout
    ...
    app:helperTextEnabled="true"
    app:helperText="@string/helper_text">

    ...

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

Adding a counter to a text field

"Text field with a counter."

<com.google.android.material.textfield.TextInputLayout
    ...
    app:counterEnabled="true"
    app:counterMaxLength="20">

    ...

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

Adding errors to a text field

"Text field with an error."

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.

Adding a prefix/suffix to a text field

"Text field with a prefix/suffix."

<com.google.android.material.textfield.TextInputLayout
    ...
    app:prefixText="@string/prefix"
    app:suffixText="@string/suffix">

    ...

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

Using text fields programmatically

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)

Types

There are two types of text fields: 1. Filled text field, 2. Outlined text field

"Text field types. Fixed: grey back, dark gray indicator turns purple. Outlined: clear back, gray outline turns purple"

Filled 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.

Filled text field examples

API and source code:

The following examples shows a filled text field with a label.

Filled text field

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.

Anatomy and key properties

A filled text field has a filled container, input text, a label, an activation indicator, optional helper/error text and optional leading/trailing icons.

Filled text field anatomy

  1. Container
  2. Leading icon
  3. Label
  4. Input text
  5. Trailing icon
  6. Activation indicator
  7. Helper/error/counter text
  8. 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).

Container attributes

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

Leading icon attributes

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

Label attributes

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.

Input text attributes

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.

Trailing icon attributes

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)

Activation indicator attributes

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

Helper/error/counter text attributes

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

Prefix/suffix attributes

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

Styles

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 field

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.

Outlined text field examples

API and source code:

The following examples shows an outlined text field.

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.

Anatomy and key properties

An outlined text field has a stroked container, input text, a label, optional helper/error text and optional leading/trailing icons.

Outlined text field anatomy

  1. Container
  2. Leading icon
  3. Label
  4. Input text
  5. Trailing icon
  6. Helper/error/counter text
  7. 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).

Container attributes

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

Leading icon attributes

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

Label attributes

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.

Input text attributes

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.

Trailing icon attributes

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)

Helper/error/counter text attributes

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)

Prefix/suffix attributes

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

Styles

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.

Theming text fields

Text fields support Material Theming and can be customized in terms of color, typography and shape.

Text field theming example

API and source code:

The following example shows filled and outlined text field types with Material Theming.

"Filled and outlined text field theming with pink and brown colors and cut corners"

Implementing text field 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.