Version 6.0.0

Text field

Text fields allow users to input custom text entries with a keyboard. Various options can be shown with the field to communicate the input requirements.

Three text fields arranged vertically and labeled Email address, Password and Job title.

Anatomy#


Image illustrating through labels the component parts of a text field including its field, label, required asterisk, value or placeholder, character count, validation marker, and help text, description or error message.

Options#


Key example displaying the standard option for a label with the text "Email address" on top of a text field with an email address as value text.

Label#

Text fields should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These text fields without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”).

Key example showing two text fields. The first field positions the label on top. The second field aligns the label on the left.

Label position#

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.

Key example of placeholder option. Text field, label Email address. Placeholder text, wilson@adobe.com.

Placeholder#

The placeholder text, also commonly known as “ghost text,” is temporary and disappears once a user enters text.

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible. Once a value is entered, this text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text. Help text is the preferred way to communicate this information.

Key example showing a text field with entered text and a label. The entered value of the text field appears in a darker text color than the placeholder color.

Value#

The value shows a user’s entered text.

Key example showing two text fields where the width of the second text field is wider.

Width#

The width of a text field can be customized appropriately for its context.

Key example of four text fields showing the size options available including small, medium, large, and extra-large. Text field label, Email address. Entered text, wilson@adobe.com.

Size#

Text fields come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.

Key example showing the quiet text field option. The first text field follows the standard option and the second quiet text field has no visible background and the background color of the page appears behind the text.

Quiet#

By default, text fields have a visible background. This style works best in a dense array of controls where the background helps to separate the input from the surrounding container, or to give visibility to isolated buttons.

Alternatively, quiet text fields can have no visible background. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read.

Key example showing the required or optional labels with three text fields. The first text field features the word "optional" in parentheses. the second field places "required" in parentheses and the last text field features an asterisk behind the label.

Required or optional#

Text fields can be marked as optional or required, depending on the situation. For required text fields, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional text fields are either denoted with text added to the end of the label — “(optional)” — or have no indication at all.

The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.

Key example showing a text field with a character count label above. The number 24 is displayed on the right side of the label, aligned with the right side of the text field, referring to 24 more characters that can be typed into the text field.

Character count#

Text fields can display a character count indicator when the length of the text entry needs to be kept under a predefined value. Character count indicators can be used in conjunction with other indicators (validation icon, “optional” or “required” indicators) when necessary.

Key example showing a validated email text field with the label "Email address" and the typed in email address user@adobe.com. A green checkmark is placed in the right side of the field.

Validation icon#

Text fields can display a validation icon when the text entry is expected to conform to a specific format (e.g., email address, credit card number, password creation requirements, etc.). The validation icon appears as soon as a user types a valid entry in the field.

Key example showing the error option of a text field. The text field features a red border and a red alert icon is placed inside the text field on the right.

Error#

A text field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. If an error exists, the error icon always overrides the validation icon.

Key example showing the disabled text field option. The text field background is grayed out, matching the gray border of the text field.

Disabled#

A text field in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a field may become available later.

Key example of read-only text fields. Label, Email address. Selected value, user@adobe.com. Text field shows visual change when moused over, but text can still be selected.

Read-only#

Text fields have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed. A text field does not have a read-only option if there is nothing entered in it.

Two examples of text fields showing help text. First example, a required text field. Label, Password. Placeholder text, Enter password. Help text description, Password must be at least 8 characters. Second example, a required text field. Label, Email address. Placeholder text, wilson@adobe.com. Error message, Enter your email address.

Help text (description and error message)#

A text field can have help text below the field to give extra context or instruction about what a user should input in the field. The help text area has two options: a description and an error message. The description communicates a hint or helpful information, such as specific requirements for correctly filling out the field. The error message communicates an error for when the field requirements aren’t met, prompting a user to adjust what they had originally input.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
label
text / nothing
label position
top / side
top
placeholder
text
value
text / nothing
width
number
size
small / medium / large / extra-large
medium
is quiet
yes / no
no
necessity indicator
text / icon / nothing
icon
is required
yes / no
no
has character count
yes / no
no
show valid icon
yes / no
no
is error
yes / no
If there’s an error, this property overrides show valid icon.
no
is disabled
yes / no
no
is read-only
yes / no
no
description
text / nothing
nothing
error message
text / nothing
nothing

Behaviors#


Key example displaying a standard and a quiet text field for entering the state id. "CA" for California is entered in both fields and enough padding surrounds the entered text.

Minimum width#

The minimum width for a text field is 1.5× the height of the field, for both standard style and quiet style. This minimum width guarantees that small text fields are readable and easy to target on touch devices.

Key example showing the overflow behavior for text field and text field label.

Text overflow#

When the field label is too long for the available horizontal space, it wraps to form another line. The field text itself truncates.

Key example showing the behavior for mixed values. The textfield value is an en dash for the label "Width".

Mixed value#

When a text field presents multiple values that are not identical, the field should show an en dash (–).

Key example of a text field with help text that has wrapped to a second line. Required field, label Password. Help text description, Password must be at least 8 characters.

Help text overflow#

When the help text is too long for the available horizontal space, it wraps to form another line.

Key example of text fields in Windows “high contrast black” theme with label “Text field” and disabled text field with label “Disabled text field” and generic “value text” inside both fields.

Windows high contrast mode#

In Windows high contrast mode, text field should be displayed using the high contrast theme-specified colors for buttons. By default, border color should be the same as the button text color and labels should use default text color. In hover and keyboard focus states, the border color should display as the button border color. In the disabled state, border and text color should display as the disabled color.

Text field (Windows high contrast mode) UI kit

Usage guidelines#


Include a label#

Every text field should have a label. A field without a label is ambiguous and not accessible.

Key example showing the correct use of a label.
Key example showing the incorrect use of a label. The label is missing from the text field.

Review label-less designs#

In rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”).

Key example showing the correct use of a label-less text field. The text field is acting as a page counter for a pagination component, indicating page 2 followed by a text string containing the total page count "of 89 pages".

Follow capitalization rules#

Field labels and placeholder text should be in sentence case.

Key example showing the correct sentence case capitalization rule. The first letter of the label "Email address" is capitalized.
Key example showing the incorrect sentence case capitalization rule. The first letter of each word from the label "Email Address" are capitalized.

Mark the minority of text fields in a form as required or optional#

In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. If most of the text fields are optional, only the required fields should be give an asterisk or have labels appended with “(required)”. If most of the text fields are required, only the optional fields should be appended with “(optional)”. An asterisk should never be used to note that a text field is optional.

Key example showing the correct usage of limiting the required label. Two of the three text fields for the first name, last name and email address are required as the last label features the word "optional in parentheses.
Key example showing the incorrect usage of marking text fields as required. Two of the three text fields feature the word "required" in parentheses while the last text field does not feature the word "required" in the label marking it as optional.

Use help text to show hints, formatting, and requirements#

The description in the help text is flexible and encompasses a range of guidance. Sometimes this guidance is about what to input, and sometime it’s about how to input. This includes information such as:

  • An overall description of the input field
  • Hints for what kind of information needs to be input
  • Specific formatting examples or requirements

The help text’s message should not simply restate the same information in the label in order to prompt someone to interact with it. Don’t add help text if it isn’t actually relevant or meaningful to a user in order to try to maintain layout continuity with other inputs that require help text.

Key example of correct usage of help text. Text field, label Email address. Help text, wilson@adobe.com.
Key example of incorrect usage of help text. Text field, label Email address. Help text, Enter your email address.

Use help text instead of placeholder text#

Putting instructions for how to complete an input, requirements, or any other essential information into placeholder text is not accessible, and should be avoided if possible. Once a value is entered, placeholder text is no longer viewable; if someone is using an automatic form filler, they will never get the information in the placeholder text.

Instead of placeholder text, use the help text description to convey requirements or to show any formatting examples that would help user comprehension. If there's placeholder text and help text at the same time, it becomes redundant and distracting, and especially if they're communicating the same thing.

Key example of correct usage of help text. Text field, label Email address. Help text, wilson@adobe.com.
Key example of cautionary usage of placeholder text. Text field, label Email address. Placeholder text, wilson@adobe.com.

Switch help text with error text#

The help text area also displays an error message. When a text field already includes help text and an error is triggered, the help text is replaced with error text. Once the error is resolved, the help text description reappears below the field.

Since one gets replaced by the other, the language of the help text and error text need to work together to convey the same messaging. Help text explains the requirement or adds supplementary context for how to successfully complete the input. Error text tells a user how to fix the error by re-stating the input requirements or describing the necessary interaction. Make sure that the help text and the error text include the same essential information so that it isn’t lost if one replaces the other (e.g., password requirements).

Key example of correct usage of switching help text with error text. Required text field, label Password. Help text in grey color, Passwords must be at least 8 characters. Error text in red color, Create a password with at least 8 characters.
Key example of incorrect usage of switching help text with error text. Required text field, label Password. Help text in grey color, Passwords must be at least 8 characters. Error text in red color, Passwords must be at least 8 characters.

Write error text that shows a solution#

Write error messaging in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user.

Error text should be written in 1-2 short, complete sentences and in a clear and straightforward way. End sentences with a period, and never with an exclamation point. For text fields, the nature of the error is often related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their email address, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter your email address.”

2 key examples of correct way of writing error text. Required form field, label Credit card number, error text, Enter your credit card number. Required form field, label Password, error text, Create a password with at least 8 characters.
2 key examples of correct way of writing error text. Required form field, label Credit card number, error text, Invalid field. Required form field, label Password, error text, Password requirements not met!

Internationalization#


Key example featuring the usage of text fields for right-to-left languages. The three text fields and their labels are horizontally mirrored.

RTL#

For RTL (right-to-left) languages, the layout of the text field is mirrored. The label is right-aligned and various decorations (character count, validation marker, error icon) are left-aligned. Make sure to consider that some types of content (e.g., email addresses) are not translated.

Keyboard interactions#


KeyInteraction
TabTabbing into a text field selects the existing text.

Changelog#


DateNumberNotes
Oct 04, 20216.0.0
  • Added size option
Feb 26, 20205.2.0
  • Added read-only option
  • Updated border color to be more accessible
Aug 22, 20195.1.0
  • Added text overflow behavior
Apr 20, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added RTL (right-to-left) guidelines

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Accessible use of color

Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).

Accessible contrast for text

Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).

Accessible contrast for UI components

Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).

Content design

UI language and information design considerations have been incorporated into component design.

Defined options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

Defined behaviors

Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don'ts that highlight best practices and common mistakes.

Writing guidelines

Includes content standards or usage guidelines for how to write or format in-product content for the component.

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are available as design tokens.

UI kit

Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.

Generated UI kit

Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.