UI components

Form controls

Form controls allow users to enter information into a page.

Accessibility

As you customize these templates, make sure they meet the accessibility guidelines in this introduction and as described for each control.

Supporting screen readers

Note: These code examples have been designed to support a range of screen readers. That said, they may not work with all versions.

Known issues

If you are a building a form with multiple controls, also consider the accessibility guidelines in the “Form Templates” section.

Text input

Text inputs allow people to enter any combination of letters, numbers, or symbols of their choosing (unless otherwise restricted). Text input boxes can span single or multiple lines.

Helpful error message

<label for="input-type-text">Text input label</label>
<input id="input-type-text" name="input-type-text" type="text">

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

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

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

<label for="input-type-textarea">Text area label</label>
<textarea id="input-type-textarea" name="input-type-textarea"></textarea>

Accessibility

If you customize the text inputs, ensure they continue to meet the the accessibility requirements that apply to all form controls.

  • Avoid placeholder text for accessibility reasons. Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio.
  • 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.

Usability

When to use
  • If you can’t reasonably predict a user’s answer to a prompt and there might be wide variability in users’ answers.
  • 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.
  • When users want to be able to paste in a response.
When to consider something else
  • When users are choosing from a specific set of options.
Guidance
  • 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.
  • Text inputs are among the easiest type of input for desktop users but are more difficult for mobile users.
  • Only show error validation messages or stylings after a user has interacted with a particular field.
  • 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.)

A dropdown allows users to select one option from a list.

<form class="usa-form">
  <label for="options">Dropdown label</label>
  <select name="options" id="options">
    <option value="value1">Option A</option>
    <option value="value2">Option B</option>
    <option value="value3">Option C</option>
  </select>

  <input type="submit" value="Submit">
</form>

Checkboxes

Checkboxes allow users to select one or more options from a visible list.

Historical figures 1
<fieldset class="usa-fieldset-inputs usa-sans">

  <legend class="usa-sr-only">Historical figures 1</legend>

  <ul class="usa-unstyled-list">
    <li>
      <input id="truth" type="checkbox" name="historical-figures-1" value="truth" checked>
      <label for="truth">Sojourner Truth</label>
    </li>
    <li>
      <input id="douglass" type="checkbox" name="historical-figures-1" value="douglass">
      <label for="douglass">Frederick Douglass</label>
    </li>
    <li>
      <input id="washington" type="checkbox" name="historical-figures-1" value="washington">
      <label for="washington">Booker T. Washington</label>
    </li>
    <li>
      <input id="carver" type="checkbox" name="historical-figures-1" disabled>
      <label for="carver">George Washington Carver</label>
    </li>
  </ul>

</fieldset>

Accessibility

If you customize the text inputs, ensure they continue to meet the the accessibility requirements that apply to all form controls.

  • Surround a related set of checkboxes with a <fieldset>. The <legend> provides context for the grouping. Do not use fieldset and legend for a single check.
  • The custom checkboxes here are accessible to screen readers because the default checkboxes are moved off-screen with position: absolute; left: -999em.
  • Each input should have a semantic id attribute, and its corresponding label should have the same value in it’s for attribute.
  • The title attribute can replace <label>.

Usability

When to use
  • When a user can select any number of choices from a set list.
  • When a user needs to choose “yes” or “no” on only one option (use a stand-alone checkbox). For example, to toggle a setting on or off.
  • When users need to see all the available options at a glance.
When to consider something different
  • If there are too many options to display on a mobile screen.
  • If a user can only select one option from a list (use radio buttons instead).
Guidelines
  • Users should be able to tap on or click on either the text label or the checkbox to select or deselect an option.
  • List options vertically if possible; horizontal listings can make it difficult to tell which label pertains to which checkbox.
  • Avoid using negative language in labels as they can be counterintuitive. For example, “I want to receive a promotional email” instead of “I don’t want to receive promotional email.”
  • If you customize, make sure selections are adequately spaced for touch screens.

Radio buttons

Radio buttons allow users to see all available choices at once and select exactly one option.

Historical figures 2
<fieldset class="usa-fieldset-inputs usa-sans">

  <legend class="usa-sr-only">Historical figures 2</legend>

  <ul class="usa-unstyled-list">
    <li>
      <input id="stanton" type="radio" checked name="historical-figures-2" value="stanton">
      <label for="stanton">Elizabeth Cady Stanton</label>
    </li>
    <li>
      <input id="anthony" type="radio" name="historical-figures-2" value="anthony">
      <label for="anthony">Susan B. Anthony</label>
    </li>
    <li>
      <input id="tubman" type="radio" name="historical-figures-2" value="tubman">
      <label for="tubman">Harriet Tubman</label>
    </li>
  </ul>

</fieldset>

Accessibility

If you customize the radio buttons, ensure they continue to meet the the accessibility requirements that apply to all form controls.

  • Group related radio buttons together with <fieldset> and describe the group with <legend>.
  • Each radio button should have a <label>. Associate the two by matching the <label>’s for attribute to the <input>’s id attribute.
  • The title attribute can replace <label>.

Usability

When to use
  • When users need to select only one option out of a set of mutually exclusive choices.
  • When the number of available options can fit onto a mobile screen.
When to consider something else
  • Consider checkboxes if users need to select more than one option or if there is only one item to select.
  • Consider a dropdown if you don’t have enough space to list out all available options.
  • If users should be able to select zero of the options.
Guidance
  • Users should be able to tap on or click on either the text “label” or the radio button to select or deselect an option.
  • Options that are listed vertically are easier to read than those that are listed horizontally. Horizontal listings can make it difficult to tell which label pertains to which radio button.
  • If you customize, make sure selections are adequately spaced for touch screens.
  • Use caution if you decide to set a default value. Setting a default value can discourage users from making conscious decisions, seem pushy, or alienate users who don’t fit into your assumptions. If you are unsure, leave nothing selected by default.

Date input

Three text fields are the easiest way for users to enter most dates.

Date of birth For example: 04 28 1986
<fieldset>
  <legend>Date of birth</legend>
  <span class="usa-form-hint" id="dobHint">For example: 04 28 1986</span>

  <div class="usa-date-of-birth">
    <div class="usa-form-group usa-form-group-month">
      <label for="date_of_birth_1">Month</label>
      <input class="usa-input-inline" aria-describedby="dobHint" id="date_of_birth_1" name="date_of_birth_1" pattern="0?[1-9]|1[012]" type="number" min="1" max="12" value="">
    </div>
    <div class="usa-form-group usa-form-group-day">
      <label for="date_of_birth_2">Day</label>
      <input class="usa-input-inline" aria-describedby="dobHint" id="date_of_birth_2" name="date_of_birth_2" pattern="0?[1-9]|1[0-9]|2[0-9]|3[01]" type="number" min="1" max="31" value="">
    </div>
    <div class="usa-form-group usa-form-group-year">
      <label for="date_of_birth_3">Year</label>
      <input class="usa-input-inline" aria-describedby="dobHint" id="date_of_birth_3" name="date_of_birth_3" pattern="[0-9]{4}" type="number" min="1900" max="2000" value="">
    </div>
  </div>
</fieldset>

Implementation

Currently, the max limit for the year input is set to 2000, but it should be changed depending on the context of the form.

Accessibility

  • These text fields should follow the accessibility guidelines for all text inputs.
  • Do not use JavaScript to auto advance the focus from one field to the next. This makes it difficult for keyboard-only users to navigate and correct mistakes.

Usability

When to use
  • Use this format for most dates, particularly memorized dates.
When to consider something else
  • If users are trying to schedule something, a calendar picker might make more sense. Be sure to also provide an option for text entry as well.
Guidelines
  • Be sure each field is properly labeled — some countries enter dates in day, month, year order.
  • It may be tempting to switch all or some of these text fields to drop downs, but these tend to be more difficult to use than text boxes.

Validation

Stating validation requirements up front, with live feedback, means users won’t be left guessing.

Enter a code

Codes must:

  • Have at least 1 uppercase character
  • Have at least 1 numerical character
<form class="usa-form">
  <fieldset>
    <legend class="usa-drop_text">Enter a code</legend>

    <div class="usa-alert usa-alert-info">
      <div class="usa-alert-body">
        <h3 class="usa-alert-heading">Codes must:</h3>
      </div>
      <ul class="usa-checklist" id="validate-code">
        <li data-validator="uppercase">Have at least 1 uppercase character</li>
        <li data-validator="numerical">Have at least 1 numerical character</li>
      </ul>
    </div>

    <label for="code">Code</label>
    <input id="code" name="code" type="text"
      aria-describedby="validate-code"
      data-validate-uppercase="[A-Z]"
      data-validate-numerical="\d"
      data-validation-element="#validate-code">

    <input type="submit" value="Submit code">
  </fieldset>
</form>

Guidance

  • Input fields which have custom validation logic can automatically provide helpful feedback to users if they are assigned a data-validation-element attribute set to a CSS selector that uniquely identifies a .usa-checklist, e.g. data-validation-element="#validate-code".
  • For each kind of validation you’d like to provide feedback on:
    1. Come up with a name for the validator, e.g. uppercase. It shouldn’t have any spaces in it.
    2. On one of the list elements in the .usa-checklist, set the data-validator attribute to the name of the validator, e.g. data-validator="uppercase". This is the list item that will appear “checked” when the validator’s condition is met.
    3. On the input field, add a field called data-validate-validator name and set its value to a regular expression that represents whether the validator’s condition is met, e.g. data-validate-uppercase="[A-Z]".