Text input and text area components are not used for the same purpose. Consider the use case and the expected length of a user’s answer when choosing between them.
Component
Use case
Text input
For single-line, short entries, use the text input component. It’s commonly used for name, phone number, or email entries in forms.
If text exceeds more than one line, use the text area component. The larger field size encourages longer responses. It’s typically used for comments or questions in forms.
Anatomy
Copy link to this section
You can find the default text input, the text input with a button, and the password input. Password inputs include a hide/show control and can’t contain a button.
With or without button
Default text input contains a label, modifiers to add placeholder text, an icon, helper text, and an error state. There is a variant that adds a button for inputs that may require independent entry submissions, such as coupon codes or search fields.
The default text input includes five main elements. All elements are optional, except the label and text input field.
Label: describes the purpose of the field.
Icon: appears before the text within the input field.
Helper text: informs the user how to format or enter text.
Placeholder text: offers contextual guidance.
Text input: displays input field container.
The text input with button variant includes six main elements. All elements are optional except the label and text input field.
Label: describes the purpose of the field.
Icon: appears before the text within the input field.
Helper text: informs the user how to format or enter text.
Placeholder text: offers contextual guidance.
Text input: displays input field container.
Button: submits data, includes label, and optional icon.
Password input
Password fields function identically to standards input fields, except for a show/hide control outside the field and not being able to have a button. The control alternately makes the password text visible or obscures it with dots.
There are five elements included in the anatomy of the password input:
Label: describes the purpose of the field.
Text: the password itself, in this view visible and unobscured.
Helper text: describes the password’s format or guidelines.
Input field: the container for the password field.
Show/Hide control: obscures password or makes password visible. “Show” mode is on.
Password input with “Hide” control on and password obscured with dots. This view emphasizes:
Obscured password: dots that hide password text.
Show/Hide control: obscures password or makes password visible. “Hide” mode is on.
Articles
Copy link to this section
Checklist for mobile input fields
Read the Nielsen Norman Group's article on input fields.
Error-message guidelines
Read the Nielsen Norman Group's article on error messages.
Feedback
Contents
Contents
Usage
Copy link to this section
Text inputs are commonly applied in forms to collect information from users. They are used to enter names, email address, addresses, passwords, phone numbers, and other types of plain text. It is extremely important for the user experience to correctly format the content and design for text inputs, following the instructions to provide clear labels and explanatory helper text.
The text input’s label should provide a clear, concise description of what you’re asking from the user. It is not recommended that you use placeholder text to provide instructions, examples, or formatting requirements, as it disappears once a user begins typing within the input. Anything considered critical information, or information that would help the user accurately enter a response into the input, should remain visible at all times (read content guidelines).
It is also necessary to identify which inputs are required and which are optional. Required inputs are those which are mandatory for submission or completion of the form. The recommended method for indicating a required input is to include a red asterisk (Red 700) next to the label. Inputs that are not required should display “(optional)” within their label. Optional inputs are used to gather additional information or preferences, but should be limited to reduce cognitive load. For more information on required and optional fields, read about visual indicators in the form pattern.
Formatting inputs
Text input components can contain masking, which depending upon development or business requirements, will help prevent formatting issues for dates, addresses, currency, phone numbers, and around localization. Applying a mask will add a structure to the text field, like parentheses and hyphens to phone numbers, that will help users add information correctly. Adding a clear helper text together with the mask is always preferred.
Email addresses
Fields to enter an email address should appear in contact forms, user registration, subscriptions, or in cases where users might need confirmations or follow ups. Although email fields appear and function identically to default input fields, the ‘input type’ property should be set to ‘email’. This will display the appropriate virtual keyboard on supported devices such as phones and tablets.
Phone numbers
For phone number text inputs, there are two general functions that impact design: internationalization and localization. For localized forms with phone numbers, the recommended best practice is to use one field for the entire phone number, along with geolocation and input masking. As the user fills in the field, parentheses and hyphens are applied automatically. In this case, the helper text might say: “Enter a 10-digit phone number” or otherwise show an example of the expected format.
Use masking when formatting the text would help users to enter a correctly formatted input and also improve readability.
An example of a phone number added to the input.
Depending on localization or internationalization design requirements, product teams can choose whether to implement a separate select component for country code selection. If opting to support a separate country code selector, a select menu is required. The country selector will default to the page’s localization and validate against the country’s formatting guidelines. See accessibility standards for more guidance on phone numbers.
Real-time validation
Use a text input with button for inputs that require independent entry submissions, where adding the information doesn’t automatically trigger an action. Such cases include applying coupon codes during checkout or search fields. Having a button next to the field gives the user a clear action to trigger. A text input with a button requires a text-only or icon-right button to avoid confusion when the warning icon appears in the input field. Display the button and input field flush together, in the same horizontal space.
Using the apply button, a customer can check if their coupon code is valid before submitting their order.
Providing keys
Read only text inputs are used for auto-generated values, for when the user is not able to change the value for the input. Use a read only text input when providing a token, a product key, account ID, or any value within an application that the user might need to copy and paste it in a different digital environment. Note that unlike inactive inputs, read only inputs are submitted as part of forms even though their inputs cannot be changed (see behavior and states).
An example of a read only input providing product keys.
Kinds
Copy link to this section
Options
There are two optional additions to the default text input component: buttons and icons. Either of these types can be used to design text, email, password, and phone number inputs.
Example of a text input without button or icon.
Example of a text input with button.
In the default text input, the icon is placed within the field.
In the text input with a button, choose a icon-right variant button, avoiding design conflicts and feedback confusion if the error state is activated and the icon appears on the field.
Sizes
Copy link to this section
Text input component is available in two sizes: small or large. Consider the experience as a whole to define the best size for the text input and keep component sizes consistent throughout the pattern. Note that sizes differentiate in their input heights, not width. Width of the component should be determined by the information length users are expected to enter into the field.
Small text inputs can be used with smaller screen sizes or when a compact layout better accommodates the content. The height of the small text input is 32 pixels.
Large text inputs may be used with larger grid sizes, layouts that require more space for content, or for users who many need a larger input field. The height of the large text input is 48 pixels.
Layout
Copy link to this section
Text input should be left-aligned (or right-aligned for right-to-left languages) in the experience. This component contains a placeholder inside the field, a label above, and a helper text below it. The error message, when activated, appears in the same placement as the helper text.
Field input width
The width of the text input helps guide the user’s text entry. It’s generally a good practice to size the field to the entry parameters, determining if the information is short or long. For example, a ZIP code field will be shorter than a street address field. Note that the field input width should match the forms or experience width itself.
Appropriate field input width example.
Inappropriate field input width example.
Specifications
To group or stack text inputs, it is recommended to maintain a spacing of multiples of 4 pixels (read more about the baseline grid on the grid foundations page). To place them correctly, make sure padding is 12 pixels for small sizes and 20 pixels for large sizes inputs.
A group of small text inputs with 12 pixels of padding.
A group of large text inputs with 20 pixels of padding.
A stack of small text inputs with 12 pixels of padding.
A stack of large text inputs with 20 pixels of padding.
Interaction
Copy link to this section
Behavior and states
The component will visually reflect the status of the user interaction. Text input communicates six states: rest, hover, focus, inactive, error, and read only. The states are represented by different colors or opacity.
State
Behavior
Rest
The rest state is the starting or ending state, indicating the text input is empty or filled.
Hover
When a user hovers over a selection, a highlight appears, indicating the field is selectable.
Focus
A blue outline appears around the text area when a user tabs or uses keyboard controls to navigate selections.
Inactive
Inactive text inputs should be used rarely and are displayed with 40% opacity, indicating the field exists but is not available to the user. Inactive inputs cannot be marked as required.
Error
Errors appear when the input entry, or lack thereof, fails validation. A validation error appears in red text (Red 700) and displays an error icon within the field. Additionally, a red error message appears under the component, describing the error and how to fix it as clearly and succinctly as possible.
Read only
Read only text inputs should not be marked as required, as users cannot edit values with them. However, this state should be focusable, given that users can copy the value it if necessary.
Standards
Copy link to this section
Accessibility
Make sure all labels are clear, concise, and unique
All users should know from the label exactly what information is needed to successfully complete the field.
WCAG 2.1: 1.3.1 Info and Relationships
Avoid using placeholder text for conveying important information
Use helper text to relate this information instead, as instructions must be visible at all times. Placeholder text disappears as the user starts typing, requiring them to delete their entered text if they need to refer to that information again.
WCAG 2.1: 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions
Make sure all helper text and error messages provide meaningful assistance in helping users avoid or fix errors
Don’t provide unclear helper text, such as “Enter a valid email address.” Instead, make it clear how a valid email address should be formatted.
WCAG 2.1: 3.3.2 Labels or Instructions, 3.3.3 Error Suggestion
Warn users in advance about fields that have masking and autoformatting requirements
If a field requires a specific kind of formatting, such as whole numbers, or a limited number of characters, communicate that in advance using helper text.
Content
North American phone number format
For the US, Canada, and other North American Numbering Plan (NANP) countries, use hyphens in phone numbers. Do not use parentheses, periods, or spaces in place of hyphens. Do: 111-222-3333 Don’t: 111.222.3333
Non-NANP phone number format
Include the country and area codes for all non-NANP countries. Use spaces, rather than hyphens, to separate the groups of numbers. Country codes are preceded by a plus sign with no space following it. Note that the quantity of numbers in a phone number can vary depending on the country or region. Do: +19 777 555 5555 Don’t: +19 (777) 555-5555
Clear and concise labels
Every input field should have a label to identify and describe its purpose, providing guidance and assuring readability and accessibility. Label text should be left-aligned (or right-aligned for right-to-left languages) with the input. Write label text in sentence case and be clear, being as succinct as possible. Do: Email address Don’t: Email Address Don’t: Enter your email address
Helper text
Helper text is an instructional text that helps the user fill out the relevant field. It usually guides the user to enter data in the appropriate format, providing field explanation, localization assistance, and help prevent errors. Keep the content concise, with as few words as possible to guide users and help them prevent errors. Helper text appears below the text field. Example: Passwords must be at least 8 characters
Placeholder text
Using placeholder text on its own introduces accessibility problems as it’s not read by screen readers. It can be difficult for people to remember the information provided by the placeholder text because it disappears when the user begins entering text. It is recommended that if you plan to use placeholder text, pair it with helper text. When using placeholder text in conjunction with helper text, placeholder text should supplement the information in the helper text rather than replace it.
Contents
Contents
Live demo
Copy link to this section
This demo lets you interact with the component and view the code. To see other interactive examples of this component or for additional developer documentation, visit Storybook.
You are now entering a live demo of the component.
<div class="dds__input-text__container ">
<labelid="sample-input-label"for="sample-input">Customer Number</label><divclass="dds__input-text__wrapper"><inputtype="text"class="dds__input-text"placeholder="Enter Customer Number"maxlength="256"name="sample-input"id="sample-input"required=""aria-labelledby="sample-input-label sample-input-helper"><smallid="sample-input-helper"class="dds__input-text__helper">Customer numbers are 8-10 characters.</small><divid="sample-input-feedback"class="dds__invalid-feedback">
Please enter a valid customer number.
</div></div></div>