This is Cedar’s legacy site. Information may be outdated.
Go to Cedar's new documentation site for the latest features and support.

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.

# Custom True/False Value

Use a custom value in place of true/false checked state.

# Custom Model Value

Use an array as the model to track a list of custom values.

# Handling Change Events

Pass checkbox data into change handlers.

# 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. Note the usage of aria-controls, id, role, aria-label, and aria-labelledby.

# Custom

Custom styles for checkboxes.

# Validation

Render a checkbox group with validation and error state

# 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
  • CdrFormGroup should be:
    • Used when associating group of checkboxes
    • Identified or described as a group using the label property or slot
  • Avoid nesting CdrFormGroup
  • 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

Four checkboxes with labels in sentence case.
Do use sentence case, with only proper nouns capitalized.
Four checkboxes with labels in title case.
Don't use title caps for labels.
A proper checkbox label with brief copy.
Do make labels brief.
A checkbox label with too much text.
Don't put too much text in the label.
A checkbox label with the positive phrase turn on notifications.
Do use positive phrasing for labels.
A checkbox label with the negative phrase turn off notifications.
Don't use negative phrasing for labels.
Checkbox label without punctuation at the end.
Do write labels as sentence fragments with no ending punctuation.
Checkbox label with punctuation at the end.
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

A single checkbox.
Do use a single checkbox.
A radio button instead of the preferred checkbox.
Don't use radio buttons or toggles for a simple toggle selection.

# Resources


# API

View it on Github: https://github.com/rei/rei-cedar-vue-2/tree/next/src/components/checkbox

# Props

This component will bind any attribute that a native HTML checkbox element (opens new window) 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`.

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 Installing Cedar.

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.

# Component Variables

For projects that cannot make use of the Vue.js component, the CdrLabelWrapper styles are available through the `@rei/cdr-component-variables` package as SCSS and LESS mixins which can be applied to plain HTML elements. See examples on the Component Variables page.

# 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 the indeterminate example.

<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