checkbox

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

Labels

Do

Do use sentence case, with only proper nouns capitalized.

Don't

Don't use title caps for labels.

Do

Do make labels brief.

Don't

Don't put too much text in the label.

Do

Do use positive phrasing for labels.

Don't

Don't use negative phrasing for labels.

Do

Do write labels as sentence fragments with no ending punctuation.

Don't

Don't add terminal punctuation at the end of a label.

Checkboxes work independently from each other:

• Selecting one checkbox shouldn’t change the selection status of another checkbox in the list
• When a 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

Do

Do use a single checkbox.

Don't

Don't use radio buttons or toggles for a simple toggle selection.

What Cedar provides

CdrCheckbox wraps the input in a label element and the label is automatically associated with it.

Development responsibilities

When using this component, here's what you are responsible for:

Make each checkbox focusable and keyboard accessible:

• When the checkbox has focus, the Space key changes the selection
• Tab key moves to the next element in the list

Avoid nesting CdrFormGroup. CdrFormGroup should:

• Associate a group of checkboxes together
• Be identified or described as a group using the label property or slot

Single checkboxes may:

• Be interchangeable with a toggle or radio button
• Include a self-explanatory label

Custom checkboxes maintain accessibility requirements. The checkbox icon is only visually hidden and replaced with the custom style.

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. These can be applied to plain HTML elements. See examples on the component variables page.

Custom true/false value

<cdr-form-group label="Custom true/false label">
  <cdr-checkbox v-model="ex1" :background="backgroundColor" true-value="yes" false-value="no">Option 1?</cdr-checkbox> {{this.ex1}}
  <cdr-checkbox v-model="ex2" :background="backgroundColor" true-value="yes" false-value="no">Option 2?</cdr-checkbox> {{this.ex2}}
  <cdr-checkbox v-model="ex3" :background="backgroundColor" true-value="yes" false-value="no">Option 3?</cdr-checkbox> {{this.ex3}}
</cdr-form-group>

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>

Custom model value

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

<cdr-form-group label="Custom value label">
  <cdr-checkbox v-model="ex" :background="backgroundColor" custom-value="1">1</cdr-checkbox>
  <cdr-checkbox v-model="ex" :background="backgroundColor" custom-value="2">2</cdr-checkbox>
  <cdr-checkbox v-model="ex" :background="backgroundColor" custom-value="3">3</cdr-checkbox>
  {{this.ex}}
</cdr-form-group>

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>

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>

Handling change events

Pass checkbox data into change handlers.

<cdr-form-group label="Handling change label">
  Last edited: {{ this.lastEdited }}
  <cdr-checkbox v-model="ex" :background="backgroundColor" custom-value="1" @change="() => lastEdited = '1'">1</cdr-checkbox>
  <cdr-checkbox v-model="ex" :background="backgroundColor" custom-value="2" @change="() => lastEdited = '2'">2</cdr-checkbox>
  <cdr-checkbox v-model="ex" :background="backgroundColor" custom-value="3" @change="() => lastEdited = '3'">3</cdr-checkbox>
  {{ this.ex }}
</cdr-form-group>

Indeterminate

Note the usage of aria-controls, id, role, aria-label, and aria-labelledby

<cdr-form-group label="Choose your toppings">
   <cdr-checkbox
     v-model="allSelected"
     :background="backgroundColor"
     :indeterminate="isIndeterminate"
     @change="selectAll"
     aria-controls="toppings-input"
   >Select All</cdr-checkbox>
   <cdr-list role="group" id="toppings-input" aria-label="Individual toppings" class="inset">
     <li v-for="topping in toppings" :key="`checkbox-${topping}`">
        <cdr-checkbox
          v-model="selected"
          :background="backgroundColor"
          :custom-value="topping"
          name="toppings"
          @input="selectOne"
          aria-labelledby="toppings-input"
        >{{ topping }}</cdr-checkbox>
      </li>
   </cdr-list>
 </cdr-form-group>

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.

<template>
  <cdr-checkbox
    v-model="groupModel"
    :indeterminate="true"
  >
    Option 1
  </cdr-checkbox>
  ...
</template>

Custom

You have the option to use custom styles for checkboxes.

<cdr-form-group label="Custom checkbox label">
  <cdr-checkbox
    v-model="ex1"
    :background="backgroundColor"
    modifier="hide-figure"
    input-class="no-box"
    content-class="no-box__content">Custom checkbox 1</cdr-checkbox>
  <cdr-checkbox
    v-model="ex2"
    :background="backgroundColor"
    modifier="hide-figure"
    input-class="no-box"
    content-class="no-box__content">Custom checkbox 2</cdr-checkbox>
  <cdr-checkbox
    v-model="ex3"
    :background="backgroundColor"
    modifier="hide-figure"
    input-class="no-box"
    content-class="no-box__content"
    disabled>Custom checkbox 3</cdr-checkbox>
</cdr-form-group>

Validation

Render a checkbox group with validation and error state.

<cdr-form-group label="What's your favorite letter?" :error="modelError" :required="true">
  <cdr-checkbox
    custom-value="A"
    v-model="ex"
    :background="backgroundColor"
    @input="validate"
  >A</cdr-checkbox>
  <cdr-checkbox
    custom-value="B"
    v-model="ex"
    :background="backgroundColor"
    @input="validate"
  >B</cdr-checkbox>
  <cdr-checkbox
    custom-value="C"
    v-model="ex"
    :background="backgroundColor"
    @input="validate"
  >C</cdr-checkbox>
</cdr-form-group>