Components
Text input
A text input allows users to enter any combination of letters, numbers, or symbols. Text input boxes can span single or multiple lines.
<label class="usa-label" for="input-type-text">Text input label</label
><input class="usa-input" id="input-type-text" name="input-type-text" />
<label class="usa-label" for="input-type-textarea">Text area label</label
><textarea
class="usa-textarea"
id="input-type-textarea"
name="input-type-textarea"
></textarea>Guidance
When to use the text input component
- Unpredictable or freeform responses. If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
- Input simplicity. When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a date picker.
- Pasted content. When users want to be able to paste in a response.
When to consider something else
- Predetermined input options. When users are choosing from a specific set of options.
Usability guidance
- Use fields appropriate to the length of the input. The length of the text input provides a hint to users as to how much text to write. Do not require users to write paragraphs of text into a single-line input box; use a text area instead.
- Consider the mobile context. Text inputs are among the easiest type of input for desktop users but are more difficult for mobile users.
- Wait to validate. Only show error validation messages or stylings after a user has interacted with a particular field.
- Avoid placeholder text. Avoid using placeholder text that appears within a text field before a user starts typing. If placeholder text is no longer visible after a user clicks into the field, users will no longer have that text available when they need to review their entries. (People who have cognitive or visual disabilities have additional problems with placeholder text.) .
Accessibility
- Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
- Avoid placeholder text. Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio.
- Avoid splitting numbers. Avoid breaking numbers with distinct sections (such as phone numbers, Social Security Numbers, or credit card numbers) into separate input fields. For example, use one input for phone number, not three (one for area code, one for local code, and one for number). Each field needs to be labeled for a screen reader and the labels for fields broken into segments are often not meaningful.
Using the text input component
Text input settings
This component has no settings.
Text input variants
| Variant | Description |
|---|---|
|
|
The error state of the text input. |
|
|
The success state of the text input. |
|
|
Displays an input at a specific width. Accepts |
Package
-
Package usage:
@forward "usa-input"; - Dependencies:
uswds-fonts
Latest updates
Meaningful code and guidance updates are listed in the following table:
| Date | USWDS version | Affects | Description |
|---|---|---|---|
| 2023-11-16 | N/A |
|
Updated the listed values for |
| 2023-06-09 | 3.5.0 |
|
Improved consistency and visibility of disabled styles.
Form elements with the |
| 2023-06-09 | 3.5.0 |
|
Improved consistency of disabled styles in forced colors mode. More information: uswds#5295 |
| 2022-06-17 | 3.0.2 |
|
Improved form group error display. Form group margins are the same whether or not the form group is in an error state. More information: uswds#4751 |
| 2022-04-28 | N/A |
|
Updated package name to |
| 2022-04-28 | 3.0.0 |
|
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656 |
| 2022-04-13 | N/A |
|
Updated package name to |
| 2021-03-17 | N/A |
|
Updated and improved guidance for text input. More information: uswds-site#1180 |
