Checkbox

Boolean toggle control with optional group management and three color variants.

Import

import { Checkbox, CheckboxView, CheckboxGroupManager, createCheckboxGroupManager } from '@atom-forge/ui';

Components

Component	Description
`Checkbox`	Full stateful checkbox — handles value binding, group registration, and click logic.
`CheckboxView`	Stateless render-only component. No internal logic; you control `status` and `onclick`.
`CheckboxGroupManager`	Context provider component — wrap checkboxes to enable group functionality.
`createCheckboxGroupManager()`	Creates a group manager in the current component's context without a wrapper element.

Checkbox Props

Prop	Type	Group	Default	Description
`value`	`boolean`	Value	`false`	Bindable checked state. Mutually exclusive with `checked`.
`checked`	`boolean`	Value	—	Alternative bindable for checked state. Mutually exclusive with `value`.
`onchange`	`(checked: boolean) => void`	—	—	Fired whenever the checked state changes.
`label`	`string`	—	`''`	Text displayed next to the checkbox.
`disabled`	`boolean`	—	`false`	Prevents interaction; applies faded appearance.
`primary`	`boolean`	Color	—	Checked state uses the primary color.
`accent`	`boolean`	Color	—	Checked state uses the accent color.
`compact`	`boolean`	Size	—	Medium size (16px box, `text-sm` label).
`small`	`boolean`	Size	—	Small size (14px box, `text-xs` label).
`group`	`string`	—	—	Group name. Requires a `CheckboxGroupManager` in context.
`master`	`boolean`	—	`false`	When `group` is set — toggles all group members; shows indeterminate when only some are checked.

CheckboxView Props

Prop	Type	Group	Default	Description
`status`	`'checked' \| 'some' \| 'unchecked'`	—	`'unchecked'`	Visual state. `'some'` renders a minus icon (indeterminate).
`label`	`string`	—	`''`	Text displayed next to the checkbox.
`disabled`	`boolean`	—	`false`	Faded, non-interactive appearance.
`primary`	`boolean`	Color	—	Active state uses the primary color.
`accent`	`boolean`	Color	—	Active state uses the accent color.
`compact`	`boolean`	Size	—	Medium size.
`small`	`boolean`	Size	—	Small size.
`onclick`	`(event: MouseEvent) => void`	—	—	Click handler — state management is entirely your responsibility.

Color Variants

Three variants for the checked/active state. At most one applies; they are mutually exclusive (XOR).

Variant	Box color	Hover
(default)	`bg-control-v border-frame text-control-contrast`	`hover:bg-secondary`
`primary`	`bg-primary border-primary text-primary-contrast`	`hover:bg-primary/10`
`accent`	`bg-accent border-accent text-accent-contrast`	`hover:bg-accent/10`

Unchecked state is always bg-control border-frame regardless of variant.

<Checkbox label="Default"  value={true} />
<Checkbox label="Primary"  value={true} primary />
<Checkbox label="Accent"   value={true} accent />

<!-- checked as alternative binding -->
<Checkbox label="Default" bind:checked={isOn} />

<!-- with onchange -->
<Checkbox label="Notify me" bind:value={enabled} onchange={(v) => console.log('changed:', v)} />

Sizes

Three sizes, mutually exclusive.

Size	Box	Label font
(normal)	`w-5 h-5` (20px)	inherited
`compact`	`w-4 h-4` (16px)	`text-sm`
`small`	`w-3.5 h-3.5` (14px)	`text-xs`

Note: Do not use text-base for normal label size — since --color-base is a defined CSS variable, Tailwind v4 interprets it as a color class, not a font-size class.

Group Management

Grouped checkboxes share state through a CheckboxGroupManager. All checkboxes in the same group must share the same group string and have access to the same manager context.

Option 1 — Wrapper component

<CheckboxGroupManager>
  <Checkbox group="items" label="Select All" master />
  <hr />
  <Checkbox group="items" label="Option A" value={false} />
  <Checkbox group="items" label="Option B" value={true} />
  <Checkbox group="items" label="Option C" value={true} />
</CheckboxGroupManager>

Option 2 — Programmatic (scattered layout)

Call createCheckboxGroupManager() in the script block of the nearest common ancestor. The checkboxes do not need to be direct children.

<script lang="ts">
  import { createCheckboxGroupManager, Checkbox } from '@atom-forge/ui';
  createCheckboxGroupManager();
</script>

<!-- checkboxes can be anywhere in the subtree -->
<Checkbox group="items" label="Select All" master />
<Checkbox group="items" label="Option A" value={false} />

Master checkbox behavior

Group state	Master displays
All checked	checked
All unchecked	unchecked
Mixed	indeterminate (`'some'`)

Clicking a master when mixed or unchecked → checks all. Clicking when all checked → unchecks all.

Architecture

Checkbox
  └── CheckboxView          (render only)

CheckboxGroupManager        (context provider component)
  └── sets CheckboxGroupManager instance in context

createCheckboxGroupManager() (function)
  └── same as above, without a wrapper element

CheckboxGroupManager (class)
  └── groups: Map<string, NamedCheckboxGroupManager>

NamedCheckboxGroupManager (class)
  ├── masters: Map<id, { changeState }>
  ├── values:  Map<id, { value, changeState }>
  ├── registerMaster / unregisterMaster
  ├── registerValue  / unregisterValue
  ├── set(id, value)         — toggle individual item
  ├── toggleAll()            — master click handler
  └── updateMasterState()    — recalculates master status after any change

Checkboxes register themselves in onMount and unregister on destroy (cleanup returned from onMount). The group prop is frozen with untrack() at init — changing the group name at runtime is not supported.

Accessibility

CheckboxView renders a <div role="checkbox"> with:

aria-checked — true / false / 'mixed' (for indeterminate)
aria-disabled — set when disabled
tabindex="0" — keyboard focusable (omitted when disabled)
onkeydown — Space and Enter activate the checkbox

When to use

Use for independent boolean choices, including select-all groups with an indeterminate master.

Alternatives

Use Radio for mutually exclusive choices and Switch for an on/off setting. CheckboxView is appropriate only when the caller owns all state.

Setup and behavior

Choose one binding (value or checked); the alias is selected at initialization, so initialize checked to a boolean when using it. onchange is called by the internal state-setting path, including group-manager updates, not as an observer of arbitrary external assignments. Standalone bindings reflect external changes; grouped visual state is manager-owned and has no effect syncing later external assignments into that manager. Group registration happens on mount. Master checkboxes display aggregate status but do not update their boolean binding or fire onchange for that aggregate. Group-wide operations do not exclude disabled members; disabled prevents local interaction, not manager-driven changes.

Forms