Checkbox

A binary on/off control. Like the other form controls, it's deliberately label-less — pair it with a Label (matching the label's for to the checkbox's id) so clicking the text toggles the box and screen readers announce it correctly.

Bind its state with v-model. It works standalone, or inside a Field, where it picks up the field's id, disabled, required, and error state automatically.

Usage

Pair the checkbox with a Label via id/for.

BasicA checkbox with an associated label.

States

Checked, unchecked, and disabled. Bind each with v-model.

StatesChecked, unchecked, disabled.

Invalid

Set invalid to show the error styling — useful for required checkboxes (like accepting terms) that haven't been checked. Inside a Field, this is driven by the field's error state automatically.

InvalidThe error state.

Visual mode

Set visual to render just the box — no <input>, no interactivity. Use this when the checkbox sits inside another interactive element (a menu row, a selectable option) where a nested real input would be invalid HTML. Drive it with :model-value (it doesn't emit changes itself; the parent owns the state).

VisualBox-only, for use inside other controls.

Props

Prop	Type	Default	Description
modelValue	boolean	false	The checked state. Use with v-model.
id	string	—	The control's id, for pairing with a Label's for. Provided automatically inside a Field.
disabled	boolean	false	Disables the checkbox. Inherited from a surrounding Field if set there.
required	boolean	false	Marks the checkbox required. Inherited from a Field.
invalid	boolean	false	Shows the error styling. Inherited from a Field's error state.
visual	boolean	false	Renders box-only (no input), for embedding inside another interactive element. Drive with :model-value.
class	string	—	Classes merged onto the box.

Accessibility

• Renders a real <input type="checkbox"> (visually hidden), so keyboard and screen-reader behavior work natively — it's focusable, toggles with Space, and participates in forms.
• Pair it with a Label (for/id) so it has an accessible name and a larger click target. Without a label, give it context another way.
• invalid, required, and disabled set the matching aria-* attributes, so assistive tech is informed of the control's state.
• visual mode is presentational only — the real checkbox controlling state must live on the surrounding interactive element.

TIP

Inside a Field, the checkbox inherits id, disabled, required, and the invalid state from the field context — you don't set them per-control. See Field for the full pattern.