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.

Passed WCAG 2.1 AA 

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

Test the text input component in your own project.

USWDS tested the text input component for accessibility. You should test your implementation, too.

Use text input accessibility tests
  • 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

.usa-input--error

The error state of the text input.

.usa-input--success

The success state of the text input.

.usa-input--[width]

Displays an input at a specific width. Accepts 2xs (5ex), xs (9ex), sm or small (13ex), md or medium (20ex), lg (30ex), xl (40ex), and 2xl (50ex).

Accessibility test status

The USWDS team did 9 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
9 7 0 2 0

Overview of recent accessibility test results:

  • Passed: 7
  • Passed with exceptions: 0
  • Conditional: 2
  • Failed: 0

Learn more on the text input accessibility tests page.

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 Breaking Description
2024-06-19 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2697

2024-03-11 3.8.0
  • JavaScript
  • Markup
 No

Added textarea support to the validation component. More information: uswds#5233

2023-11-16 N/A
  • Guidance
 No

Updated the listed values for .usa-input--[width]. More information: uswds-site#2291

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2022-06-17 3.0.2
  • Styles
 No

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
  • Guidance
 No

Updated package name to usa-input. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2022-04-13 N/A
  • Guidance
 No

Updated package name to form-controls. More information: uswds-site#1497

2021-03-17 N/A
  • Guidance
 No

Updated and improved guidance for text input. More information: uswds-site#1180