Checkboxes

Permits user to make one or more selections from a list

# Overview

# Default (Medium)

Default and standard spacing for checkboxes.

# Size

Different sizing for checkboxes.

# Indeterminate

Displays status for checkbox group by indicating that some of the sub-selections in a list are selected. Provides user with ability to select or unselect all items in the list’s sub-group. To see a functioning example see this codesandbox.

# Custom

Custom styles for checkboxes.

# Accessibility

Many WCAG requirements are contextual to their implementation. To ensure that usage of this component complies with accessibility guidelines you are responsible for the following:

  • Each checkbox must be focusable and keyboard accessible:
    • When the checkbox has focus, the Space key changes the selection
    • Tab key moves to next element in list
  • Fieldsets (or grouped checkboxes) should be:
    • Used when associating group of checkboxes
    • Identified or described as a group using a <legend> tag
  • Avoid nested fieldsets
  • Single checkboxes:
    • May be interchangeable with a toggle or Radio Button
    • Write labels to be self-explanatory
  • Custom checkboxes maintain accessibility requirements. The checkbox icon is only visually hidden and replaced with custom style

This component has compliance with WCAG guidelines by:

  • Wrapping the input in a label element and label is automatically associated with it

For more information, review techniques and failures for:


# Guidelines

# Use When

  • Selecting one or multiple choices from a list
  • Selecting options from a list that contains sub-selections
  • Choosing "yes" or "no" when there is a single option (stand-alone checkbox)
  • Viewing all available options is needed
  • Comparing between a list of selections is desired

# Don't Use When

  • Selecting from a list when only one choice is allowed. Instead, use Radio Buttons

# Content

When using checkboxes in a list:

  • Use a logical order, whether it’s alphabetical, numerical, or time-based
  • Labels should have approximately equal length
  • Clearly communicate the effect of selecting the option
  • Provide a link or include a subtitle for more information. Don’t rely on tooltips to explain a checkbox

Checkbox labels should:

  • Start with a capital letter
  • Use sentence case
  • Use positive phrasing so that the label describes the selected state
  • Avoid long labels
  • Be written as sentence fragments
  • No terminal punctuation

# Do/Don't

Image showing proper checkbox sentence case.
Do use sentence case, with only proper nouns capitalized.
Image showing improper title caps use.
Don't use title caps for labels.
Image showing proper checkbox label with brief copy
Do make labels brief.
Image showing a label with too much text
Don't put too much text in the label.
Image showing proper checkbox positive phrasing
Do use positive phrasing for labels.
Image showing a label with negative phrasing
Don't use negative phrasing for labels.
Image showing proper checkbox label with no ending punctuation
Do write labels as sentence fragments with no ending punctuation.
Image showing improper terminal punctuation.
Don't add terminal punctuation at the end of a label.

# Behavior

Checkboxes work independently from each other:

  • Selecting one checkbox shouldn’t change the selection status of another checkbox in the list
  • When parent checkbox is used for a bulk selection action, all child checkbox items will be selected or not selected
  • Use a standalone checkbox for a simple toggle selection. Don’t use radio buttons or toggles

Image showing proper simple checkbox usage
Do use a single checkbox.
Image showing a radio button used when a checkbox is preferred
Don't use radio buttons or toggles for a simple toggle selection.

# Resources


# API

# Props

This component will bind any attribute that a native HTML checkbox element accepts.

labelClass

name

string

type

N/A

default

Adds CSS class to the label for custom styles.

inputClass

name

string

type

N/A

default

Adds CSS class to the input for custom styles.

contentClass

name

string

type

N/A

default

Adds CSS class to the slot wrapper for custom styles.

indeterminate

name

boolean

type

false

default

Shows checkbox in indeterminate state. This is a visual-only state with no logic for when to show it.

trueValue

name

string, number, boolean, object, array, symbol, function

type

true

default

The value when checked.

falseValue

name

string, number, boolean, object, array, symbol, function

type

false

default

The value when unchecked.

customValue

name

string, number, boolean, object, array, symbol, function

type

false

default

The value when used in a checkbox group. Replaces `trueValue` and `falseValue`.

The `compact` modifier is deprecated in the winter 2020 release and will be removed. Use size="small" instead

modifier

name

string

type

N/A

default

Modifies the style variant for this component. Possible values: { ‘hide-figure’ }

size

name

string

type

'medium'

default

Sets the checkbox size; values can target responsive breakpoints. Breakpoint values are: xs, sm, md, and lg. Examples: { 'small' | 'medium' | 'large' | 'large@sm' }

# Slots

Find more information about using Slots in the article Getting Started as a Developer.

default

name

Sets the innerHTML for CdrCheckbox. This is the readable text for the <label> element.

# Events

change

name

newValue, event

arguments

$emit event fired on check/uncheck.

# Usage

The CdrCheckbox component requires v-model to track :checked values.

This example uses true-value and false-value props to change what’s saved to the model.

<template>
  <cdr-checkbox
    v-model="model"
    true-value="checked"
    false-value="unchecked"
  >
    Option 1
  </cdr-checkbox>
</template>
1
2
3
4
5
6
7
8
9

Use custom-value with a shared model to create a checkbox group that will track multiple checkbox values.

<template>
  <cdr-checkbox
    v-model="groupModel"
    :custom-value="{ value: ‘D’ }"
  >
    Option 1
  </cdr-checkbox>
  <cdr-checkbox
    v-model="groupModel"
    :custom-value="[ 9, 10 ]"
  >
    Option 2
  </cdr-checkbox>
</template>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

If both values are checked, the model would be [ { value: ‘D’ }, [ 9, 10 ] ]. Unchecking either checkbox would remove its value from the model array.

Default checkbox to checked/unchecked state by setting the model in Javascript.

<template>
  <cdr-checkbox
    v-model="groupModel"
    :custom-value="{ value: ‘D’ }"
  >
    Option 1
  </cdr-checkbox>
  ...
</template>
<script>
  ...
  data() {
    return {
      groupModel: [ { value:D} ],
    };
  },
}
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Set the indeterminate prop to true to generate an indeterminate checkbox, which looks different than the default. This is a visual styling only; it does not include any of the functional aspects of an indeterminate checkbox. To see a functioning example see this codesandbox.

<template>
  <cdr-checkbox
    v-model="groupModel"
    :indeterminate="true"
  >
    Option 1
  </cdr-checkbox>
  ...
</template>
1
2
3
4
5
6
7
8
9

# Modifiers

Following variants are available to the cdr-checkbox modifier attribute:

Value Description
'hide-figure' Hides the checkbox icon

Use the hide-figure modifier to hide the checkbox itself, which leaves the text label as the clickable element. Add appropriate custom styles to convey selected and unselected states.

<template>
  <cdr-checkbox
    v-model="model"
    name="model"
    value="model"
    modifier="hide-figure"
    input-class="no-box"
    content-class="no-box__content"
  >
    Add to cart
  </cdr-checkbox>
</template>

<style>
.no-box:checked ~ .no-box__content {
   color: green;

   &::after {
     content: '(checked)';
   }
 }
</style>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22