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.

Helpful error message
<label class="usa-label" for="input-type-text">Text input label</label>
<input
  class="usa-input"
  id="input-type-text"
  name="input-type-text"
  type="text"
/>

<label class="usa-label" for="input-focus">Text input focused</label>
<input
  class="usa-input usa-focus"
  id="input-focus"
  name="input-focus"
  type="text"
/>

<div class="usa-form-group usa-form-group--error">
  <label class="usa-label usa-label--error" for="input-error"
    >Text input error</label
  >
  <span class="usa-error-message" id="input-error-message"
    >Helpful error message</span
  >
  <input
    class="usa-input usa-input--error"
    id="input-error"
    name="input-error"
    type="text"
    aria-describedby="input-error-message"
  />
</div>

<label class="usa-label" for="input-success">Text input success</label>
<input
  class="usa-input usa-input--success"
  id="input-success"
  name="input-success"
  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 calendar 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

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 (4ex), xs (7ex), sm or small (10ex), md or medium (20ex), lg (30ex), xl (40ex), and 2xl (50ex).

Package

  • Package usage: @import usa-form-controls
  • Requires: required, global