Components / Choice

Checkbox

A checkbox with indeterminate state and an optional hint. Extra attributes go to the native input, which overlays the visible box so test tools can check() it directly.

@ruckc/truss-ui Choice

Import

import { Checkbox } from '@ruckc/truss-ui';

Playground

Recipe: reacting to a toggle

oncheckedchange receives the new state (boolean) when the user toggles the checkbox. It does not fire when checked is changed from code. onchange is unchanged: it is still the native change event, for callers that need the event itself, and both can be used together.

<Checkbox bind:checked={on} oncheckedchange={(checked) => save(checked)}>Accept</Checkbox>

<!-- onchange stays the native change event -->
<Checkbox bind:checked={on} onchange={(e) => save(e.currentTarget.checked)}>Accept</Checkbox>

Recipe: function bindings for immutable state

Bind with a getter and a setter when state is updated immutably; the setter is the place to copy or validate.

<script lang="ts">
  let form = $state({ accepted: true });
  const setAccepted = (checked: boolean) => (form = { ...form, accepted: checked });
</script>

<!-- Svelte function bindings: a getter and a setter -->
<Checkbox bind:checked={() => form.accepted, setAccepted}>Accept</Checkbox>

API

Prop	Type	Default	Description
checked bindable	boolean	false	Whether it is checked. Bind it with `bind:checked`.
indeterminate	boolean	false	Shows the mixed state (neither checked nor unchecked).
disabled	boolean	false	Disables the control: it cannot be focused, changed or activated.
hint	string	—	Helper text shown below the control.
onchange event	(e: Event & { currentTarget: HTMLInputElement }) => void	—	The native change event (unchanged). Read the state with `e.currentTarget.checked`.
oncheckedchange event	(checked: boolean) => void	—	Value form of `onchange`: called with the new `checked` state after the user toggles. Not called for programmatic changes.
children snippet	Snippet	—	Content, as a Svelte snippet.
aria-label	string	—	Accessible name.
tabindex	number	—	Tab order override.