Checkbox
A checkbox with an optional indeterminate state. Inside a Field
it takes its id (the field’s controlId), disabled, required, state, and
aria-describedby from there.
An error state sets aria-invalid and colors the default icon. See
Field for pairing it with a Hint.
Built on bits-ui Checkbox.
<Field class="flex items-center gap-2"> <Checkbox bind:checked /> <Label>Accept the terms</Label></Field><Checkbox
checked={false}
indeterminate={false}
disabled={false}
/>- Three states, unchecked, checked, and indeterminate, driven by two bindable props:
checkedandindeterminate. - Keyboard and screen reader behavior from the WAI-ARIA checkbox pattern, via bits-ui.
- Submits with the form through a hidden
<input>when given aname. - The icon is a snippet, so size and color are yours to change.
Two-way binding
Section titled “Two-way binding”bind:checked keeps your state and the box in sync. State & binding covers both modes.
checked: false
Code
<script lang="ts"> import { Checkbox, Field, Label } from "@viamrobotics/prime-ui";
let checked = $state(false);</script>
<div class="not-content"> <Field class="flex items-center gap-2"> <Checkbox bind:checked /> <Label>Email me about updates</Label> </Field>
<p class="mt-3 text-sm text-subtle-2">checked: <code>{checked}</code></p></div>Fully controlled
Section titled “Fully controlled”Give bind:checked a getter and a setter. Here the box can be turned on but never off. State & binding has the rule.
accepted: false
Code
<script lang="ts"> import { Checkbox, Field, Label } from "@viamrobotics/prime-ui";
let accepted = $state(false);</script>
<div class="not-content"> <Field class="flex items-center gap-2"> <Checkbox bind:checked={ () => accepted, (next) => { if (next) accepted = true; } } /> <Label>Accept the terms (cannot be undone)</Label> </Field>
<p class="mt-3 text-sm text-subtle-2">accepted: <code>{accepted}</code></p></div>Custom icon
Section titled “Custom icon”Pass children to replace the icon. The snippet receives the current checked and indeterminate, so it can pick a glyph, a size, and a color per state.
Code
<script lang="ts"> import { mdiCheckCircle, mdiCircleMedium } from "@mdi/js"; import { Checkbox, Field, Icon, Label } from "@viamrobotics/prime-ui";
let checked = $state(true);</script>
<Field class="not-content flex items-center gap-2"> <Checkbox bind:checked> {#snippet children({ checked })} <Icon icon={checked ? mdiCheckCircle : mdiCircleMedium} size="xl" class={checked ? "text-info-dark" : "text-subtle-2"} /> {/snippet} </Checkbox> <Label>Larger, round, and blue when checked</Label></Field>In a field
Section titled “In a field”Inside a Field the checkbox takes controlId, disabled, required, state, and aria-describedby from the field, and the label and hint wire themselves to it. name and value make it part of the enclosing form. A state of error sets aria-invalid="true" and turns the default icon red. Pass state directly to override the field’s.
Required before you can continue.
Code
<script lang="ts"> import { Checkbox, Field, Hint, Label } from "@viamrobotics/prime-ui";
let checked = $state(false);</script>
<Field class="not-content grid grid-cols-[auto_1fr] items-center gap-x-2" required> <Checkbox bind:checked name="terms" value="accepted" /> <Label>Accept the terms</Label> <Hint class="col-start-2">Required before you can continue.</Hint></Field>States
Section titled “States”Styling
Section titled “Styling”class lands on the root button, which is the whole component. bits-ui sets these data attributes on it, so Tailwind variants like data-[state=checked]:bg-light work without a wrapper.
| Attribute | Value |
|---|---|
data-state |
checked, unchecked, or indeterminate |
data-disabled |
present when disabled |
aria-invalid |
true when state is error |
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| Space | Toggles the checkbox. |
| Enter | Swallowed, so pressing it on the box never submits the form. |
| Prop | Type | Default | Description |
|---|---|---|---|
bind:checked | boolean | false | Checked state. |
bind:indeterminate | boolean | false | Indeterminate ("mixed") state. Wins over checked visually. |
value | string | Value submitted when checked. | |
required | boolean | Require the box to be checked for form submission. Defaults to the enclosing field's required. | |
state | FieldState | Contextual state. Defaults to the enclosing field's state. | |
form | string | Id of the form to submit with. bits-ui accepts a string only, so null is dropped. | |
children | Snippet<[{ checked: boolean; indeterminate: boolean }]> | Custom content instead of the default icon. Receives { checked, indeterminate }. |
Plus everything in Omit<HTMLButtonAttributes, 'children' | 'form' | 'value'>, spread onto the element.