Text field

TextField allows for multiple types of 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 inputted text of the TextField could be truncated. Use TextArea instead.

Best practices

For general text field best practices, refer to the Web Text Field Documentation.

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 make sure 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. Users can lose context on what is required in the field.

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 on time — 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 leading 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 often 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.

Accessibility

People use Apple’s accessibility features, such as reduced transparency, VoiceOver, and increased text size to personalize how they interact with their device. Supporting these personalizations ensures that everyone has a great user experience. See Apple’s Human Interface Guidelines and documentation about accessibility for iOS:

Accessible design on iOS

, Opens a new tab

Accessible development on iOS
, Opens a new tab

Labels

Be sure to provide a unique label 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". Additional helpful information could be, indicating which input is needed, describing allowed formats, timing limitations, etc.
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 can't be interacted with. They also don't need to meet contrast requirements, so don't 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.
A form field with helper text under the form that reads, enter a valid web address.

With helper text

A disabled text field that is grayed out and not interactive.

Disabled

A form field with an error. The error text reads, that username is not available.

Error

A text field that was successfully submitted. The success text reads, that username is available.

Success

Colors

Overview of how the TextField colors look in both themes.


Light mode

Dark mode

Edit page on GitHub