CSC Design System v4.0.1
VueFlavour Vue React Angular TypeScript
Flavour Vue React Angular TypeScript
PrimaryCSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
CSC UI Colors Primary Secondary AccentCustom Colors Red Orange Green Blue Purple Pink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<c-checkbox>

A form control for a single on/off choice: a native checkbox with a label, an optional hint, and validation messaging.

Usage

Bind the state with a plain v-model: value is true-value while the checkbox is on and false-value while it is off (true and false unless you map them onto custom values). checked is the same state as a boolean — setting it sets value, and a checked attribute sets the initial state when no value is bound.

<c-checkbox v-model="accepted" label="I accept the terms" />

Set indeterminate for the mixed "some but not all" state of a parent checkbox. As on a native checkbox, a click or Space clears it and toggles the state. A binding writes indeterminate only when its value changes, so it doesn't bring the mixed state back after a click that leaves the options partly checked (some rows disabled, say). Set the element's property in your change handler:

<script setup>
const onSelectAll = (event) => {
  selectAll(event.detail);
  // The binding writes again only when `partly` changes.
  event.currentTarget.indeterminate = partly.value;
};
</script>

<template>
  <c-checkbox
    :value="all"
    :indeterminate="partly"
    label="All projects"
    @change="onSelectAll"
  />
</template>

Set hint for a persistent helper line below the control; while invalid is set, error-message replaces it. hide-message removes the message area entirely.

When to use

  • A single independent yes/no choice (consent, feature toggle in a form).
  • A list where several options can be selected at once.

When not to use

  • Choosing exactly one of several options — use c-radio-group.
  • Switching a setting that takes effect immediately — use c-switch.

Accessibility

The checkbox is a native input named by its label. Without a visible label, set aria-label on the element: it names the input, as the other ARIA attributes on the element describe it.

Customization

Restyle via CSS parts from your own stylesheet. The indicator part is the checkbox box and mark is the check glyph inside it. The indicator's border, its checked fill and its keyboard focus ring all draw with currentColor, so one color recolours the three together; the host exposes the checked and indeterminate custom states, so the box is also stylable per state:

/* Border, checked fill and focus ring follow `color`. */
c-checkbox::part(indicator) {
  color: var(--my-green);
}

/* The mark draws with currentColor too — recolour it via `color`. */
c-checkbox:state(checked)::part(mark) {
  color: black;
}

/* Finer control still works per property and per state (the focus ring
   keeps following `color`, not these). */
c-checkbox:not(:state(checked))::part(indicator) {
  border-color: gray;
}

For app-wide recolouring prefer the design tokens (--c-primary seed) over per-component rules.

Examples

Basic
Vue React Angular TypeScript
<template>
  <div class="example-row">
    <c-checkbox v-model="subscribed" hint="You can unsubscribe at any time">
      Subscribe to the newsletter
    </c-checkbox>

    <p>Value: {{ subscribed }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const subscribed = ref(false);
</script>
States
Vue React Angular TypeScript
<template>
  <div class="example-row">
    <c-checkbox hide-message>Unchecked</c-checkbox>

    <c-checkbox checked hide-message>Checked</c-checkbox>

    <c-checkbox hide-message indeterminate>Indeterminate</c-checkbox>

    <c-checkbox disabled hide-message>Disabled</c-checkbox>

    <c-checkbox checked disabled hide-message>Checked and disabled</c-checkbox>
  </div>
</template>

API reference

<c-checkbox>

A form control for a single on/off choice: a native checkbox with a label, an optional hint, and validation messaging.

Properties

PropertyAttributeTypeDefaultDescription
checkedcheckedbooleanfalse Whether the checkbox is on: the boolean view of `value`. Setting it sets `value` to `trueValue` or `falseValue`; reading it reports whether `value` equals `trueValue`. As an attribute it sets the initial state when no `value` is bound.
disableddisabledbooleanfalse Disable the checkbox
errorMessageerror-messagestring'' Error message shown in place of the hint while the checkbox is invalid
falseValuefalse-valueboolean | number | stringfalse The value when the checkbox is unchecked
hideMessagehide-messageboolean— Hide the message line — the hint and error messages under the field — and the room it keeps.
hinthintstring'' Hint text for the checkbox
indeterminateindeterminatebooleanfalse Show the mixed state, a bar in place of the check, for a parent checkbox whose options are partly checked. It wins over `checked`; a click or Space clears it and toggles the state, as on a native checkbox
invalidinvalidbooleanfalse Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`.
labellabelstring'' Label of the checkbox, shown beside the box. Falls back to the default slot content when not set.
namenamestring'' The name the checkbox submits under in a native `<form>` while it is checked: its `true-value`, or `on` when that is `true`
requiredrequiredbooleanfalse Set as required — shows the required marker on the label
trueValuetrue-valueboolean | number | stringtrue The value when the checkbox is checked
valuevaluestring | number | boolean— The checkbox's state: `trueValue` while it is on, `falseValue` while it is off. A bound value wins over a `checked` attribute; any other value, `''` included, reads as off.
hideDetails deprecated hide-detailsbooleanfalse Deprecated. Use `hide-message`. Hide the hint and error messages

Events

EventDetailDescription
changeboolean | number | stringFired when the user toggles the checkbox, carrying the new value — `trueValue` when checked, `falseValue` when unchecked.
inputvoidNative bubbling input event fired on toggle so a plain Vue `v-model` stays in sync. No detail.
update:valueboolean | number | stringFired alongside `change` with the same detail — the `v-model` contract.

Methods

MethodSignatureDescription
focus(options?: FocusOptions): voidFocus its checkbox, as `focus()` does on a native control: the element renders no box of its own to take it.

Slots

SlotDescription
defaultThe visible label of the checkbox (fallback when the `label` prop is not set)

CSS parts

Style from outside with c-checkbox::part(name) — parts are the library's only styling customization API.

PartDescription
rootThe outer wrapper containing the checkbox, label and message
labelThe label text or slotted label content beside the box
indicatorThe checkbox box itself — the bordered square that fills when checked; border, fill and the keyboard focus ring (its `::before`) all draw with `currentColor`, so `color` recolours them together
markThe SVG check / indeterminate glyph revealed inside the indicator; draws with `currentColor`, so `color` recolours it
messageThe hint / error message area below the checkbox (always reserved unless `hide-message`)

Custom states

Select on the host's live state with c-checkbox:state(name) — combine with ::part() for per-state styling, e.g. c-checkbox:state(checked)::part(indicator) targets the indicator only while checked.

StateDescription
checkedPresent while the checkbox is checked
indeterminatePresent while the checkbox is in the indeterminate state