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

Character count

Character count helps users know how much text they can enter when there is a limit on the number of characters.

This is an input with a character counter.
You can enter up to 25 characters
This is a textarea with a character counter.
You can enter up to 50 characters
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<form class="usa-form">
  <div class="usa-character-count">
    <div class="usa-form-group">
      <label class="usa-label" for="with-hint-input">
        Text input
      </label>
      <span id="with-hint-input-hint" class="usa-hint">
        This is an input with a character counter.
      </span>
      <input class="usa-input usa-character-count__field" id="with-hint-input" maxlength="25" name="with-hint-input" aria-describedby="with-hint-input-info with-hint-input-hint">
    </div>
    <span id="with-hint-input-info" class="usa-hint usa-character-count__message" aria-live="polite">
      You can enter up to 25 characters
    </span>
  </div>
</form>

<form class="usa-form">
  <div class="usa-character-count">
    <div class="usa-form-group">
      <label class="usa-label" for="with-hint-textarea">
        Textarea
      </label>
      <span id="with-hint-textarea-hint" class="usa-hint">
        This is a textarea with a character counter.
      </span>
      <textarea class="usa-textarea usa-character-count__field" id="with-hint-textarea" maxlength="50" name="with-hint-textarea" rows="5" aria-describedby="with-hint-textarea-info with-hint-textarea-hint"></textarea>
    </div>

    <span id="with-hint-textarea-info" class="usa-hint usa-character-count__message" aria-live="polite">
      You can enter up to 50 characters
    </span>
  </div>
</form>

When to use the character count component

  • Brevity is desired. When users are likely to provide more detail than is needed, and you want to force them to user fewer words. Note: this will likely increase the amount of time it takes users to submit the form because editing requires thinking. In the words of Mark Twain, “I didn't have time to write a short letter, so I wrote a long one instead.”
  • Legal requirement. When there is a legal reason where an entry must be under a certain number of characters.

When to consider something else

  • Backend limitations. If your users keep hitting the character limit imposed by the backend of your service then try to increase the limit rather than use a character count.
  • Already implied. If the character length is apparent or implied by the data type (i.e. phone number or zip code).
  • Exceeding the character limit is highly unlikely. If the vast majority of users (well over 99%) are very unlikely to run afoul of backend validation, such as an address field that has a database field limit of 250 characters.

Accessibility

  • Associate the character count message to the input. Use aria-describedby on the input to allow the message to be announced to those using screen readers.
  • Use the aria-live attribute on character count message. Use aria-live="polite" so that updates to character count message are also announced when using a screen reader.

Implementation

  • Add component classes. The structure should include a base element with the class usa-character-count. Inside of that base element there should be an input element (input or textarea) with the class usa-character-count__field and an message element (span or div) with the class usa-character-count__message
  • Add a maxlength attribute to the input element. This will be used as the limit referenced in the message and for validation.
  • Account for no-JavaScript environments. Add a default message in the message element that refers to the character limit. This will appear in instances when JavaScript does not load.

Package information

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

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

Package information

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

Combo box

A combo box helps users select an item from a large list of options.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<form class="usa-form">
  <label class="usa-label" for="fruit">Select a fruit</label>
  <div class="usa-combo-box">
    <select class="usa-select" name="fruit" id="fruit" required>
      <option value>Select a fruit</option>
      <option value="apple">Apple</option>
      <option value="apricot">Apricot</option>
      <option value="avocado">Avocado</option>
      <option value="banana">Banana</option>
      <option value="blackberry">Blackberry</option>
      <option value="blood orange">Blood orange</option>
      <option value="blueberry">Blueberry</option>
      <option value="boysenberry">Boysenberry</option>
      <option value="breadfruit">Breadfruit</option>
      <option value="buddhas hand citron">Buddha's hand citron</option>
      <option value="cantaloupe">Cantaloupe</option>
      <option value="clementine">Clementine</option>
      <option value="crab apple">Crab apple</option>
      <option value="currant">Currant</option>
      <option value="cherry">Cherry</option>
      <option value="custard apple">Custard apple</option>
      <option value="coconut">Coconut</option>
      <option value="cranberry">Cranberry</option>
      <option value="date">Date</option>
      <option value="dragonfruit">Dragonfruit</option>
      <option value="durian">Durian</option>
      <option value="elderberry">Elderberry</option>
      <option value="fig">Fig</option>
      <option value="gooseberry">Gooseberry</option>
      <option value="grape">Grape</option>
      <option value="grapefruit">Grapefruit</option>
      <option value="guava">Guava</option>
      <option value="honeydew melon">Honeydew melon</option>
      <option value="jackfruit">Jackfruit</option>
      <option value="kiwifruit">Kiwifruit</option>
      <option value="kumquat">Kumquat</option>
      <option value="lemon">Lemon</option>
      <option value="lime">Lime</option>
      <option value="lychee">Lychee</option>
      <option value="mandarine">Mandarine</option>
      <option value="mango">Mango</option>
      <option value="mangosteen">Mangosteen</option>
      <option value="marionberry">Marionberry</option>
      <option value="nectarine">Nectarine</option>
      <option value="orange">Orange</option>
      <option value="papaya">Papaya</option>
      <option value="passionfruit">Passionfruit</option>
      <option value="peach">Peach</option>
      <option value="pear">Pear</option>
      <option value="persimmon">Persimmon</option>
      <option value="plantain">Plantain</option>
      <option value="plum">Plum</option>
      <option value="pineapple">Pineapple</option>
      <option value="pluot">Pluot</option>
      <option value="pomegranate">Pomegranate</option>
      <option value="pomelo">Pomelo</option>
      <option value="quince">Quince</option>
      <option value="raspberry">Raspberry</option>
      <option value="rambutan">Rambutan</option>
      <option value="soursop">Soursop</option>
      <option value="starfruit">Starfruit</option>
      <option value="strawberry">Strawberry</option>
      <option value="tamarind">Tamarind</option>
      <option value="tangelo">Tangelo</option>
      <option value="tangerine">Tangerine</option>
      <option value="ugli fruit">Ugli fruit</option>
      <option value="watermelon">Watermelon</option>
      <option value="white currant">White currant</option>
      <option value="yuzu">Yuzu</option>
    </select>
  </div>
</form>

When to use the combo box component

  • More than 15 options. When there are more than 15 choices in a drop-down list it can be hard to navigate with scrolling only.
  • Limited space. Use a combo box for presenting options when screen real estate is limited.

When to consider something else

  • Limited choices. When the number of options is small you can continue to use a select or radio elements.

Usability guidance

  • Use option strings familiar to users. The combo box filters by matching strings. Include option text that includes familiar strings or spellings (i.e. if using the combobox with a state list, include the postal abbreviation in the option text: District of Columbia (DC)).
  • Make sure to test. 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 dependent options. 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.
  • Use a good default. When most users will (or should) pick a particular option, make it the default: <option selected="selected">Default</option>
  • Avoid auto-submission. 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.

Accessibility

  • Customize accessibly. If you customize the combo box, ensure it continues to meet the the accessibility requirements that apply to all form controls.
  • Always use a label. 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).
  • Avoid auto-submission. 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.

Implementation

  • Initialization properties. The following properties update the component during initialization. These properties must be set before the component is initialized in order to have an effect.
property element effect
required select The combo box component will be required in terms of native form validation.
disabled select The combo box component will be disabled / readonly. You can re-enable by executing the enable procedure on the component.
data-placeholder .usa-combo-box To update the placeholder text of the combo-box use the data-placeholder attribute. Is it recommended that a label or hint is used in lieu of a placeholder.
data-default-value .usa-combo-box The combo box will set this value as the default selection if it is found within the select options.
  • Additional component procedures. The following static procedures update the component after initialization. These are in addition to the primary methods referenced in the JS customization documentation.
procedure parameters effect
enable .usa-combo-box element The combo box component will be enabled.
disable .usa-combo-box element The combo box component will be disabled / readonly.

Package information

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

Date input

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

Date of birth For example: 4 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: 4 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="text" maxlength="2" pattern="[0-9]*" inputmode="numeric" 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="text" maxlength="2" pattern="[0-9]*" inputmode="numeric" 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="text" minlength="4" maxlength="4" pattern="[0-9]*" inputmode="numeric" 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

Implementation

  • The year input is set to accept only a four-digit number while the month and day inputs can accept up to a two-digit number.
  • Always use back-end validation on dates for correctness.

Package information

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

Date picker

A date picker helps users select a single date.

mm/dd/yyyy
1
2
3
4
5
6
7
8
9
<form class="usa-form">
  <div class="usa-form-group">
    <label class="usa-label" id="appointment-date-label" for="appointment-date">Appointment date</label>
    <div class="usa-hint" id="appointment-date-hint">mm/dd/yyyy</div>
    <div class="usa-date-picker">
      <input class="usa-input" id="appointment-date" name="appointment-date" type="text" aria-describedby="appointment-date-label appointment-date-hint">
    </div>
  </div>
</form>

When to use the date picker component

  • Scheduling. When users needs to schedule an event and benefit from the context of a calendar.
  • When the day of the week is important. When knowing the day of the week helps users choose a specific date.

When to consider something else

  • Familiar dates. When asking users for a date they know well, or can look up without using a calendar (like a birthday), use date input fields.
  • When the day of the week is irrelevant. If there's no benefit to knowing the day of the week for a particular date, consider date input fields.

Usability guidance

  • Describe the date format. Provide a hint of mm/dd/yyyy to help users enter the proper date format if they opt not to use the date picker.

Accessibility

  • Customize accessibly. If you customize the date picker, ensure it continues to meet the the accessibility requirements that apply to all form controls.
  • Avoid auto-submission. 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.

Implementation

  • Initialization properties. The following properties update the component during initialization. These properties must be set before the component is initialized in order to have an effect.
property element effect
required input The date picker component will be required in terms of native form validation.
disabled input The date picker component will be disabled/readonly. You can re-enable by executing the enable procedure on the component.
data-default-value .usa-date-picker The date picker input will set this value if it is a valid date. The date should be in the format YYYY-MM-DD.
  • Component properties. The following properties modify component functionality. These properties must be set before the component is initialized in order to have an effect.
property element effect
data-min-date .usa-date-picker The date picker will not allow a date selection before this date. The date should be in the format YYYY-MM-DD. Typing in an earlier date will cause native form validation error. A default min date or 0000-01-01 is used as a default.
data-max-date .usa-date-picker The date picker will not allow a date selection after this date. The date should be in the format YYYY-MM-DD. Typing in an later date will cause native form validation error. There is no default maximum date.
data-range-date .usa-date-picker The date picker will show a range selection from the range date. The date should be in the format YYYY-MM-DD.
  • Additional component procedures. The following static procedures update the component after initialization. These are in addition to the primary methods referenced in the JS customization documentation.
procedure parameters effect
enable .usa-date-picker element The date picker component will be enabled.
disable .usa-date-picker element The date picker component will be disabled/readonly.

Package information

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

Date range picker

A date range picker helps users select a range between two dates.

mm/dd/yyyy
mm/dd/yyyy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<form class="usa-form">
  <div class="usa-date-range-picker">
    <div class="usa-form-group">
      <label class="usa-label" id="event-date-start-label" for="event-date-start">Event start date</label>
      <div class="usa-hint" id="event-date-start-hint">mm/dd/yyyy</div>
      <div class="usa-date-picker">
        <input class="usa-input" id="event-date-start" name="event-date-start" type="text" aria-describedby="event-date-start-label event-date-start-hint">
      </div>
    </div>

    <div class="usa-form-group">
      <label class="usa-label" id="event-date-end-label" for="event-date-end">Event end date</label>
      <div class="usa-hint" id="event-date-end-hint">mm/dd/yyyy</div>
      <div class="usa-date-picker">
        <input class="usa-input" id="event-date-end" name="event-date-end" type="text" aria-describedby="event-date-end-label event-date-end-hint">
      </div>
    </div>
  </div>
</form>

When to use the date range picker component

  • Scheduling. When users needs to schedule an event and benefit from the context of a calendar.
  • When the day of the week is important. When knowing the day of the week helps users choose a specific date.

When to consider something else

  • When the day of the week is irrelevant. If there's no benefit to knowing the day of the week for a date or range, consider date input fields.

Usability guidance

  • Describe the date format. Provide a hint of mm/dd/yyyy to help users enter the proper date format if they opt not to use the date picker.

Accessibility

  • Customize accessibly. If you customize the date picker, ensure it continues to meet the the accessibility requirements that apply to all form controls.
  • Avoid auto-submission. 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.

Implementation

  • Initialization properties. The following properties update the component during initialization. These properties must be set before the component is initialized in order to have an effect.
property element effect
data-min-date .usa-date-picker The date picker will not allow a date selection before this date. The date should be in the format YYYY-MM-DD. Typing in an earlier date will cause native form validation error. A default min date or 0000-01-01 is used as a default.
data-max-date .usa-date-picker The date picker will not allow a date selection after this date. The date should be in the format YYYY-MM-DD. Typing in an later date will cause native form validation error. There is no default maximum date.

Package information

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

A dropdown 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>

File input

File input allows users to attach one or multiple files.

Must be a PDF Any file type
Helpful error message
1
2
3
4
5
6
7
8
9
10
11
12
13
<label class="usa-label" for="input-single">Single file</label>
<span class="usa-hint" id="input-single-hint">Must be a PDF</span>
<input id="input-single" class="usa-file-input" type="file" name="input-single" accept=".pdf" aria-describedby="input-single-hint" />

<label class="usa-label" for="input-multiple">Multiple files</label>
<span class="usa-hint" id="input-multiple-hit">Any file type</span>
<input id="input-multiple" class="usa-file-input"  type="file" name="input-multiple" aria-describedby="input-multiple-hit" multiple />

<div class="usa-form-group usa-form-group--error">
  <label class="usa-label usa-label--error" for="file-input-error">Error example</label>
  <span class="usa-error-message" id="file-input-error-message" role="alert">Helpful error message</span>
  <input id="file-input-error" class="usa-file-input" multiple type="file" name="file-input-error" aria-describedby="file-input-error-message"/>
</div>

When to use the file input

  • Documents are required. Ask users to provide files when it's necessary.

When to consider something else

  • Documents are optional. Avoid asking users to provide documents if you don't require them.
  • Asynchronous upload. The file input component doesn't support asynchronous uploading. Files are POSTed only when only on form submission.
  • Asking for large files. Be mindful that some users might have limited connectivity or data plans.

Usability guidance

  • Allow multiple file formats. Not everyone has access to the same software. Be flexible with file types to avoid unnecessary software requirements.
  • Prefer one file per input. Some users might not know how to select multiple files in a file browser. Additionally, iOS does not allow multiple-file selection using the Files app.
  • Highlight input restrictions. Use usa-hint to be clear about any file restrictions, such as document types or file size.

Accessibility

  • Use proper labels and attributes. Each file input should have a <label>. Associate the two by matching the <label>’s for attribute to the <input>’s id attribute.
  • Use as a progressive enhancement. The file input component should be a progressive enhancement of <input type="file" />. If the component doesn't initialize, it should still work and appear like a standard file input.

Implementation

  • Initialization properties. JavaScript will create most elements for file input. To get a file input to initialize, add the class name usa-file-input to <input type="file" />.
  • Interaction. When a user selects or drags documents to the file input, the file name and a thumbnail preview are listed.
  • Using the accept attribute. You can allow certain files by placing an accept attribute on the <input/>If a file type is not accepted, the file will not be attached and the file input will display a message. Learn more about the accept attribute.
  • Internet Explorer/Edge These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.

Package information

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

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 selections. 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>.

Package information

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

Range slider

A 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.

Package information

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

References

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

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

Package information

  • Package usage: @import validation
  • Requires: required, global