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
<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.
<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| Prop | Type | Default |
|---|---|---|
checked bind | boolean Whether it is checked. | false |
indeterminate bind | boolean 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 bind | HTMLButtonElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="checkbox" | Always present. |
data-state | "checked", "unchecked" or "indeterminate". |
data-disabled | Present when disabled. |