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 
<form>
  <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-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>
</form>

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>- Select -</option>
    <option value="value1">Option A</option>
    <option value="value2">Option B</option>
    <option value="value3">Option C</option>
  </select>
</form>

Accessibility

If you customize the dropdown, ensure it continues to meet the the accessibility requirements that apply to all form controls.

  • Make sure your dropdown has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the dropdown read “Select a state” by default).
  • Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.

Usability

When to use
  • Use sparingly — only when a user needs to choose from about seven to 15 possible options and you have limited space to display the options.
When to consider something else
  • If the list of options is very short. Use radio buttons instead.
  • If the list of options is very long. Let users type the same information into a text input that suggests possible options instead.
  • If you need to allow users to select more than one option at once. Users often don’t understand how to select multiple items from dropdowns. Use checkboxes instead.
  • For site navigation (use the navigation components instead).
Guidance
  • Test dropdowns thoroughly with members of your target audience. Several usability experts suggest they should be the “UI of last resort.” Many users find them confusing and difficult to use.
  • Avoid making options in one dropdown menu change based on the input to another. Users often don’t understand how selecting an item in one impacts another.
  • When most users will (or should) pick a particular option, make it the default: <option selected="selected">Default</option>
  • Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Offer a “submit” button at the end of the form instead. Users often change their choices multiple times. Auto-submission is also less accessible.

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

Implementation

The validation component is intended primarily for usability, not as a robust security solution, since all the validation logic occurs on the client-side. The validation should be "mirrored" on the server-side for security purposes.

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]".