TextField

TextField allows for multiple types of text input.

also known as Text Input

A selected text field with a black outline and a default text field with a gray outline.

Usage guidelines

When to use
  • Any time succinct data needs to be entered by a user, like a date, email address, name, or Pin title.
When not to use
  • Situations where long amounts of text need to be entered, since the full content of the TextField will be truncated. Use TextArea instead.

Best practices

A form field asking for a name. Helper text reads, enter your first and last name.
Do

Use helper text for important information. Helper text helps users understand how to complete the text field or to indicate any needed input.

A form field where the gray text inside the field reads, enter your first and last name.
Don't

Put essential information in the placeholder text, instead put it in the helper text.

A form field with a label asking for a username.
Do

Always ensure the text field has a visible label. The label provides context and supports users when filling in information.

A form field without a label, making it unclear what information is expected.
Don't

Remove the label, as this creates accessibility and usability issues.

A form field with an error. The error text reads, this is not a valid web address.
Do

Provide clear and useful error messages that help the user fix the issue. Error messages should be displayed in a timely manner — typically once the field loses focus or when the form is submitted.

A form field with an error. The error text reads, there has been an error.
Don't

Display generic error messages, such as "There is an error" or remove the accompanying icon.

A form with three fields where the website field is marked as optional.
Do

Consider all text fields as required, unless explicitly noted as optional.

A form with three fields where the username field is marked as required.
Don't

Mark fields as required.

A password field with an eye icon that allows the user to show hidden text.
Do

Use the show/hide “eye” icon when asking sensitive information that may need to be double-checked. Used frequently for passwords.

Two short text fields side by side instead of stacked.
Don't

Place fields horizontally. This creates unnecessarily restricted fields and a more complex interaction pattern.

For general Icon best practices, refer to the web Text Field Documentation.

Accessibility

People use Android's accessibility features, such as TalkBack and dynamic text sizing to personalize how they interact with their devices. Supporting these personalizations ensures that everyone has a great user experience. See Material Design and development documentation about accessibility for Android:

Accessible design on Android
Accessible development on Android

Labels

Be sure to provide a unique for each TextField.

Validation

When providing a validation message, make sure the instructions are clear and help users complete the field. For example, "Passwords must contain at least 20 characters". In addition, use the helper text to provide instructions to help users understand how to complete the text field or to indicate any needed input, allowed formats, timing limitations, or other pertinent information.
These practices give users of assistive technologies more information about the form, helping them to fill it out.

Keyboards

Make sure your keyboards match the function of your form field. For example, asking for a phone number should pull up the phone pad keyboard.

Design tokens

Anatomy

See below how the TextField component is constructed.


Variants

  1. With helper text
    Whenever you want to provide more information about a form field, you should use helper text.
  2. Disabled
    Disabled Text Fields cannot be interacted with. They also do not need to meet contrast requirements, so do not use them to present info to the user.
  3. Error
    Text Field can display an error message below the field. Always include an icon to illustrate the error by more than just color.
  4. Success
    Text Field can display a success message below the field. Always include an icon to illustrate the success by more than just color.

With helper text

Disabled

Error

Success

Colors

Overview of how the TextField colors look in both themes.


Light mode

Dark mode

Animation

Visit Apple’s HIG for more information on Animation and Motion.