Components

Form controls

Form controls allow users to enter information into a page.

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

General accessibility guidance for forms

  • Customize accessibly. As you customize these templates, make sure they meet the accessibility guidelines in this introduction and as described for each control.
  • Don’t control element order with CSS. Display form controls in the same order in HTML as they appear on screen. Don’t use CSS to rearrange the form controls. Screen readers narrate forms in the order they appear in the HTML.
  • Align validation with inputs. Visually align validation messages with the input fields, so people using screen magnifiers can read them quickly.
  • Use proper markup. Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend elements make it easier for screen reader users to navigate the form.
  • Use legends. Use a single legend for fieldset (this is required). One example of a common use of fieldset and legend is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the legend tag.
  • Embed multiple fieldsets and legends for more complex forms.
  • Use simple vertical layouts. Keep your form blocks in a vertical pattern. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
Note: These components have been designed to support a wide range of screen readers, but they may not work with all versions.

Known issues with screen readers

  • VoiceOver on iOS currently does not support fieldset and legend for forms. You can address this by using aria-labelledby="for-attribute-of-label id-of-legend id-of-additional-info" on each input in the fieldset. Using aria-labelledby will overwrite the default text read by the screen reader, so it is important to include all relevant information.
  • VoiceOver on OS X currently does not support aria-describedby. Use aria-labelledby instead, and include all related fields, including, labels, legend, and hint text

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.

Dropdowns allow users to select one option from a temporary modal menu.

1
2
3
4
5
6
7
8
9
<form class="usa-form">
  <label class="usa-label" for="options">Dropdown label</label>
  <select class="usa-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>

Checkbox

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

Historical figures 1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-sr-only">Historical figures 1</legend>
    <div class="usa-checkbox">
      <input class="usa-checkbox__input" id="truth" type="checkbox" name="historical-figures-1" value="truth" checked>
      <label class="usa-checkbox__label" for="truth">Sojourner Truth</label>
    </div>
    <div class="usa-checkbox">
      <input class="usa-checkbox__input" id="douglass" type="checkbox" name="historical-figures-1" value="douglass">
      <label class="usa-checkbox__label" for="douglass">Frederick Douglass</label>
    </div>
    <div class="usa-checkbox">
      <input class="usa-checkbox__input" id="washington" type="checkbox" name="historical-figures-1" value="washington">
      <label class="usa-checkbox__label" for="washington">Booker T. Washington</label>
    </div>
    <div class="usa-checkbox">
      <input class="usa-checkbox__input" id="carver" type="checkbox" name="historical-figures-1" disabled>
      <label class="usa-checkbox__label" for="carver">George Washington Carver</label>
    </div>
  </fieldset>
</form>

When to use the checkbox component

  • Multi-select. When a user can select any number of choices from a set list.
  • Toggles. 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.
  • Visibility of options. When users need to see all the available options at a glance.

When to consider something different

  • Too many options. If there are too many options to display on a mobile screen.
  • Single-select only. If a user can only select one option from a list (use radio buttons instead).

Usability guidelines

  • Make the label selectable. 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. Horizontal listings can make it difficult to tell which label pertains to which checkbox.
  • Use positive statements. Negative language in labels can be counterintuitive. For example, use “I want to receive a promotional email” instead of “I don’t want to receive promotional email.”
  • Use adequate touch targets. If you customize, make sure selections are adequately spaced for touch screens.

Accessibility

  • Customize accessibly. If you customize the text inputs, ensure they continue to meet the the accessibility requirements that apply to all form controls.
  • Use a fieldset and legend for a checkbox group. 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.
  • These custom checkboxes are accessible. The custom checkboxes here are accessible to screen readers because the default checkboxes are moved off-screen with position: absolute; left: -999em.
  • Use semantic ids. 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>.

Radio buttons

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

Historical figures 2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-sr-only">Historical figures 2</legend>
    <div class="usa-radio">
      <input class="usa-radio__input" id="stanton" type="radio" checked name="historical-figures-2" value="stanton">
      <label class="usa-radio__label" for="stanton">Elizabeth Cady Stanton</label>
    </div>
    <div class="usa-radio">
      <input class="usa-radio__input" id="anthony" type="radio" name="historical-figures-2" value="anthony">
      <label class="usa-radio__label" for="anthony">Susan B. Anthony</label>
    </div>
    <div class="usa-radio">
      <input class="usa-radio__input" id="tubman" type="radio" name="historical-figures-2" value="tubman">
      <label class="usa-radio__label" for="tubman">Harriet Tubman</label>
    </div>
  </fieldset>
</form>

When to use the radio button component

  • Single selection. When users need to select only one option out of a set of mutually exclusive choices.
  • Limited choices. When the number of available options can fit onto a mobile screen.

When to consider something else

  • Multiple seleections. Consider checkboxes if users need to select more than one option or if there is only one item to select.
  • Limited space. Consider a dropdown if you don’t have enough space to list out all available options.
  • Selecting none. If users should be able to select zero of the options.

Usability guidance

  • Use the label as a target. Users should be able to tap on or click on either the text “label” or the radio button to select or deselect an option.
  • List items vertically. 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.
  • Use adequate spacing. If you customize, make sure selections are adequately spaced for touch screens.
  • Set default values with caution. 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.

Accessibility

  • Customize accessibly. If you customize the radio buttons, ensure they continue to meet the the accessibility requirements that apply to all form controls.
  • Use fieldset and legend. Group related radio buttons together with <fieldset> and describe the group with <legend>.
  • Use proper labels and attributes. 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>.

Date input

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

Date of birth For example: 04 28 1986
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Date of birth</legend>
    <span class="usa-hint" id="dobHint">For example: 04 28 1986</span>
    <div class="usa-memorable-date">
      <div class="usa-form-group usa-form-group--month">
        <label class="usa-label" for="date_of_birth_1">Month</label>
        <input class="usa-input 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 class="usa-label" for="date_of_birth_2">Day</label>
        <input class="usa-input 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 class="usa-label" for="date_of_birth_3">Year</label>
        <input class="usa-input usa-input--inline" aria-describedby="dobHint" id="date_of_birth_3" name="date_of_birth_3" type="number" min="1900" max="2019" value="">
      </div>
    </div>
  </fieldset>
</form>

When to use the date input component

  • Appropriate for most dates. Use this format for most dates, particularly memorized dates.

When to consider something else

  • Consider a calendar picker for scheduling. 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.

Usability guidelines

  • Label each field. Be sure each field is properly labeled — some countries enter dates in day, month, year order.
  • Avoid dropdowns. It may be tempting to switch all or some of these text fields to dropdowns, but these tend to be more difficult to use than text boxes.

Accessibility

  • Follow input guidance. These text fields should follow the accessibility guidelines for all text inputs.
  • Don’t auto-advance focus. 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.

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.

Validation

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

Enter a code

Code requirements

  • Use at least one uppercase character
  • Use at least one number
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend">Enter a code</legend>
    <div class="usa-alert usa-alert--info usa-alert--validation">
      <div class="usa-alert__body">
        <h3 class="usa-alert__heading">Code requirements</h3>
        <ul class="usa-checklist" id="validate-code">
          <li class="usa-checklist__item usa-checklist__item--checked" data-validator="uppercase">Use at least one uppercase character</li>
          <li class="usa-checklist__item" data-validator="numerical">Use at least one number</li>
        </ul>
      </div>
    </div>
    <label class="usa-label" for="code">Code</label>
    <input class="usa-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 class="usa-button" 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.
  • 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]".

Range slider

The range slider allows users to choose an approximate number from a range.

1
2
3
4
<form class="usa-form">
  <label class="usa-label" for="range-slider">Range slider</label>
  <input id="range-slider" class="usa-range" type="range" min="0" max="100" step="10" value="20">
</form>

When to use the range slider component

  • When the range is more important than precision. For instance, it could be more important for a target price selector to communicate where the target price falls within a certain range than the precise dollar amount selected.
  • When a relative value is more important than an exact value. For instance, a volume slider is typically more focussed on the relative loudness of the output rather than the specific decibel level.

When to consider something else

  • Use a regular text input if a user needs to enter a precise number.

Usability guidance

  • Highlight the control when selected. The slider control should change color to indicate it is active when a user selects it.
  • The control must be draggable. Users should be able to drag the slider control or select somewhere along the slider itself to change the value.
  • Label the limits of the range. When appropriate, label the ends of the slider with the limits of the range (for example: “0/100”, “small/large” or “less expensive/more expensive”).
  • Don’t be too granular. In a range slider, the relative value is more important than the specific value, so set the step attribute so it’s not too granular. By setting the step to a value of 10-20% of the total range you prevent unnecessary precision and cognitive strain in your users. For example, set step="10" in a total range of 100.

Accessibility

Implementation

  • Set the min and max attribute of the input element to correspond to the instructions or labels that accompany the slider.

References