`<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 (or the checked prop); true-value / false-value map the checked state onto custom values. Set indeterminate for the mixed "some but not all" state of a parent checkbox.

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

Set hint for a persistent helper line below the control; while valid is false, error-message replaces it. hide-details 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.

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-details>Unchecked</c-checkbox>

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

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

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

    <c-checkbox checked disabled hide-details>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

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	If `true`, the checkbox is selected.
`disabled`	`disabled`	`boolean`	`false`	Disable the checkbox
`errorMessage`	`error-message`	`string`	`''`	Error message shown in place of the hint while the checkbox is invalid
`falseValue`	`false-value`	`boolean \| number \| string`	`false`	The value when the checkbox is unchecked
`hideDetails`	`hide-details`	`boolean`	`false`	Hide the hint and error messages
`hint`	`hint`	`string`	`''`	Hint text for the input
`hostId`	`host-id`	`string`	`''`	Id of the element
`hostName`	`host-name`	`string`	`''`	Name of the input - Only used when the checkbox participates in a native `<form>`
`indeterminate`	`indeterminate`	`boolean`	`false`	Indeterminate state
`label`	`label`	`string`	`''`	Element label
`required`	`required`	`boolean`	`false`	Set as required
`trueValue`	`true-value`	`boolean \| number \| string`	`true`	The value when the checkbox is checked
`valid`	`valid`	`boolean`	`true`	Set the validity of the input
`value`	`value`	`boolean \| number \| string`	`false`	The input value - Only used when the checkbox participates in a native `<form>`

Events

Event	Detail	Description
`change`	`void`	Standard bubbling DOM change event, re-dispatched from the host when the checkbox is toggled (the inner input's change does not cross the shadow boundary). No detail; read the new value from the host's `value` property.
`changeValue`	`boolean \| number \| string`	Fired when the checkbox is toggled, carrying the new value — `trueValue` when checked, `falseValue` when unchecked. Also dispatched as `change-value` — bind that name in Vue templates.
`input`	`void`	Native bubbling input event fired on toggle so a plain Vue `v-model` works without the `v-control` directive. No detail.
`update:value`	`boolean \| number \| string`	v-model contract event fired on toggle, carrying the new value — `trueValue` when checked, `falseValue` when unchecked.

Slots

Slot	Description
`default`	Default slot for the label

CSS parts

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

Part	Description
`root`	The outer wrapper containing the checkbox, label and message
`label`	The `<label>` element wrapping the indicator and the label content
`indicator`	The 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
`mark`	The SVG check / indeterminate glyph revealed inside the indicator; draws with `currentColor`, so `color` recolours it
`content`	Wrapper around the label text or slotted label content
`message`	The hint / error message area below the checkbox (always reserved unless `hide-details`)

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).

State	Description
`checked`	Present while the checkbox is checked
`indeterminate`	Present while the checkbox is in the indeterminate state