Skip to main content

Checkbox (HTML)

Checkboxes indicate whether an option, sometimes part of a group of related options, has been selected.

Looking for the web component? See Checkbox (web component)
Variations

Checkbox control

A checkbox control provides the minimum functional markup necessary to display a Bolt-styled checkbox.

Refer to the checkbox control code reference docs for more information.

<bolt-checkbox-control>
  <input
    id="INPUT_ID"
    type="checkbox"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
  </label>
</bolt-checkbox-control>
<bolt-checkbox-control>
  <input
    disabled
    id="INPUT_ID"
    type="checkbox"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
  </label>
</bolt-checkbox-control>
<bolt-checkbox-control class="bolt-invalid">
  <input
    id="INPUT_ID"
    type="checkbox"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
  </label>
</bolt-checkbox-control>

Checkbox field

A checkbox field provides the minimum markup required to display a single checkbox, label, and optional description.

Refer to the checkbox field code reference docs for more information.

<bolt-checkbox-control>
  <input
    id="INPUT_ID"
    type="checkbox"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
    <div class="bolt-field__label">
      Field label
    </div>
  </label>
</bolt-checkbox-control>
field with description 
<bolt-checkbox-control>
  <input
    id="INPUT_ID"
    type="checkbox"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
    <div class="bolt-field__label">
      Field label
    </div>
    <div class="bolt-field__description">
      This is a field description. It may include <strong>bold</strong>, <em>italic</em>, and other basic formatting, but avoid interactive elements like links and buttons.
    </div>
  </label>
</bolt-checkbox-control>
<bolt-checkbox-control>
  <input
    disabled
    id="INPUT_ID"
    type="checkbox"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
    <div class="bolt-field__label">
      Field label
    </div>
  </label>
</bolt-checkbox-control>
<bolt-checkbox-control class="bolt-invalid">
  <input
    id="INPUT_ID"
    type="checkbox"
    aria-describedby="ERRORS_ID"
  />
  <label for="INPUT_ID">
    <bolt-checkbox-facade></bolt-checkbox-facade>
    <div class="bolt-field__label">
      Field label
    </div>
  </label>
  <div
    class="bolt-field__errors"
    id="ERRORS_ID"
  >
    <bolt-field-error>
      This is a field error message.
    </bolt-field-error>
  </div>
</bolt-checkbox-control>

Checkbox group

A checkbox group provides the markup necessary to display a set of related checkbox fields as a cohesive unit.

Refer to the checkbox group code reference docs for more information.

<fieldset class="bolt-fieldset bolt--checkboxes">
  <legend>
    <span class="bolt-fieldset__name">
      Group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
  </legend>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_1"
        type="checkbox"
      />
      <label for="INPUT_ID_1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_2"
        type="checkbox"
      />
      <label for="INPUT_ID_2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_3"
        type="checkbox"
      />
      <label for="INPUT_ID_3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
<fieldset class="bolt-fieldset bolt--checkboxes">
  <legend>
    <span class="bolt-fieldset__name">
      Group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
    <div class="bolt-help">
      This is some instructional text.
    </div>
  </legend>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        id="demo-instructional-text-1"
        type="checkbox"
      />
      <label for="demo-instructional-text-1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="demo-instructional-text-2"
        type="checkbox"
      />
      <label for="demo-instructional-text-2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="demo-instructional-text-3"
        type="checkbox"
      />
      <label for="demo-instructional-text-3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
<fieldset class="bolt-fieldset bolt--checkboxes">
  <legend>
    <span class="bolt-fieldset__name">
      Group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
  </legend>
  <div class="bolt-fieldset__toggles">
    <button type="button">
      Select all
    </button>
    <span>|</span>
    <button type="button" disabled>
      Select none
    </button>
  </div>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_1"
        type="checkbox"
      />
      <label for="INPUT_ID_1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_2"
        type="checkbox"
      />
      <label for="INPUT_ID_2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_3"
        type="checkbox"
      />
      <label for="INPUT_ID_3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
<fieldset class="bolt-fieldset bolt--checkboxes">
  <legend>
    <span class="bolt-fieldset__name">
      Group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
    <bolt-contextual-help
      heading="Heading text"
      type="push"
    >
      <p>Contextual help body content.</p>
    </bolt-contextual-help>
  </legend>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_1"
        type="checkbox"
      />
      <label for="INPUT_ID_1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_2"
        type="checkbox"
      />
      <label for="INPUT_ID_2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_3"
        type="checkbox"
      />
      <label for="INPUT_ID_3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
<fieldset class="bolt-fieldset bolt--checkboxes">
  <legend>
    <span class="bolt-fieldset__name">
      Group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
  </legend>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        disabled
        id="INPUT_ID_1"
        type="checkbox"
      />
      <label for="INPUT_ID_1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1 (disabled)
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_2"
        type="checkbox"
      />
      <label for="INPUT_ID_2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_3"
        type="checkbox"
      />
      <label for="INPUT_ID_3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
<fieldset
  class="bolt-fieldset bolt--checkboxes"
  disabled
>
  <legend>
    <span class="bolt-fieldset__name">
      Disabled group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
  </legend>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_1"
        type="checkbox"
      />
      <label for="INPUT_ID_1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_2"
        type="checkbox"
      />
      <label for="INPUT_ID_2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_3"
        type="checkbox"
      />
      <label for="INPUT_ID_3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
<fieldset
  class="
    bolt-fieldset bolt--checkboxes
    bolt-invalid
  "
>
  <legend>
    <span class="bolt-fieldset__name">
      Group name
    </span>
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>
    <div class="bolt-fieldset__errors">
      <bolt-field-error>
        This group has invalid data.
      </bolt-field-error>
    </div>
  </legend>
  <div class="bolt-fieldset__body">
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_1"
        type="checkbox"
      />
      <label for="INPUT_ID_1">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 1
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_2"
        type="checkbox"
      />
      <label for="INPUT_ID_2">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 2
        </div>
      </label>
    </bolt-checkbox-control>
    <bolt-checkbox-control>
      <input
        id="INPUT_ID_3"
        type="checkbox"
      />
      <label for="INPUT_ID_3">
        <bolt-checkbox-facade></bolt-checkbox-facade>
        <div class="bolt-field__label">
          Option 3
        </div>
      </label>
    </bolt-checkbox-control>
  </div>
</fieldset>
 Code reference

The HTML implementation provides maximum control over the markup. However, it is up to the consumer to implement all advanced interaction logic.

If you want Bolt to handle the interaction logic, check out the web component implementation.

This implementation should be compatible with @angular/forms without the need for additional dependencies.

Checkbox facade

All APIs built for <bolt-checkbox-facade> should be considered "private" and are subject to change at any time, without warning.
Any use of the custom element outside of documented patterns shall be done so at consumer's own risk.

The <bolt-checkbox-facade> custom element is designed exclusively for use within the checkbox control pattern in order to encapsulate the complex SVG markup and CSS required to present a styled checkbox control.

Checkbox control

As documented below, the checkbox control pattern is not fully accessible without additional configuration.

Please refer to the checkbox control accessibility docs for more information about accessibility concerns.

Syntax

Unless specified, elements should be defined in the order presented below.

<!-- Root (REQUIRED) -->
<bolt-checkbox-control
  class="
    [bolt-invalid]
  "
>
  <!-- Input (REQUIRED) -->
  <input
    [checked]
    [disabled]
    id="INPUT_ID"
    type="checkbox"
    ...
  />

  <!-- Label (REQUIRED) -->
  <label for="INPUT_ID">
    <!-- Facade (REQUIRED) -->
    <bolt-checkbox-facade></bolt-checkbox-facade>
  </label>
</bolt-checkbox-control>

Anatomy

A checkbox control is comprised of the following items:

  • Root (REQUIRED)
    • MAY apply .bolt-invalid class to apply "invalid" appearance to a single control.
  • Input (REQUIRED)
    • MUST have [type="checkbox"] attribute configuration.
    • MUST have an [id] attribute.
    • Refer to MDN for best practices on using the HTML <input type="checkbox"> element.
  • Label (REQUIRED)
    • MUST have a [for] attribute with value matching the [id] of the Input.
  • Facade (REQUIRED)
    • MUST be present to display a checkbox on screen.

Checkbox field

Please refer to the checkbox field accessibility docs for information about accessibility concerns.

A checkbox field is an extension of the checkbox control pattern, above.

Syntax

Unless specified, elements should be defined in the order presented below.

<!-- Root (REQUIRED) -->
<bolt-checkbox-control
  class="
    [bolt-invalid]
  "
>
  <!-- Input (REQUIRED) -->
  <input
    [aria-describedby="ERRORS_ID"]
    id="INPUT_ID"
    type="checkbox"
    ...
  />

  <!-- Label (REQUIRED) -->
  <label for="INPUT_ID">
    <!-- Facade (REQUIRED) -->
    <bolt-checkbox-facade></bolt-checkbox-facade>

    <!-- Field label (REQUIRED) -->
    <div class="bolt-field__label">...</div>

    <!-- Field description (optional) -->
    <div class="bolt-field__description">...</div>
  </label>

  <!-- Field errors (optional) -->
  <div
    [aria-live="..."]
    class="bolt-field__errors"
    id="ERRORS_ID"
  >
    <!-- Error (optional) -->
    <bolt-field-error>...</bolt-field-error>
  </div>
</bolt-checkbox-control>

Anatomy

A checkbox field is comprised of the following items:

  • All checkbox control items.
  • Field label (REQUIRED)
    • MUST be present to provide an accessible label.
    • MUST have .bolt-field__label class.
  • Field description (optional)
    • MUST have .bolt-field__description class.
    • Supports formatted text, but avoid including interactive elements.
  • Field errors (optional)
    • Supports wrapping one or more error messages to be associated with the Input.
    • MUST have .bolt-field__errors class.
    • MUST have an [id] attribute that is referenced from [aria-describedby] attribute of Input.
    • MAY define [aria-live] attribute, depending on validation strategy.
    • NOT permitted within the checkbox group pattern.
  • Error (optional)

Checkbox group

Please refer to the checkbox group accessibility docs for information about accessibility concerns.

Syntax

Unless specified, elements should be defined in the order presented below.

<!-- Root (REQUIRED) -->
<fieldset
  class="
    bolt-fieldset bolt--checkboxes
    [bolt-invalid]
  "
  [disabled]
>
  <!-- Legend (REQUIRED) -->
  <legend>
    <!-- Fieldset name (REQUIRED) -->
    <span class="bolt-fieldset__name">
      ...
    </span>

    <!-- Annotation (optional) -->
    <span class="bolt-annotation bolt-optional">
      (optional)
    </span>

    <!-- Contextual help (optional) -->
    <bolt-contextual-help
      type="push"
      [disabled]
      ...
    >
      ...
    </bolt-contextual-help>

    <!-- Instructional text (optional) -->
    <div class="bolt-help">
      This is some instructional text.
    </div>

    <!-- Fieldset errors (optional) -->
    <div
      [aria-live="..."]
      class="bolt-fieldset__errors"
    >
      <!-- Error (optional) -->
      <bolt-field-error>...</bolt-field-error>
    </div>
  </legend>

  <!-- Toggles (optional) -->
  <div class="bolt-fieldset__toggles">
    <!-- "All" button (REQUIRED) -->
    <button type="button">Select all</button>
    <!-- Divider (REQUIRED) -->
    <span>|</span>
    <!-- "None" button (REQUIRED) -->
    <button type="button" disabled>Select none</button>
  </div>

  <!-- Fieldset body (REQUIRED) -->
  <div class="bolt-fieldset__body">
    <!-- Field 1 -->
    <bolt-checkbox-control>...</bolt-checkbox-control>
    ...
    <!-- Field N -->
    <bolt-checkbox-control>...</bolt-checkbox-control>
  </div>
</fieldset>

Anatomy

A checkbox group is comprised of the following items:

  • Root (REQUIRED)
    • MUST be a <fieldset> element to apply correct semantic markup.
    • MUST match .bolt-fieldset.bolt--checkboxes CSS selector.
    • MAY apply .bolt-invalid class to apply "invalid" appearance to the entire group.
    • MAY add [disabled] attribute to semantically disable all fields within the group.
    • Refer to MDN for best practices on using the HTML <fieldset> element.
  • Legend (REQUIRED)
    • MUST be present for semantic configuration.
  • Fieldset name (REQUIRED)
    • MUST have .bolt-fieldset__name class.
    • MUST be an inline element.
  • Annotation (optional)
    • When present, communicates that selecting options within the group is not critical for workflow progression.
    • MUST match .bolt-annotation.bolt-optional CSS selector.
    • MUST be an inline element.
    • Should have "(optional)" as inner text.
  • Contextual help (optional)
    • MUST have [type="push"]
    • See contextual help component for more information.
  • Fieldset errors (optional)
    • Supports wrapping one or more error messages to be associated with the group.
    • MUST have .bolt-fieldset__errors class.
    • MAY define [aria-live] attribute, depending on validation strategy.
  • Error (optional)
  • Toggles (optional)
    • MUST have .bolt-fieldset__toggles class.
    • MUST have at least one <button> enabled at all times, unless the entire <fieldset> is disabled.
  • Fieldset body (REQUIRED)
    • Base container element used to apply various layouts.
      • The grid component might be handy here.
    • MUST have .bolt-fieldset__body class
    • MUST have at least two checkbox field children.
 Design guidelines

HTML pattern specific guidelines

When using an HTML pattern, the responsibility falls on the consumer to ensure that proper UX interaction research and Accessibility standards are applied.

When to use

  • Use an individual checkbox in scenarios where you require more control over the layout of interconnected content.

When not to use

  • Do not use a checkbox control that lacks a clear visual label or implied affordance.
    • An unlabeled checkbox in a table header is typically understood to check/uncheck all checkboxes in visible table rows.
    • However, the purpose of an unlabeled checkbox sitting near a table is ambiguous.

General guidelines

  • Order individual Checkbox labels logically.
  • Lengthy text may wrap.
  • Checkbox group validation should occur upon submission of the parent form. Single Checkbox validation can occur after selecting the Checkbox or upon submission of the parent form.
  • Checkbox group options should be stacked vertically.
  • Consider using "select all" functionality in a Checkbox group based on context/content.
  • Error messages should be displayed below a Checkbox group's legend or below the input and label of a single Checkbox.
  • Avoid displaying more than one error message at a time. This can lead to user confusion.

When to use

  • Consider a Checkbox when the user can select 0, 1, or multiple values from a predefined list.
  • Consider a Checkbox when form submission is needed.
  • Consider a single Checkbox for user confirmation, e.g., "I agree to…" or "I have read…".

When not to use

  • Avoid using Checkboxes for revealing or hiding other screen components.
  • Avoid long lists of Checkboxes. Aim to keep the list to 7 options or under.

When to use something else

  • Consider using a Switch for immediate actions that do not require reviewing or confirming.
  • Consider a Radio button or a Select if users need to make a single, mutually-exclusive selection from two or more options.

Do

  • Use the indeterminate state when the Checkbox contains a sub-list of selections.
  • Align the Checkbox on the left side of the first line of a left-justified field label.
  • Use Checkboxes when form submission is needed.
  • Use a single Checkbox for user confirmation, e.g., "I agree to…" or "I have read…".

Don't

  • Don't use Checkboxes for triggering navigation or immediate actions.
  • Don't use Checkboxes for revealing or hiding other screen components.

Content guidelines

  • Write labels as statements that the checked state makes true, and the unchecked state makes false.
  • Avoid using negative phrasing for labels.
  • Use sentence case for Checkbox group labels and individual Checkbox labels.
  • Ending punctuation is not needed for individual Checkbox labels.
 Accessibility

In addition to code requirements, the following guidelines should be taken into account to ensure maximum accessibility.

Checkbox control

See also: checkbox control API
  • A lone checkbox control MUST define an accessible label via one of the following strategies:
    • input[aria-label]
    • input[aria-labelledby] + external element
    • visually-hidden text within the associated <label>

Checkbox field

See also: checkbox field API
  • AVOID including interactive elements within the field description.
    • These types of elements will conflict with expected field interactions.
  • An "invalid" checkbox field MUST make use of the [aria-describedby] attribute to connect the <input> with displayed error messages.

Checkbox group

See also: checkbox group API
  • By default, screen readers will NOT automatically announce error messages that are dynamically added to the group <legend>.
    • Configuring the errors wrapper as a live region via the [aria-live] attribute is a potential strategy for communicating mid-form validation errors with AT users (before form submission).

      If you implement this strategy in your project, make sure to perform proper accessibility testing to ensure that screen readers announce errors at relevant times during user interaction.

Display settings

Note: not all settings persist across pages

Default Compact (-1) Sparse (+1) XL (default) 2XL 3XL Default Min Max Light (default) System Dark Branded (default) Unbranded