Checkbox

Checkbox (input + label)
Checkbox (input > label)
Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<fieldset class="bx--fieldset">
  <legend class="bx--label">Checkbox (input + label)</legend>
  <!-- input + label -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <input id="bx--checkbox-new" class="bx--checkbox" type="checkbox" value="new"
      name="checkbox" checked>
    <label for="bx--checkbox-new" class="bx--checkbox-label">Checkbox</label>
  </div>
  <!-- input + label indeterminate -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <input id="bx--checkbox-ind" class="bx--checkbox" type="checkbox" value="new"
      name="checkbox" aria-checked="mixed">
    <label for="bx--checkbox-ind" class="bx--checkbox-label">Indeterminate checkbox</label>
  </div>
  <!-- input + label checked disabled -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <input id="bx--checkbox-new--disabled" class="bx--checkbox" type="checkbox" value="new"
      name="checkbox" checked disabled>
    <label for="bx--checkbox-new--disabled" class="bx--checkbox-label">Checkbox</label>
  </div>
  <!-- input + label indeterminate disabled -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <input id="bx--checkbox-ind--disabled" class="bx--checkbox" type="checkbox" value="new"
      name="checkbox" aria-checked="mixed" disabled>
    <label for="bx--checkbox-ind--disabled" class="bx--checkbox-label">Indeterminate
      checkbox</label>
  </div>
  <!-- input + label disabled -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <input id="bx--checkbox-disabled" class="bx--checkbox" type="checkbox" value="new"
      name="checkbox" disabled>
    <label for="bx--checkbox-disabled" class="bx--checkbox-label">Disabled checkbox</label>
  </div>
</fieldset>
<fieldset class="bx--fieldset">
  <legend class="bx--label">Checkbox (input > label)</legend>
  <!-- label > input -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <label for="bx--checkbox-new2" class="bx--checkbox-label">
      <input id="bx--checkbox-new2" class="bx--checkbox" type="checkbox" value="yellow"
        name="checkbox" checked>
      Checkbox
    </label>
  </div>
  <!-- label > input indeterminate -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <label for="bx--checkbox-ind2" class="bx--checkbox-label"
      data-contained-checkbox-state="mixed">
      <input id="bx--checkbox-ind2" class="bx--checkbox" type="checkbox" value="yellow"
        name="checkbox" aria-checked="mixed">
      Indeterminate checkbox
    </label>
  </div>
  <!-- label > input checked disabled -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <label for="bx--checkbox-new2--disabled" class="bx--checkbox-label">
      <input id="bx--checkbox-new2--disabled" class="bx--checkbox" type="checkbox"
        value="yellow" name="checkbox" checked disabled>
      Checkbox
    </label>
  </div>
  <!-- label > input indeterminate disabled -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <label for="bx--checkbox-ind2--disabled" class="bx--checkbox-label"
      data-contained-checkbox-state="mixed">
      <input id="bx--checkbox-ind2--disabled" class="bx--checkbox" type="checkbox"
        value="yellow" name="checkbox" aria-checked="mixed" disabled>
      Indeterminate checkbox
    </label>
  </div>
  <!-- label > input unchecked disabled -->
  <div class="bx--form-item bx--checkbox-wrapper">
    <label for="bx--checkbox-disabled2" class="bx--checkbox-label">
      <input id="bx--checkbox-disabled2" class="bx--checkbox" type="checkbox" value="yellow"
        name="checkbox" disabled>
      Disabled checkbox
    </label>
  </div>
</fieldset>

Documentation

Javascript

Public Methods

Name Params Description
setState state: String ['true', 'false', 'mixed'] Can be used to set the checkbox to true(checked), false(unchecked) or mixed (indeterminate)
setDisabled state: Boolean Can be used to set the checkbox to disabled, needed for the label > input

Options

Option Default Selector Description
selectorInit .bx--checkbox The CSS selector to find checkbox
selectorContainedCheckboxState [data-contained-checkbox-state] The CSS selector to find a container of checkbox preserving checked state
selectorContainedCheckboxDisabled [data-contained-checkbox-disabled] The CSS selector to find a container of checkbox preserving disabled state
classLabel .bx--checkbox-label The CSS class for the label
classLabelFocused .bx--checkbox-label__focus The CSS class for the focused label
attribContainedCheckboxState data-contained-checkbox-state The attribute name for the checked state of contained checkbox
attribContainedCheckboxDisabled data-contained-checkbox-disabled The attribute name for the disabled state of contained checkbox

FAQ

Two ways to write checkbox HTML

Checkbox HTML can be written in two ways:

With input and label as siblings

<div class="bx--form-item">
  <input id="bx--checkbox" class="bx--checkbox" type="checkbox" value="green" name="checkbox" />
  <label for="bx--checkbox" class="bx--checkbox-label"> Checkbox (input + label) </label>
</div>

With label wrapping input

<div class="bx--form-item">
  <label class="bx--checkbox-label">
    <input class="bx--checkbox" type="checkbox" value="yellow" name="checkbox" /> Checkbox (label > input)
  </label>
</div>

Note: You no longer need to include a SVG for the checkmark to render.

Fieldset and Legend

As a best practice, groups of checkboxes should make use of <fieldset> and <legend> (see Form for details). This is especially true for forms submitting data.

But, there are exceptions to the rule. For example, Data Tables make use of checkboxes as a way to select rows of data. Checkboxes in this context would represent an entire row of data in its associated table row.