Carbon Design System

Checkbox

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.

Edit this page on GitHub

Components: Button

Checkbox: Usage