Text input

Text inputs allow users to enter any combination of letters, numbers, or symbols. Text input boxes can span single or multiple lines.

Helpful error message
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<form class="usa-form">
  <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" role="alert">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>
</form>

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 accessibly. If you customize the text inputs, ensure they continue to meet the 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.

Package information

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