<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
<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>
<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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | 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. |
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 |
hideMessage | hide-message | boolean | — | Hide the message line — the hint and error messages under the field — and the room it keeps. |
hint | hint | string | '' | Hint text for the checkbox |
indeterminate | indeterminate | boolean | false | 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 |
invalid | invalid | boolean | false | Show the control as invalid: its `error-message`, when set, replaces the hint, and the control is marked `aria-invalid`. |
label | label | string | '' | Label of the checkbox, shown beside the box. Falls back to the default slot content when not set. |
name | name | string | '' | The name the checkbox submits under in a native `<form>` while it is checked: its `true-value`, or `on` when that is `true` |
required | required | boolean | false | Set as required — shows the required marker on the label |
trueValue | true-value | boolean | number | string | true | The value when the checkbox is checked |
value | value | string | 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-details | boolean | false | Deprecated. Use `hide-message`. Hide the hint and error messages |
Events
| Event | Detail | Description |
|---|---|---|
change | boolean | number | string | Fired when the user toggles the checkbox, carrying the new value — `trueValue` when checked, `falseValue` when unchecked. |
input | void | Native bubbling input event fired on toggle so a plain Vue `v-model` stays in sync. No detail. |
update:value | boolean | number | string | Fired alongside `change` with the same detail — the `v-model` contract. |
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its checkbox, as `focus()` does on a native control: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
default | The 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.
| Part | Description |
|---|---|
root | The outer wrapper containing the checkbox, label and message |
label | The label text or slotted label content beside the box |
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 |
message | The 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.
| State | Description |
|---|---|
checked | Present while the checkbox is checked |
indeterminate | Present while the checkbox is in the indeterminate state |