Spectrum
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.
Table of contents#
Anatomy#
Options#
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”).
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.
Value#
The value shows a user’s entered text.
Width#
The width of a text field can be customized appropriately for its context.
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.
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. Too many quiet components in a small space can be hard to read.
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.
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.
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 icon appears as soon as a user types a valid entry in the field.
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.
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.
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.
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.
Input type#
A text field can have multiple input types, depending on the need and use case. Text fields have a text input type by default.
Use these input types for the following use cases:
- Text defines a single-line text field.
- URL defines a field for entering a URL.
- Phone defines a field for entering a telephone number.
- Email defines a field for entering an email address.
- Password defines a password field. As a user enters a value, the text changes to dots.
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.
| Property | Values | Default value |
|---|---|---|
| label | text / nothing | – |
| label position | top / side | top |
| 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 |
| input type | text / url / phone / email / password | text |
Behaviors#
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.
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.
Mixed value#
When a text field presents multiple values that are not identical, the field should show an en dash (–).
Help text overflow#
When the help text is too long for the available horizontal space, it wraps to form another line.
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.
Usage guidelines#
Include a label#
Every text field should have a label. A field without a label is ambiguous and not accessible.
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”).
Follow capitalization rules#
Field labels should be in sentence case.
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.
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.
Don’t use placeholder 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, 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, 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, especially if they're communicating the same thing.
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).
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.”
Internationalization#
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#
| Key | Interaction |
|---|---|
| Tab | Tabbing into a text field selects the existing text. |
Theming#
A theme is an intentional, systematic customization of Spectrum. It has unique visual attributes. For more information, view Theming.
Spectrum for Adobe Express#
Text fields in Spectrum for Adobe Express have more rounding and a thicker border.
Changelog#
| Date | Number | Notes |
|---|---|---|
| Feb 24, 2023 | 9.0.0 |
|
| Apr 06, 2022 | 8.0.0 |
|
| Feb 23, 2022 | 7.1.0 |
|
| Feb 07, 2022 | 7.0.0 |
|
| Dec 13, 2021 | 6.1.0 |
|
| Oct 04, 2021 | 6.0.0 |
|
| Feb 26, 2020 | 5.2.0 |
|
| Aug 22, 2019 | 5.1.0 |
|
| Apr 20, 2019 | 5.0.0 |
|
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.
Text area