/ checkbox

Checkbox

@kumiki/components/checkbox

Compound <Checkbox.Root> for tri-state form checkboxes (role=checkbox, aria-checked).

Pure state machines (FSMs). No DOM. Run in server, Vitest, Worker. Reach for these when you only want the behavior.

State machine

Tri-state (unchecked / checked / mixed) checkbox.

Source package: @kumiki/machines/checkbox
Initial state: unchecked
Top-level states: unchecked,checked,mixed,disabled

toJSON() snapshot Open in stately.ai/viz

Install

pnpm add @kumiki/machines

Pure-TS tri-state

import { createCheckboxMachine } from '@kumiki/machines/checkbox';

const m = createCheckboxMachine({ initial: 'mixed' });
m.send({ type: 'TOGGLE' });          // mixed → checked (APG tristate)
console.log(m.context.value);        // 'checked'
m.send({ type: 'SET', value: 'mixed' });
console.log(m.state);                // 'mixed'

Svelte 5 {@attach} factories. Glue ARIA / keyboard / focus onto any DOM node you choose. **Best when you want full control over markup and styling.**

Install

pnpm add @kumiki/headless

Drive your own DOM

<script lang="ts">
  import { createCheckbox } from '@kumiki/headless/checkbox';
  const c = createCheckbox({ initial: 'unchecked' });
</script>

<button {@attach c.root}>
  {c.value === 'checked' ? '✓' : c.value === 'mixed' ? '−' : ''}
</button>

Compound components (<Root> / <Trigger> / …). Markup is fixed; styling is not. Same trade-off as a typical headless UI library.

Live preview

Install

pnpm add @kumiki/components/checkbox

Basic — uncontrolled

<script lang="ts">
  import { Checkbox } from '@kumiki/components/checkbox';
  let value = $state<'unchecked' | 'checked' | 'mixed'>('unchecked');
</script>

<Checkbox.Root bind:value>
  {value === 'checked' ? '✓' : value === 'mixed' ? '−' : ''}
</Checkbox.Root>

Tri-state parent of a group

<script lang="ts">
  import { Checkbox } from '@kumiki/components/checkbox';
  let items = $state([
    { id: 1, checked: false },
    { id: 2, checked: true },
    { id: 3, checked: false },
  ]);
  // mixed when some-but-not-all children checked
  const parentValue = $derived(
    items.every((i) => i.checked)
      ? 'checked'
      : items.some((i) => i.checked)
        ? 'mixed'
        : 'unchecked',
  );
</script>

<Checkbox.Root
  value={parentValue}
  onCheckedChange={(v) => items.forEach((i) => (i.checked = v === 'checked'))}>
  Select all
</Checkbox.Root>

Styled, copy-paste presets (preview). Run pnpm kumiki add to drop the source into your project, then edit freely.

Live preview

Live preview…

Install

pnpm add @kumiki/atelier

Tri-state checkbox

<script lang="ts">
  import { Tailwind as Checkbox } from '@kumiki/atelier/checkbox';
  import type { CheckboxValue } from '@kumiki/components/checkbox';

  let agreed = $state<CheckboxValue>('unchecked');
</script>

<label>
  <Checkbox.Root id="agree" bind:value={agreed} />
  <span>I agree to the terms</span>
</label>

Key	Effect
`Space`	Toggles checked / unchecked.
`Tab`	Move focus.

This component, layer by layer

Keyboard

Test discipline