Checkbox

A composable tri-state checkbox with separate checked and indeterminate bindings, hidden input form support, and headless indicator rendering.

Accept terms and conditions

Anatomy

The checkbox is assembled from two parts. Checkbox.Root renders the control (and a hidden checkbox input for form integration); Checkbox.Indicator renders the check or mixed mark and only mounts while the checkbox is checked or indeterminate.

<script>
	import { Checkbox } from '@human-kit/ui';
</script>

<Checkbox.Root aria-label="Accept terms">
	<Checkbox.Indicator>
		<CheckIcon />
	</Checkbox.Indicator>
</Checkbox.Root>

States

Every visual state is exposed through data-* attributes on both parts, so all styling — including disabled, readonly, and indeterminate — is done with plain CSS or utility classes.

Indeterminate

The mixed state has its own indeterminate / defaultIndeterminate binding and takes precedence over checked. The first user toggle from the indeterminate state resolves to checked.

Select all rows

Forms

Checkbox.Root keeps a hidden checkbox input in sync: give it a name and value and the pair is submitted when the checkbox is checked. Unchecked and indeterminate states submit no entry.

Usage guidelines

Use checked / defaultChecked for the checked state and indeterminate / defaultIndeterminate for the mixed state.
indeterminate takes precedence over checked. When both are true, the checkbox is exposed as indeterminate.
Use value only for form submission through the hidden native input; it does not represent the visual state.
Wrap the checkbox in a native <label> for the simplest accessible labeling pattern, or point a sibling label[for] at the checkbox id.

Accessibility

Checkbox.Root exposes role="checkbox" with aria-checked="true" | "false" | "mixed".
Press Space to toggle the checkbox.
readonly keeps the checkbox focusable while preventing state changes.

API reference

Root

The checkbox control. Renders a span with role="checkbox" and keeps a hidden checkbox input in sync for form integration.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description

data-checkbox-input Identifies the hidden native input.

data-checkbox-root Identifies the root element.

data-checked Present while the checkbox is checked.

data-disabled Present when the checkbox is disabled.

data-focus-visible Present while focus should be visibly indicated (keyboard modality).

data-focused Present while the checkbox has focus.

data-indeterminate Present while the checkbox is indeterminate (mixed).

data-pressed Present while the checkbox is actively pressed via pointer or keyboard.

data-readonly Present when the checkbox is readonly.

data-required Present when the checkbox is required.

data-unchecked Present while the checkbox is unchecked.

Indicator

The visual check or mixed mark. Only mounted while the checkbox is checked or indeterminate unless `forceMount` is set.