Version 5.2.0

Text field

Text fields are text boxes that allow users to input custom text entries with a keyboard. Various decorations can be displayed around the field to communicate the entry requirements.


Image illustrating through labels the component parts of a text field including its label, a required asterisk, character count, placeholder text, validation marker, content area for error text and the text field.


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 a placeholder.


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 showing a label on top of a text field. An example email address is placed as a placeholder inside the text field.


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

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.


The value shows a user’s entered text.

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


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

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.


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


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.


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, Text field shows visual change when moused over, but text can still be selected.


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.

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
text / nothing
label position
top / side
text / nothing
is quiet
yes / no
necessity indicator
text / icon / nothing
is required
yes / no
has character count
yes / no
show valid icon
yes / no
is error
yes / no
If there’s an error, this property overrides show valid icon.
is disabled
yes / no
is read-only
yes / no


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 (–).

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.


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


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#

TabTabbing into a text field selects the existing text.


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

Multiple options

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

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

Defined behaviors

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

Usage guidelines

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

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

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 included in Spectrum DNA.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.