Skip to main content Skip to docs navigation

Checkbox

Highly customizable, native checkbox <input> elements for presenting toggleable options.

GitHub Edit on GitHub
On this page

Trialing new components with the following rules:

  • New components are purely components, they don't assume layout of any kind.
  • New options for form layout:
    • Use new form groups to lay out your forms: .control-group, .check-group, .radio-group.
    • Use helpers to lay out your forms—.hstack and .vstack—with utilities.

Basic checkbox

All checkbox styling is contained to a wrapper class, .check. This does the following:

  • Adds a stacking grid layout for the checkbox and custom SVG icon.
  • Overrides the default <input> appearance with themed colors.
  • Handles the toggling of separate paths in our custom SVG for the :checked and indeterminate states. Two <path>s are included in the SVG, one for each state, and the appropriate <path> is shown based on the <input>’s state.

For folks looking to replace our provided icons, you'll need to add the .checked and .indeterminate classes to the <path>s and use them in a single <svg> element.

Checkbox layout and labels are handled with additional HTML and CSS.

HTML
<div class="check">
  <input type="checkbox" id="check" checked />
  <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
    <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
    <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
  </svg>
</div>

Indeterminate

Checkboxes can utilize the indeterminate pseudo class when manually set via JavaScript. There is no available HTML attribute for specifying it.

HTML
<div class="check">
  <input type="checkbox" id="checkIndeterminate" />
  <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
    <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
    <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
  </svg>
</div>

Label

Wrap the .check in a <b-checkgroup> layout component and add your label. We use a custom element for layout here that sets some basic flexbox styling.

Consider margin utilities for additional spacing, and flex utilities for alignment.
HTML
<b-checkgroup>
  <div class="check">
    <input type="checkbox" id="checkLabel" />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkLabel">Example new checkbox</label>
</b-checkgroup>

Theme colors

Modify the appearance of checked checkboxes by adding the .theme-{color} class to the .check element. This will set the checked background and border color to the theme color.
HTML
<b-checkgroup>
  <div class="check theme-primary">
    <input type="checkbox" id="checkprimary" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkprimary">Example primary checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-accent">
    <input type="checkbox" id="checkaccent" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkaccent">Example accent checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-success">
    <input type="checkbox" id="checksuccess" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checksuccess">Example success checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-danger">
    <input type="checkbox" id="checkdanger" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkdanger">Example danger checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-warning">
    <input type="checkbox" id="checkwarning" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkwarning">Example warning checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-info">
    <input type="checkbox" id="checkinfo" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkinfo">Example info checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-inverse">
    <input type="checkbox" id="checkinverse" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkinverse">Example inverse checkbox</label>
</b-checkgroup>
<b-checkgroup>
  <div class="check theme-secondary">
    <input type="checkbox" id="checksecondary" checked />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checksecondary">Example secondary checkbox</label>
</b-checkgroup>

Description

With this layout approach, you can easily add a description or other content after the label. Here we use another custom element, <b-vstack>, to stack the label and description.

Supporting description for the above label.
HTML
<b-checkgroup>
  <div class="check">
    <input type="checkbox" id="checkDescription" />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <b-vstack>
    <label for="checkDescription">Example new checkbox</label>
    <small class="description">Supporting description for the above label.</small>
  </b-vstack>
</b-checkgroup>

Disabled

Add the disabled attribute and the associated <label>s are automatically styled to match with a lighter color to help indicate the input’s state.
HTML
<b-checkgroup>
  <div class="check">
    <input type="checkbox" id="checkDisabled" disabled />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkDisabled">Example new checkbox</label>
</b-checkgroup>
HTML
<b-checkgroup>
  <div class="check">
    <input type="checkbox" id="checkDisabledChecked" checked disabled />
    <svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'>
      <path class="checked" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='m6 10 3 3 6-6'/>
      <path class="indeterminate" fill='none' stroke='currentcolor' stroke-linecap='round' stroke-linejoin='round' stroke-width='3' d='M6 10h8'/>
    </svg>
  </div>
  <label for="checkDisabledChecked">Example new checkbox</label>
</b-checkgroup>

CSS

Variables

CSS variables for the checkbox component are built on the Sass variables.

SCSS
--check-bg: transparent;
--check-border-color: #{$check-border-color};
--check-checked-bg: #{$check-checked-bg};
--check-checked-border-color: #{$check-checked-border-color};
--check-indeterminate-bg: #{$check-indeterminate-bg};
--check-indeterminate-border-color: #{$check-indeterminate-border-color};
--check-disabled-bg: #{$check-disabled-bg};
--check-disabled-opacity: #{$check-disabled-opacity};

Sass variables

SCSS
$check-border-color: var(--border-color);
$check-checked-bg: var(--primary-base);
$check-checked-border-color: $check-checked-bg;
$check-indeterminate-bg: var(--primary-base);
$check-indeterminate-border-color: $check-indeterminate-bg;
$check-disabled-bg: var(--bg-3);
$check-disabled-opacity: .65;