Appearance
Checkbox
On/off choice that takes effect on submit, or one item in a list of independent choices. Use switch for a setting that applies at once, and radio-group when exactly one of several options must be chosen.
Usage
vue
<Checkbox v-model="terms" name="terms" required>I accept the terms</Checkbox>Props
| Prop | Type | Default | Notes |
|---|---|---|---|
modelValue | false | true | 'indeterminate' | false | v-model; 'indeterminate' shows a dash |
size | 'md' | 'sm' | 'lg' | 'md' | Box and text size |
disabled | boolean | false | |
name | string | none | Form field name; without it the box is not part of the form |
value | string | 'on' | Submitted while checked |
class | string | none | Applied to the wrapping label |
id, required (it needs name) and aria-* attributes go to the checkbox control, not the wrapper. With a name, the checkbox submits value (default on) in its form while checked; indeterminate counts as unchecked, for submit and for required.
Slots
| Slot | Content |
|---|---|
default | The label text; a click on it toggles the box |
Events
| Event | Payload | When |
|---|---|---|
update:modelValue | boolean | 'indeterminate' | On toggle: always true or false; an indeterminate box becomes true |
Tokens
None of its own. The box uses border-control, and primary with primary-foreground when checked or indeterminate; corners are radius-sm.
States
unchecked, checked, indeterminate; hover, focus-visible, disabled (unchecked and checked); three sizes; label that wraps; no visible label (aria-label).
Keyboard
| Key | Action |
|---|---|
Space | Toggle |
Enter does not toggle, as for a native checkbox.
Accessibility
- Renders
role="checkbox"witharia-checkedtrue,falseormixed. - The default slot sits inside a
labelaround the control, so it names the checkbox. Without a slot, passaria-label. - The check and dash icons are
aria-hidden. - A disabled checkbox dims its box; its label text turns
muted-foregroundrather than translucent, so it still meets contrast.
Do
vue
<Checkbox v-model="all" :model-value="some ? 'indeterminate' : all">Select all</Checkbox>Do not
vue
<!-- A checkbox that saves on click: use a switch for instant settings. -->
<Checkbox v-model="notifications" @update:model-value="save">Email me</Checkbox>