Skip to content
Statix Design System

Forms

Checkbox

A 20px box for options people can turn on or off independently. It fills with the primary blue when checked.

import { Checkbox } from '@statix/ui/checkbox';

Playground

Controls
<Checkbox id="invoices" />
<Label for="invoices">Send invoices by email</Label>

Examples

With a label

Bind checked and pair it with a Label.

<script lang="ts">
	import { Checkbox } from '@statix/ui/checkbox';
	import { Label } from '@statix/ui/label';

	let checked = $state(true);
</script>

<div class="flex items-center gap-3">
	<Checkbox id="cb-invoices" bind:checked />
	<Label for="cb-invoices" class="font-normal">Send invoices as PDF by email</Label>
</div>

With a description

Use a horizontal Field with FieldContent when the option needs explaining.

We copy yoga-berger.de, run the updates there and only then update the live site.

<script lang="ts">
	import { Checkbox } from '@statix/ui/checkbox';
	import * as Field from '@statix/ui/field';
</script>

<Field.Field orientation="horizontal" class="max-w-md">
	<Checkbox id="cb-staging" />
	<Field.Content>
		<Field.Label for="cb-staging">Test updates on a staging copy first</Field.Label>
		<Field.Description>
			We copy yoga-berger.de, run the updates there and only then update the live site.
		</Field.Description>
	</Field.Content>
</Field.Field>

Group

A FieldSet with a legend names the group. Each checkbox stays independent.

Email me when
<script lang="ts">
	import { Checkbox } from '@statix/ui/checkbox';
	import * as Field from '@statix/ui/field';

	const options = [
		{ id: 'downtime', label: 'Website is down', checked: true },
		{ id: 'backup', label: 'A backup failed', checked: true },
		{ id: 'updates', label: 'Updates were installed', checked: false },
		{ id: 'invoice', label: 'A new invoice is ready', checked: false }
	];
</script>

<Field.Set class="w-full max-w-sm">
	<Field.Legend variant="label">Email me when</Field.Legend>
	<Field.Group data-slot="checkbox-group">
		{#each options as option (option.id)}
			<Field.Field orientation="horizontal">
				<Checkbox id="notify-{option.id}" checked={option.checked} />
				<Field.Label for="notify-{option.id}" class="font-normal">{option.label}</Field.Label>
			</Field.Field>
		{/each}
	</Field.Group>
</Field.Set>

Indeterminate

A "select all" checkbox shows a dash when only some items are checked.

<script lang="ts">
	import { Checkbox } from '@statix/ui/checkbox';
	import { Label } from '@statix/ui/label';

	let invoices = $state([
		{ id: 'RE-2027-031', checked: true },
		{ id: 'RE-2027-022', checked: false },
		{ id: 'RE-2027-014', checked: true }
	]);

	const count = $derived(invoices.filter((i) => i.checked).length);
	const all = $derived(count === invoices.length);
	const some = $derived(count > 0 && !all);
</script>

<div class="flex w-full max-w-xs flex-col gap-3">
	<div class="flex items-center gap-3 border-b border-border pb-3">
		<Checkbox
			id="inv-all"
			checked={all}
			indeterminate={some}
			onCheckedChange={(value) => invoices.forEach((i) => (i.checked = value))}
		/>
		<Label for="inv-all">Download {count} of {invoices.length} invoices</Label>
	</div>
	{#each invoices as invoice (invoice.id)}
		<div class="flex items-center gap-3">
			<Checkbox id="inv-{invoice.id}" bind:checked={invoice.checked} />
			<Label for="inv-{invoice.id}" class="font-normal tabular-nums">{invoice.id}</Label>
		</div>
	{/each}
</div>

Invalid and disabled

aria-invalid turns the border red. disabled fades the box to 50%.

Accept the contract to continue.

<script lang="ts">
	import { Checkbox } from '@statix/ui/checkbox';
	import { Label } from '@statix/ui/label';
</script>

<div class="flex flex-col gap-4">
	<div class="flex items-center gap-3">
		<Checkbox id="st-terms" aria-invalid="true" aria-describedby="st-terms-error" />
		<Label for="st-terms" class="font-normal">I accept the hosting contract</Label>
	</div>
	<p id="st-terms-error" class="-mt-2 pl-8 text-small text-destructive">
		Accept the contract to continue.
	</p>
	<div class="flex items-center gap-3">
		<Checkbox id="st-ssl" checked disabled />
		<Label for="st-ssl" class="font-normal">SSL certificate (always included)</Label>
	</div>
</div>

Guidelines

Do

  • Use a checkbox for options that take effect when the form is saved.
  • Write labels as positive statements: "Send invoices by email", not "Don't send invoices by post".

Don't

  • Don't use a checkbox for a setting that applies right away. Use Switch.
  • Don't use checkboxes for mutually exclusive options. Use RadioGroup.

Accessibility

  • Renders a <button role="checkbox"> with aria-checked, including "mixed" for the indeterminate state.
  • Space toggles it. A hidden native input keeps form submission working when name is set.
  • Label it with <Label for> pointing at its id.
  • The hit area extends 12px left and right and 8px up and down beyond the box.

API reference

Checkbox

renders <button role="checkbox"> and accepts its attributes
PropTypeDefault
checked bindboolean

Whether it is checked.

false
indeterminate bindboolean

Shows a dash. Cleared when the user toggles it.

false
onCheckedChange (checked: boolean) => void

Called when the user toggles it.

–
disabled boolean

Disables the checkbox.

false
required boolean

Marks it as required in a form.

false
name string

Name of the hidden input for form submission.

–
value string

Value submitted when checked.

'on'
ref bindHTMLButtonElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="checkbox"Always present.
data-state"checked", "unchecked" or "indeterminate".
data-disabledPresent when disabled.