Checkbox

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add checkbox

Usage#

import { Checkbox } from "@/components/ui/checkbox"

export function Example() {
  return (
    <label htmlFor="terms" className="flex items-center gap-2.5">
      <Checkbox id="terms" defaultChecked />
      Accept terms and conditions
    </label>
  )
}

Anatomy#

import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"

<Checkbox />

<CheckboxGroup allValues={[…]}>
  <Checkbox parent />
  <Checkbox value="…" />
  <CheckboxGroup allValues={[…]}>
    <Checkbox parent />
    <Checkbox value="…" />
  </CheckboxGroup>
</CheckboxGroup>

States#

Checked and indeterminate both fill with the primary (ink) color; indeterminate shows a minus rather than a check. Drive the tri-state by passing checked="indeterminate".

Sizes#

sm (16px) sits inside dense tables; md (20px) is the default for forms. The indicator scales with the box.

With a label#

Checkbox renders only the box; pair it with a <label htmlFor> for an accessible name and a larger hit target. With a description, nudge the box to the first line.

Group#

CheckboxGroup holds one string[] for a whole set. Each member is a plain Checkbox with a value, so there is no per-box state to keep. Use defaultValue, or value with onValueChange to control it. Name the group with aria-labelledby.

Select all#

Pass allValues and add a Checkbox parent. It reads checked when every child is, indeterminate on a partial selection and unchecked when none are, and a click toggles them all. From a partial selection it cycles through all, none, then back to the selection you had, so a stray click never loses it. The same tri-state the DataTable header uses.

Nested#

Put a CheckboxGroup inside another and leave out its value: it shares the outer group’s list and only scopes its own allValues. A tree of permissions stays one flat array, and every parent at every level follows its children with no wiring.

API reference#

FAQ#