View on GitHub

Checkbox

Create consistent cross-browser and cross-device checkboxes.

On this page

You can find here the OUDS Checkbox design guidelines.

Overview

Checkboxes allow users to select one or more options from a number of choices.

They are implemented using .control-item-* classes, see below. Browser default checkboxes are replaced with the help of the selector .control-item-indicator[type="checkbox"].

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" value="" id="checkboxDefault" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxDefault">Default checkbox</label>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input checked class="control-item-indicator" type="checkbox" value="" id="checkboxDefault2" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxDefault2">Checked checkbox</label>
  </div>
</div>
html
Bootstrap $enable-bootstrap-compatibility: true 
<div class="form-check">
  <input class="form-check-input" type="checkbox" value="" id="checkDefault" />
  <label class="form-check-label" for="checkDefault">
    Default checkbox (Bootstrap compatible)
  </label>
</div>
<div class="form-check">
  <input checked class="form-check-input" type="checkbox" value="" id="checkChecked" />
  <label class="form-check-label" for="checkChecked">
  Checked checkbox (Bootstrap compatible)
  </label>
</div>
html

Control item

Control item is an abstraction for several non-text input components, like checkbox, radio button and switch, that have similar behavior and layout. It contains an <input /> indicator, a text container for the label and an optional icon.

We use the parent element selector (:has) for all our <input /> states, like :invalid or :disabled. When combined with the .control-item-label class, we can easily style the text for each item based on the <input />’s state.

.control-item-assets-container controls the position of the .control-item-indicator and the optional icon.

.control-item-text-container contains the label and optional helper text and controls their positioning.

.control-item-label extend their clickable area until a .checkbox-standalone, .radio-button-standalone, .switch-standalone or a position: relative; is found in the page hierarchy. This ensures a consistent approach, whatever the DOM is. Consequently, none of the elements next to the label should be interactive.

.control-item-indicator uses customized icons to indicate checked states.

Variants

Divider

To display a divider, add .control-item-divider to a .checkbox-item.

<div class="checkbox-item control-item-divider">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" value="" id="checkboxDivider" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxDivider">Default checkbox with divider</label>
  </div>
</div>
<div class="checkbox-item control-item-divider">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" value="" id="checkboxDivider2" checked />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxDivider2">Checked checkbox with divider</label>
  </div>
</div>
html

Icon

The recommended way to use icons is to fill an SVG sprite file, and use currentColor for styling. If really necessary, for example when you have a lot of icons, you can use an icon font. Find out more about using icons.

To display an icon, add .control-item-assets-container with an icon (SVG or font-icon most likely) inside, as a child of a .checkbox-item.

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" value="" id="checkboxWithSVG" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxWithSVG">Default checkbox with an SVG icon</label>
  </div>
  <div class="control-item-assets-container">
    <svg aria-hidden="true">
      <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
    </svg>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" value="" id="checkboxWithIconFont" checked />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxWithIconFont">Checked checkbox with a font-icon</label>
  </div>
  <div class="control-item-assets-container">
    <span class="icon si si-settings" aria-hidden="true"></span>
  </div>
</div>
html

Helper text

To display a helper text, add a .control-item-helper as a sibling of a .control-item-label. Make sure the helper text is accessible by adding an aria-describedby attribute to the input.

Helper text

Helper text

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" aria-describedby="checkboxHelperTextDescription" id="checkboxHelperText" value="" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxHelperText">Default checkbox</label>
    <p class="control-item-helper" id="checkboxHelperTextDescription">Helper text</p>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" aria-describedby="checkboxHelperTextDescription2" id="checkboxHelperText2" value="" checked />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxHelperText2">Checked checkbox</label>
    <p class="control-item-helper" id="checkboxHelperTextDescription2">Helper text</p>
  </div>
</div>
html

Layout

Default

It's recommended to keep checkbox label to no more than three words. When space is limited or when a long label or helper text is required, the text can wrap, as this is preferable to truncation. The checkbox indicator and the icon will remain vertically centered, until the .control-item-assets-container reaches a defined maximum height.

Helper text

A longer helper text that can wrap to another line to show the behaviour

Also a longer helper text, it will also wrap at some point depending on the component width

<div class="row">
  <div class="col-8 col-md-6 col-xl-5">
    <div class="checkbox-item control-item-divider">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checboxLayout1" aria-describedby="checboxLayout1Description" />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checboxLayout1">Label</label>
        <p class="control-item-helper" id="checboxLayout1Description">Helper text</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
    <div class="checkbox-item control-item-divider">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checboxLayout2" aria-describedby="checboxLayout2Description" />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checboxLayout2">A short label</label>
        <p class="control-item-helper" id="checboxLayout2Description">A longer helper text that can wrap to another line to show the behaviour</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
    <div class="checkbox-item control-item-divider">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checboxLayout3" aria-describedby="checboxLayout3Description" checked />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checboxLayout3">A longer label for showing behavior in this case, checkbox indicator and icon will stick to the top area of the component</label>
        <p class="control-item-helper" id="checboxLayout3Description">Also a longer helper text, it will also wrap at some point depending on the component width</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
  </div>
</div>
html

Reverse

To reverse the component, simply add .control-item-reverse to a .checkbox-item.

Helper text

Also a longer helper text, it will also wrap at some point depending on the component width

<div class="row">
  <div class="col-8 col-md-6 col-xl-5">
    <div class="checkbox-item control-item-divider control-item-reverse">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checboxLayoutRev1" aria-describedby="checboxLayoutRev1Description" />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checboxLayoutRev1">Label with reverse layout</label>
        <p class="control-item-helper" id="checboxLayoutRev1Description">Helper text</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
    <div class="checkbox-item control-item-divider control-item-reverse">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checboxLayoutRev2" aria-describedby="checboxLayoutRev2Description" checked />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checboxLayoutRev2">A longer label with reverse layout for showing behavior in this case, checkbox indicator and icon will stick to the top area of the component</label>
        <p class="control-item-helper" id="checboxLayoutRev2Description">Also a longer helper text, it will also wrap at some point depending on the component width</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
  </div>
</div>
html
Bootstrap $enable-bootstrap-compatibility: true

Put your checkboxes on the opposite side with the .form-check-reverse modifier class.

<div class="form-check form-check-reverse">
  <input class="form-check-input" type="checkbox" value="" id="reverseCheck" checked />
  <label class="form-check-label" for="reverseCheck">
    Checked reverse checkbox (Bootstrap compatible)
  </label>
</div>
html

Indeterminate

This is often used to indicate a partial selection within a group of choices. For instance, in a nested (hierarchical) list, a parent checkbox can be indeterminate if some, but not all, sub-options are selected. Learn more about nesting in the design guidelines.

Users cannot set a checkbox as indeterminate directly. This must be calculated by the system and set via JavaScript (there is no available HTML attribute available for specifying it). Then, checkboxes use the :indeterminate pseudo class for styling.

Indeterminate state can be used in conjunction with all the other states below.

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator" type="checkbox" value="" id="checkboxIndeterminate" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxIndeterminate">Indeterminate checkbox</label>
  </div>
</div>
html

Here is the associated JavaScript to set a checkbox as indeterminate.

const checkbox = document.getElementById('checkbox')

checkbox.indeterminate = true
Bootstrap $enable-bootstrap-compatibility: true 
<div class="form-check">
  <input class="form-check-input" type="checkbox" value="" id="checkIndeterminate" />
  <label class="form-check-label" for="checkIndeterminate">
    Indeterminate checkbox (Bootstrap compatible)
  </label>
</div>
html

States

Disabled

Add the disabled attribute to the input, then the checkbox and the associated <label> are automatically styled to match with a lighter color to help indicate the input’s state.

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input disabled class="control-item-indicator" type="checkbox" value="" id="checkboxDisabled" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxDisabled">Default disabled checkbox</label>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input disabled class="control-item-indicator" type="checkbox" value="" id="checkboxCheckedDisabled" checked />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxCheckedDisabled">Checked disabled checkbox</label>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input disabled class="control-item-indicator" type="checkbox" value="" id="checkboxIndeterminateDisabled" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxIndeterminateDisabled">Indeterminate disabled checkbox</label>
  </div>
</div>
html
Bootstrap $enable-bootstrap-compatibility: true 

<div class="form-check">
  <input disabled class="form-check-input" type="checkbox" value="" id="checkDisabled" />
  <label class="form-check-label" for="checkDisabled">
    Default disabled checkbox (Bootstrap compatible)
  </label>
</div>
<div class="form-check">
  <input disabled class="form-check-input" type="checkbox" value="" id="checkCheckedDisabled" checked />
  <label class="form-check-label" for="checkCheckedDisabled">
    Checked disabled checkbox (Bootstrap compatible)
  </label>
</div>
<div class="form-check">
  <input disabled class="form-check-input" type="checkbox" value="" id="checkIndeterminateDisabled" />
  <label class="form-check-label" for="checkIndeterminateDisabled">
    Indeterminate disabled checkbox (Bootstrap compatible)
  </label>
</div>
html

Read only

To create a read only checkbox, the input should be replaced by a span element with role="checkbox", aria-readonly="true" and aria-disabled="true" attributes. The checkbox will be accessible to keyboard navigation and assistive technologies, thanks to aria-labelledby and tabindex, but other interactions will be prevented.

Default readonly checkbox

Checked readonly checkbox

Indeterminate readonly checkbox

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <span class="control-item-indicator" role="checkbox" aria-readonly="true" aria-disabled="true" tabindex="0" aria-checked="false" aria-labelledby="checkboxReadonlyLabel"></span>
  </div>
  <div class="control-item-text-container">
    <p class="control-item-label" id="checkboxReadonlyLabel">Default readonly checkbox</p>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <span class="control-item-indicator" role="checkbox" aria-readonly="true" aria-disabled="true" tabindex="0" aria-checked="true" aria-labelledby="checkboxReadonlyCheckedLabel"></span>
  </div>
  <div class="control-item-text-container">
    <p class="control-item-label" id="checkboxReadonlyCheckedLabel">Checked readonly checkbox</p>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <span class="control-item-indicator" role="checkbox" aria-readonly="true" aria-disabled="true" tabindex="0" aria-checked="mixed" aria-labelledby="checkboxReadonlyIndeterminate"></span>
  </div>
  <div class="control-item-text-container">
    <p class="control-item-label" id="checkboxReadonlyIndeterminate">Indeterminate readonly checkbox</p>
  </div>
</div>
html

Invalid

The invalid state is the equivalent of the ‘Error’ state that you can find in the design specification.

To display an invalid checkbox, add .is-invalid to a .control-item-indicator. Please take a look at our Validation page to learn more.

Helper text

Helper text

Helper text

<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator is-invalid" type="checkbox" value="" id="checkboxInvalid" aria-describedby="checkboxInvalidDescription" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxInvalid">Default invalid checkbox</label>
    <p class="control-item-helper" id="checkboxInvalidDescription">Helper text</p>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator is-invalid" type="checkbox" value="" id="checkboxInvalid2" aria-describedby="checkboxInvalid2Description" checked />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxInvalid2">Checked invalid checkbox</label>
    <p class="control-item-helper" id="checkboxInvalid2Description">Helper text</p>
  </div>
</div>
<div class="checkbox-item">
  <div class="control-item-assets-container">
    <input class="control-item-indicator is-invalid" type="checkbox" value="" id="checkboxInvalidIndeterminate" aria-describedby="checkboxInvalidIndeterminateDescription" />
  </div>
  <div class="control-item-text-container">
    <label class="control-item-label" for="checkboxInvalidIndeterminate">Indeterminate invalid checkbox</label>
    <p class="control-item-helper" id="checkboxInvalidIndeterminateDescription">Helper text</p>
  </div>
</div>
html
Bootstrap $enable-bootstrap-compatibility: true

To display an invalid checkbox, add .is-invalid to a .form-check-input.

<div class="form-check">
  <input class="form-check-input is-invalid" type="checkbox" value="" id="checkInvalid" />
  <label class="form-check-label" for="checkInvalid">
    Default invalid checkbox (Bootstrap compatible)
  </label>
</div>
html

Group

If checkboxes belong to a group (e.g., in a form), provide clear context by adding a <legend> element inside a <fieldset> for the group title. Then, screen readers will read the legend before navigating through the checkboxes.

Checkboxes group example

Helper text

Helper text

<div class="row">
  <fieldset class="col-md-6">
    <legend>Checkboxes group example</legend>
    <div class="checkbox-item control-item-divider">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checkboxGroup1" aria-describedby="checkboxGroup1Description" />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checkboxGroup1">Group checkbox 1</label>
        <p class="control-item-helper" id="checkboxGroup1Description">Helper text</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
    <div class="checkbox-item control-item-divider">
      <div class="control-item-assets-container">
        <input class="control-item-indicator" type="checkbox" value="" id="checkboxGroup2" aria-describedby="checkboxGroup2Description" checked />
      </div>
      <div class="control-item-text-container">
        <label class="control-item-label" for="checkboxGroup2">Group checkbox 2</label>
        <p class="control-item-helper" id="checkboxGroup2Description">Helper text</p>
      </div>
      <div class="control-item-assets-container">
        <svg aria-hidden="true">
          <use xlink:href="/sosh/docs/0.5/assets/img/ouds-web-sprite.svg#heart-empty" />
        </svg>
      </div>
    </div>
  </fieldset>
</div>
html

Standalone

This standalone version is commonly used for building custom components and should not be used on its own. Remember to provide some sort of accessible name for assistive technologies (for instance, using aria-labelledby, a .visually-hidden, aria-label or a second label). See the forms overview accessibility section for details.

For the standalone checkbox, we provide a completely different architecture to ease the integration inside your projects.

<label class="checkbox-standalone">
  <input class="control-item-indicator" type="checkbox" value="" />
  <span class="visually-hidden">Standalone checkbox</span>
</label>
html
Bootstrap $enable-bootstrap-compatibility: true

Be careful when using this, as you must implement the background on hover, focus and active states.

<div style="position: relative">
  <input class="form-check-input" type="checkbox" id="checkboxNoLabel" value="" aria-label="Standalone checkbox (Bootstrap compatible)" />
</div>
html