OCheckbox

OCheckbox renders a native checkbox for a standalone boolean or a selected-value group.

Usage

Step by step

1. Import OCheckbox from the ooko-ui/checkbox public subpath.
2. Bind a standalone checkbox to a boolean with v-model.
3. For a group, bind an array and give each checkbox a distinct value with the same name.

Example

The rendered example and its source come from the same Vue single-file component.

Product updates

Engineering news

Interactive playground

Change the value, label, guidance, size, and checkbox states. The preview updates immediately.

Email updates

We only send relevant news.

Size smmdLabel Hint Error Disabled Read-only Required Hide label

Props

Prop	Type	Default	Description
size	OokoFormControlSize	undefined	Controls the choice control's form-control scale.
label	string	undefined	Visible or visually hidden accessible label.
id	string	undefined	Native input identifier. A hydration-safe identifier is generated when omitted.
name	string	undefined	Native form field name and OForm validation key.
hint	string	undefined	Persistent guidance displayed below the choice control.
error	string	undefined	Controlled validation error displayed below the choice control.
validation	OokoValidationBinding	undefined	Validation binding created by useOokoValidation.
hideLabel	boolean	false	Visually hides the label while preserving its accessible name.
required	boolean	false	Marks the native input as required.
disabled	boolean	false	Disables the native input.
readonly	boolean	false	Prevents changes while keeping the input focusable.
modelValue	boolean | readonly Value[]	undefined	Controlled boolean state for a standalone checkbox. Selected values for a checkbox group.
value	Value	undefined	Value submitted by a standalone checked checkbox. Value represented by this checkbox in the group.

Events

Event	Payload	Description
update:modelValue	boolean | Value[]	Emits the next boolean state or next selected group values after a native change.

Slots

Slot	Props	Description
default	none	Provides the checkbox label content.

Related types

Type	Definition
OCheckboxModelValue	type OCheckboxModelValue<Value extends OCheckboxValue = OCheckboxValue> = boolean | readonly Value[];
OCheckboxValue	type OCheckboxValue = number | string;
OokoFormControlSize	type OokoFormControlSize = "sm" | "md";

CSS custom properties

Custom property	Default	Description
--o-checkbox-gap	var(--o-space-2)	Sets the space between the checkbox indicator and its label.
--o-checkbox-indicator-size	var(--o-space-5)	Sets the checkbox indicator size.
--o-checkbox-indicator-border-radius	var(--o-radius-control-compact)	Sets the checkbox indicator corner radius.
--o-checkbox-focus-width	0.1875rem	Sets the focus outline width.
--o-checkbox-focus-style	solid	Sets the focus outline style.
--o-checkbox-focus-offset	0.125rem	Sets the distance between the indicator and focus outline.
--o-checkbox-disabled-opacity	0.5	Sets the opacity of a disabled checkbox.

Override example

:root {
  --o-checkbox-gap: var(--o-space-3);
}

Accessibility

The native checkbox and its control row form one label, so clicking the indicator or text toggles it. Space toggles it, focus is visibly indicated, and disabled behavior uses the native attribute. readonly remains focusable and exposes aria-readonly; it does not change value. Hints and feedback are referenced by aria-describedby, while errors are announced politely. Forced-colors and reduced-motion preferences are respected.

Behavior and edge cases

With a boolean v-model, the component emits the next boolean state. With an array v-model, value is required and the component immutably adds or removes that value like a native checkbox group. Native attributes and listeners are forwarded to the input; consumer classes and styles apply to the component root. size accepts sm and md, and may be configured through app defaults. Setting the native indeterminate property on the input, for instance with a forwarded :indeterminate binding, displays a dash instead of the check mark.