Skip to content

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: checked and indeterminate.
  • Keyboard and screen reader behavior from the WAI-ARIA checkbox pattern, via bits-ui.
  • Submits with the form through a hidden <input> when given a name.
  • The icon is a snippet, so size and color are yours to change.

bind:checked keeps your state and the box in sync. State & binding covers both modes.

checked: false

Code
TwoWay.svelte
<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>

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
Controlled.svelte
<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>

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
CustomIcon.svelte
<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>

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
InField.svelte
<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>
unchecked checked indeterminate disabled disabled + checked

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
KeyAction
SpaceToggles the checkbox.
EnterSwallowed, so pressing it on the box never submits the form.
PropTypeDefaultDescription
bind:checkedbooleanfalseChecked state.
bind:indeterminatebooleanfalseIndeterminate ("mixed") state. Wins over checked visually.
valuestringValue submitted when checked.
requiredbooleanRequire the box to be checked for form submission. Defaults to the enclosing field's required.
stateFieldStateContextual state. Defaults to the enclosing field's state.
formstringId of the form to submit with. bits-ui accepts a string only, so null is dropped.
childrenSnippet<[{ 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.