Text box

Purpose

Users need to input a simple text value.

Description

Text boxes allow the user to input a simple text value. A text box only allows for a single line of input.

Example

Normal

Disabled

Example HTML usage:

<!--Text box-->
<div class="form-group">
  <label for="exampleFormControlInput1">Normal</label>
  <input
    type="text"
    class="form-control"
    id="exampleFormControlInput1"
    name="exampleFormControlInput1"
  />
</div>
<div class="form-group">
  <label for="exampleFormControlInput2">Disabled</label>
  <input
    type="text"
    class="form-control"
    id="exampleFormControlInput2"
    name="exampleFormControlInput2"
    disabled
  />
</div>

Text area

Purpose

Users need to input an extended, potentially multi-line text value.

Description

Text areas allow the user to input extended, multi-line text values.

Sizing and resizing

Text areas can either

have a fixed, static height
automatically grow/shrink based on the input, from a minimum number of lines (e.g., 3) to a maxmimum number of lines (e.g., 10) to ensure that space is optimally used
have a resize handle, allowing for manual vertical and/or horizontal resizing

Example

Normal

Disabled

Example HTML usage:

<!--Text area-->
<div class="form-group">
  <label for="ta1" class="col-sm-3 control-label">Normal</label>
  <div class="col-sm-9">
    <textarea class="form-control" id="ta1" rows="2"></textarea>
  </div>
</div>
<div class="form-group">
  <label for="ta2" class="col-sm-3 control-label">Disabled</label>
  <div class="col-sm-9">
    <textarea class="form-control" id="ta2" rows="2" disabled=""></textarea>
  </div>
</div>

Radio buttons

Purpose

Users must choose between two or more mutually exclusive options.

Description

Radio buttons come in a group of two or more mutually exclusive options
A radio button is either checked or unchecked
There can only be one radio button checked in a group
Radio button labels should use sentence casing
Use concise labels
Provide an initially checked option when the field is not required and/or there is a sane default
Align vertically when possible
Align in shorter columns if there are many options
Ensure there is adequate spacing between adjacent fields and radio/checkbox groups

Radio button

Custom radio checked

Custom radio unchecked

Custom radio disabled

Example HTML usage:

<!--Custom radio button-->
<div class="form-group">
  <div class="custom-control custom-radio">
    <input
      type="radio"
      id="customRadio1"
      name="customRadio"
      class="custom-control-input"
      checked=""
    />
    <label class="custom-control-label" for="customRadio1"
      >Custom radio checked</label
    >
  </div>
  <div class="custom-control custom-radio">
    <input
      type="radio"
      id="customRadio2"
      name="customRadio"
      class="custom-control-input"
    />
    <label class="custom-control-label" for="customRadio2"
      >Custom radio unchecked</label
    >
  </div>
  <div class="custom-control custom-radio">
    <input
      type="radio"
      id="customRadio3"
      name="customRadio"
      class="custom-control-input"
      disabled=""
    />
    <label class="custom-control-label" for="customRadio3"
      >Custom radio disabled</label
    >
  </div>
</div>

Tile radio button

Custom radio checked

Custom radio unchecked

Custom radio disabled

Example HTML usage:

<!--Custom radio button-->
<div class="form-group">
  <div class="custom-control custom-radio tile">
    <input
      type="radio"
      id="customRadio5"
      name="customRadio4"
      class="custom-control-input"
      checked
    />
    <label class="custom-control-label" for="customRadio5"
      >Custom radio checked</label
    >
  </div>
  <div class="custom-control custom-radio tile">
    <input
      type="radio"
      id="customRadio6"
      name="customRadio4"
      class="custom-control-input"
    />
    <label class="custom-control-label" for="customRadio6"
      >Custom radio unchecked</label
    >
  </div>
  <div class="custom-control custom-radio tile">
    <input
      type="radio"
      id="customRadio7"
      name="customRadio4"
      class="custom-control-input"
      disabled
    />
    <label class="custom-control-label" for="customRadio7"
      >Custom radio disabled</label
    >
  </div>
</div>

Browser radio button

Default radio checked

Default radio unchecked

Disabled radio

Example HTML usage:

<!--Default radio button-->
<div class="form-group">
  <div class="form-check">
    <input
      class="form-check-input"
      type="radio"
      name="exampleRadios"
      id="exampleRadios1"
      value="option1"
      checked=""
    />
    <label class="form-check-label" for="exampleRadios1">
      Default radio checked
    </label>
  </div>
  <div class="form-check">
    <input
      class="form-check-input"
      type="radio"
      name="exampleRadios"
      id="exampleRadios2"
      value="option1"
    />
    <label class="form-check-label" for="exampleRadios1">
      Default radio unchecked
    </label>
  </div>

  <div class="form-check">
    <input
      class="form-check-input"
      type="radio"
      name="exampleRadios"
      id="exampleRadios3"
      value="option3"
      disabled=""
    />
    <label class="form-check-label" for="exampleRadios3">
      Disabled radio
    </label>
  </div>
</div>

Checkboxes

Purpose

Users need to specify which option(s) from a set are applicable/valid/true based on a label.

Description

A set of checkboxes are used when a user is able to select none, one, or multiple options
A single checkbox is used when a user is able to select or not select an option
When clicked, a checkbox’s state toggles between unchecked and checked
Checkboxes can have an indeterminate state that is set based on external interactions (e.g., indicating that some but not all items in a collection are selected)
Checkbox labels should use sentence casing
Use concise labels
Align vertically when possible
Align in shorter columns if there are many options
The selected state of a checkbox should ideally indicate something ‘positive’ and may require the rephrasing of the label (e.g., Send me weekly reminders, vs. Do not send me weekly reminders)
Ensure there is adequate spacing between adjacent fields and radio/checkbox groups

Checkboxes

Custom checkbox checked

Custom checkbox unchecked

Custom checkbox disabled

Custom checkbox checked disabled

Example HTML usage:

<!--Custom checkboxes-->
<div class="form-group">
  <div class="custom-control custom-checkbox">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customCheck1"
      checked=""
    />
    <label class="custom-control-label" for="customCheck1"
      >Custom checkbox checked</label
    >
  </div>

  <div class="custom-control custom-checkbox">
    <input type="checkbox" class="custom-control-input" id="customCheck2" />
    <label class="custom-control-label" for="customCheck2"
      >Custom checkbox unchecked</label
    >
  </div>

  <div class="custom-control custom-checkbox">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customCheck3"
      disabled=""
    />
    <label class="custom-control-label" for="customCheck2"
      >Custom checkbox disabled</label
    >
  </div>
  <div class="custom-control custom-checkbox">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customCheck3"
      disabled=""
      checked=""
    />
    <label class="custom-control-label" for="customCheck2"
      >Custom checkbox checked disabled</label
    >
  </div>
</div>

Tile checkboxes

Custom checkbox checked

Custom checkbox unchecked

Custom checkbox disabled

Custom checkbox checked disabled

Example HTML usage:

<!--Custom radio button-->
<div class="form-group">
  <div class="custom-control custom-checkbox tile">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customCheck7"
      checked
    />
    <label class="custom-control-label" for="customCheck7"
      >Custom checkbox checked</label
    >
  </div>

  <div class="custom-control custom-checkbox tile">
    <input type="checkbox" class="custom-control-input" id="customCheck8" />
    <label class="custom-control-label" for="customCheck8"
      >Custom checkbox unchecked</label
    >
  </div>
  <div class="custom-control custom-checkbox tile">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customCheck9"
      disabled=""
    />
    <label class="custom-control-label" for="customCheck9"
      >Custom checkbox disabled</label
    >
  </div>
  <div class="custom-control custom-checkbox tile">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customCheck9"
      disabled=""
      checked=""
    />
    <label class="custom-control-label" for="customCheck9"
      >Custom checkbox checked disabled</label
    >
  </div>
</div>

Browser checkboxes

Default checkbox checked

Default checkbox unchecked

Disabled checkbox

Example HTML usage:

<!--Default checkboxes-->
<div class="form-group">
  <div class="form-check">
    <input
      class="form-check-input"
      type="checkbox"
      value=""
      id="defaultCheck1"
      checked=""
    />
    <label class="form-check-label" for="defaultCheck1">
      Default checkbox checked
    </label>
  </div>
  <div class="form-check">
    <input
      class="form-check-input"
      type="checkbox"
      value=""
      id="defaultCheck2"
    />
    <label class="form-check-label" for="defaultCheck2">
      Default checkbox unchecked
    </label>
  </div>
  <div class="form-check">
    <input
      class="form-check-input"
      type="checkbox"
      value=""
      id="defaultCheck3"
      disabled=""
    />
    <label class="form-check-label" for="defaultCheck3">
      Disabled checkbox
    </label>
  </div>
  <div class="form-check">
    <input
      class="form-check-input"
      type="checkbox"
      value=""
      id="defaultCheck4"
      disabled=""
      checked=""
    />
    <label class="form-check-label" for="defaultCheck4">
      Disabled checkbox
    </label>
  </div>
</div>

Toggle switches

Purpose

Users need to toggle an option between on/off or yes/no.

Description

Use a toggle switch for a binary option where the change occurs immediately. Use a checkbox instead if the user has to perform other actions for the change to be effective (e.g., pressing Save or Submit).

Toggle switches

Toggle this switch element

Disabled switch element

Example HTML usage:

<!--Toggle switches-->
<div class="form-group">
  <div class="custom-control custom-switch">
    <input
      type="checkbox"
      class="custom-control-input"
      id="customSwitch1"
      checked
    />
    <label class="custom-control-label" for="customSwitch1"
      >Toggle this switch element</label
    >
  </div>
  <div class="custom-control custom-switch">
    <input type="checkbox" class="custom-control-input" id="customSwitch2" />
    <label class="custom-control-label" for="customSwitch2"
      >Toggle this switch element</label
    >
  </div>
  <div class="custom-control custom-switch">
    <input
      type="checkbox"
      class="custom-control-input"
      disabled
      id="customSwitch3"
    />
    <label class="custom-control-label" for="customSwitch3"
      >Disabled switch element</label
    >
  </div>
</div>

Select

Purpose

The user needs to choose an option from a predefined set.

Description

A select, sometimes referred to as a combo box, provides functionality for choosing an option from a set
It is similar to dropdown button but facilitates item selection, filtering, and reflects the currently selected value
When clicked, the user is shown all available options and can make a selection
When a selection is made, the dropdown closes and the select control updates to reflect the current selection
If there are 5 or more options, the list should allow for filtering via a text field
For empty selects, use a placeholder in the format of Select a [type]... or Select...

Select

Small select

Large select

Example HTML usage:

<!--Custom select-->
<div class="form-group">
  <label for="exampleFormControlSelect3" class="mt-2">Select</label>
  <select class="custom-select" id="exampleFormControlSelect3">
    <option selected="">Select menu</option>
    <option value="1">One</option>
    <option value="2">Two</option>
    <option value="3">Three</option>
    <option value="4">Four</option>
    <option value="5">Five</option>
  </select>
</div>
<div class="form-group">
  <label for="exampleFormControlSelect4" class="mt-2">Small select</label>
  <select class="custom-select custom-select-sm" id="exampleFormControlSelect4">
    <option selected="">Select small menu</option>
    <option value="1">One</option>
    <option value="2">Two</option>
    <option value="3">Three</option>
    <option value="4">Four</option>
    <option value="5">Five</option>
  </select>
</div>
<div class="form-group">
  <label for="exampleFormControlSelect5" class="mt-2">Large select</label>
  <select class="custom-select custom-select-lg" id="exampleFormControlSelect5">
    <option selected="">Select large menu</option>
    <option value="1">One</option>
    <option value="2">Two</option>
    <option value="3">Three</option>
    <option value="4">Four</option>
    <option value="5">Five</option>
  </select>
</div>

Browser select

Normal

Disabled

Example HTML usage:

<!--Select-->
<div class="form-group">
  <label for="exampleFormControlSelect1" class="mt-2">Normal</label>
  <select class="form-control" id="exampleFormControlSelect1">
    <option value="value1">Option A</option>
    <option value="value2">Option B</option>
    <option value="value3">Option C</option>
    <option value="value4">Option D</option>
    <option value="value5">Option E</option>
  </select>
</div>
<div class="form-group">
  <label for="exampleFormControlSelect2" class="mt-2">Disabled</label>
  <select class="form-control" id="exampleFormControlSelect2" disabled>
    <option value="value1">Option A</option>
    <option value="value2">Option B</option>
    <option value="value3">Option C</option>
    <option value="value4">Option D</option>
    <option value="value5">Option E</option>
  </select>
</div>

Multi-select

This is the native browser multi-select. ctrl+click (or cmd+click) toggles selection on an item. shift+click performs a range selection. A single click sets the selection to only that item.

Select

Example HTML usage:

<!--Multiple select-->
<div class="form-group">
  <label for="exampleFormControlSelect6" class="mt-2">Select</label>
  <select class="custom-select" multiple id="exampleFormControlSelect6">
    <option value="value1">Option A</option>
    <option value="value2">Option B</option>
    <option value="value3">Option C</option>
    <option value="value4">Option D</option>
  </select>
</div>
<div class="form-group">
  <label for="exampleFormControlSelect6" class="mt-2">Select</label>
  <select
    class="custom-select"
    multiple
    id="exampleFormControlSelect6"
    disabled
  >
    <option value="value1">Option A</option>
    <option value="value2">Option B</option>
    <option value="value3">Option C</option>
    <option value="value4">Option D</option>
  </select>
</div>

Date picker

Depending on the JS library used for the date picker, functionality may vary.

Date pickers can provide:

Navigating years and months via previous/next arrows and/or other dropdowns
Multi-calendar views
Range highlighting
Min and max allowable dates
Highlighting/disabling of days/rows/columns (e.g., disable weekends or highlight bi-week)
Ability to type date as well as use a calendar dropdown

Example HTML usage:

<!--Date picker-->
<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>

Date input

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

Date of birth For example: 4 28 1986

Month

Day

Year

Example HTML usage:

<!--Date input field-->
<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>

Time picker

In progress

A time picker helps users select a specific time.

Example HTML usage:

<form class="usa-form row">
  <div class="col-sm-3">
    <label class="usa-label" for="fruit">Appointment time</label>
    <span class="usa-hint" id="dobHint">hh:mm</span>
    <div class="usa-combo-box">
      <select class="usa-select" name="time" id="time" required>
        <option value="00:00">12:00am</option>
        <option value="00:30">12:30am</option>
        <option value="01:00">1:00am</option>
        <option value="01:30">1:30am</option>
        <option value="02:00">2:00am</option>
        <option value="02:30">2:30am</option>
        <option value="03:00">3:00am</option>
        <option value="03:30">3:30am</option>
        <option value="04:00">4:00am</option>
        <option value="04:30">4:30am</option>
        <option value="05:00">5:00am</option>
        <option value="05:30">5:30am</option>
        <option value="06:00">6:00am</option>
        <option value="06:30">6:30am</option>
        <option value="07:00">7:00am</option>
        <option value="07:30">7:30am</option>
        <option value="08:00">8:00am</option>
        <option value="08:30">8:30am</option>
        <option value="09:00">9:00am</option>
        <option value="09:30">9:30am</option>
        <option value="10:00">10:00am</option>
        <option value="10:30">10:30am</option>
        <option value="11:00">11:00am</option>
        <option value="11:30">11:30am</option>
        <option value="12:00">12:00pm</option>
        <option value="12:30">12:30pm</option>
        <option value="13:00">1:00pm</option>
        <option value="13:30">1:30pm</option>
        <option value="14:00">2:00pm</option>
        <option value="14:30">2:30pm</option>
        <option value="15:00">3:00pm</option>
        <option value="15:30">3:30pm</option>
        <option value="16:00">4:00pm</option>
        <option value="16:30">4:30pm</option>
        <option value="17:00">5:00pm</option>
        <option value="17:30">5:30pm</option>
        <option value="18:00">6:00pm</option>
        <option value="18:30">6:30pm</option>
        <option value="19:00">7:00pm</option>
        <option value="19:30">7:30pm</option>
        <option value="20:00">8:00pm</option>
        <option value="20:30">8:30pm</option>
        <option value="21:00">9:00pm</option>
        <option value="21:30">9:30pm</option>
        <option value="22:00">10:00pm</option>
        <option value="22:30">10:30pm</option>
        <option value="23:00">11:00pm</option>
        <option value="23:30">11:30pm</option>
      </select>
    </div>
  </div>
</form>

Input prefix or suffix

In progress

Use input prefixes and suffixes to show symbols or abbreviations that help users enter the right type of information in a form’s text input.

Example HTML usage:

<form>
  <div class="form-group">
    <label for="inputprefix">Credit card number</label>
    <div class="input-group prefix mb-3">
      <div class="input-group-prepend">
        <span class="input-group-text">
          <i class="material-icons">credit_card</i>
        </span>
      </div>
      <input
        type="text"
        id="inputprefix"
        class="form-control creditCardText"
        placeholder="xxxx-xxxx-xxxx-xxxx"
        aria-label="Credit card number"
        aria-describedby="inputprefix"
        required=""
        pattern="[0-9]{13,16}"
        maxlength="19"
      />
    </div>
  </div>

  <div class="form-group">
    <label for="inputsuffix">Weight, in pounds</label>
    <div class="input-group suffix mb-3">
      <input
        type="text"
        class="form-control"
        id="inputsuffix"
        aria-label="Weight in lbs"
        aria-describedby="lbs"
      />
      <div class="input-group-append">
        <span class="input-group-text">lbs</span>
      </div>
    </div>
  </div>
</form>

Range slider

In progress

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

Range slider

Example HTML usage:

<!-- Range slider -->
<div class="form-group">
  <label for="customRange1">Range slider</label>
  <input type="range" class="custom-range" id="customRange1" />
</div>

Rich text editor

In progress

The rich text editor allows for text input with additional formatting and inline images/links. Only include the functionality/buttons/tools necessary for the specific purpose.

Example HTML usage:

<!-- Rich text editor -->
<div class="border border-secondary">
  <div class="bg-light border-bottom border-secondary margin-0">
    <div class="btn-group border-right border-secondary" style="height: 46px">
      <button
        type="button"
        class="btn btn-default dropdown-toggle"
        data-toggle="dropdown"
        aria-expanded="false"
      >
        Arial
      </button>
      <div class="dropdown-menu" role="menu">
        <a class="dropdown-item" href="#">Arial</a>
        <a class="dropdown-item" href="#">Georgia</a>
        <a class="dropdown-item" href="#">Courier</a>
      </div>
    </div>

    <div class="btn-group border-right border-secondary">
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-icon-only"
        data-original-title="Bold"
      >
        <i class="material-icons">format_bold</i
        ><span class="sr-only">Bold</span>
      </button>
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover active btn-icon-only"
        data-original-title="Italicize"
      >
        <i class="material-icons">format_italic</i
        ><span class="sr-only">Italicize</span>
      </button>
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Underline"
      >
        <i class="material-icons">format_underline</i
        ><span class="sr-only">Underline</span>
      </button>
    </div>

    <div class="btn-group border-right border-secondary">
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Ordered list"
      >
        <i class="material-icons">format_list_numbered</i
        ><span class="sr-only">Ordered list</span>
      </button>
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Unordered list"
      >
        <i class="material-icons">format_list_bulleted</i
        ><span class="sr-only">Unordered list</span>
      </button>
    </div>
    <div class="btn-group border-right border-secondary">
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Indent"
      >
        <i class="material-icons">format_indent_increase</i
        ><span class="sr-only">Indent</span>
      </button>
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Outdent"
      >
        <i class="material-icons">format_indent_decrease</i
        ><span class="sr-only">Outdent</span>
      </button>
    </div>
    <div class="btn-group">
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Insert link"
      >
        <i class="material-icons">link</i
        ><span class="sr-only">Insert link</span>
      </button>
      <button
        type="button"
        data-toggle="tooltip"
        data-placement="top"
        title=""
        class="btn btn-hover btn-icon-only"
        data-original-title="Insert image"
      >
        <i class="material-icons">insert_photo</i
        ><span class="sr-only">Insert image</span>
      </button>
    </div>
  </div>

  <textarea
    name=""
    id=""
    cols="30"
    rows="10"
    class="form-control border-0"
    placeholder="Enter note here..."
  ></textarea>
</div>