Text Input

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.

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.

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

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.

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.

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.

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.

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.

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.