Checkbox

A form control that allows users to select one or more options from a set.

Anatomy

<script>
  import {
    Checkbox,
    CheckboxControl,
    CheckboxLabel,
    CheckboxIndicator,
    CheckboxGroup,
  } from "@saas-ui/svelte/components/checkbox";
</script>

<!-- Simple checkbox with label -->
<Checkbox.Root label="Accept terms" />

<!-- Checkbox group -->
<CheckboxGroup label="Select options">
  <Checkbox.Root label="Option 1" value="1" />
  <Checkbox.Root label="Option 2" value="2" />
  <Checkbox.Root label="Option 3" value="3" />
</CheckboxGroup>

Examples

Basic Accessibility

Basic checkbox with label and default styling.

<Checkbox.Root label="Accept terms and conditions" />

Colours Accessibility

Use the colour prop to change the colour scheme. Supports all standard colour palettes.

<VStack align="start" gap={2}>
	{#each colours as colour}
		<HStack align="center" gap={10} class="w-full">
			<Text size="xs" class="min-w-[8ch]">
				{colour}
			</Text>
			{#each checkboxVariants as variant}
				<Checkbox.Root
					{variant}
					{colour}
					checked
					label="Checkbox"
				/>
			{/each}
		</HStack>
	{/each}
</VStack>

Controlled Accessibility

Controlled checkbox with bound checked state for programmatic control.

<Checkbox.Root
	bind:checked={controlledChecked}
	label="Accept terms and conditions"
/>

Custom Icon Accessibility

Checkbox with a custom icon instead of the default checkmark.

<Checkbox.Root checked label="With Custom Icon" icon={Plus} />

Description Accessibility

Checkbox with additional description text for extra context.

<Checkbox.Root class="items-start">
	<Checkbox.Control>
		<Checkbox.Indicator>
			<Icon as={Check} class="h-full w-full" weight="bold" />
		</Checkbox.Indicator>
	</Checkbox.Control>
	<Checkbox.Label>
		<VStack gap={0}>
			<Text as="span" class="text-fg-default">
				I agree to the terms and conditions
			</Text>
			<Text as="span" class="text-fg-muted mt-1 font-normal">
				By clicking this, you agree to our Terms and Privacy Policy.
			</Text>
		</VStack>
	</Checkbox.Label>
	<Checkbox.HiddenInput />
</Checkbox.Root>

Group Accessibility

Use Checkbox.Group to group related checkboxes with shared state management.

<Checkbox.Group label="Select framework">
	<Checkbox.Root value="react" label="React" />
	<Checkbox.Root value="svelte" label="Svelte" />
	<Checkbox.Root value="vue" label="Vue" />
	<Checkbox.Root value="angular" label="Angular" />
</Checkbox.Group>

Indeterminate Accessibility

Indeterminate state for parent checkbox when only some child checkboxes are selected.

<VStack gap={2}>
	<Checkbox.Root
		checked={isIndeterminate ? "indeterminate" : allSelected}
		onCheckedChange={handleSelectAll}
		label="Weekdays"
	/>
	<Checkbox.Group bind:value={indeterminateValue} class="ps-6">
		{#each indeterminateItems as item}
			<Checkbox.Root value={item.value} label={item.label} />
		{/each}
	</Checkbox.Group>
</VStack>

Sizes Accessibility

Use the size prop to change the size of the checkbox. Available sizes: sm, md, lg.

<HStack align="start" gap={12} class="flex-1">
	{#each checkboxSizes as size}
		<VStack gap={2} class="items-center">
			<Text size="xs">{size}</Text>
			<Checkbox.Root {size} checked label="Checkbox" />
		</VStack>
	{/each}
</HStack>

States Accessibility

Checkbox states including disabled and invalid for form validation.

<Stack gap={2}>
	<Checkbox.Root disabled label="Disabled" />
	<Checkbox.Root checked disabled label="Disabled Checked" />
	<Checkbox.Root invalid label="Invalid" />
</Stack>

Variants Accessibility

Use the variant prop to change the visual style. Available variants: outline, subtle, solid.

<HStack align="start" gap={10}>
	{#each checkboxVariants as variant}
		<VStack gap={2} class="flex-1 items-center">
			<Text size="xs">
				{variant}
			</Text>
			<Checkbox.Root checked={false} {variant} label="Unchecked" />
			<Checkbox.Root checked {variant} label="Checked" />
		</VStack>
	{/each}
</HStack>

With Link Accessibility

Checkbox with a link in the label for terms and conditions scenarios.

<Checkbox.Root>
	<Checkbox.Control>
		<Checkbox.Indicator>
			<Icon as={Check} class="h-full w-full" weight="bold" />
		</Checkbox.Indicator>
	</Checkbox.Control>
	<Checkbox.Label>
		I agree to the
		<Link colour="teal" href="https://google.com"
			>terms and conditions</Link>
	</Checkbox.Label>
	<Checkbox.HiddenInput />
</Checkbox.Root>

Props

Checkbox.Root

The root checkbox component.

Prop	Type	Default	Description
`children`	`Snippet`	-	Content to render inside the checkbox (composition API).
`label`	`string`	-	The label text displayed next to the checkbox.
`class`	`string`	-	Additional CSS classes to apply.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	The size of the checkbox.
`variant`	`"solid" \| "subtle" \| "outline"`	`"solid"`	The visual style of the checkbox.
`colour`	`ColourName`	`"indigo"`	The colour palette of the checkbox.
`checked`	`boolean \| "indeterminate"`	`false`	The controlled checked state of the checkbox.
`defaultChecked`	`boolean`	-	The default checked state when uncontrolled.
`value`	`string`	-	The value of the checkbox (used in groups).
`name`	`string`	-	The name of the input field.
`disabled`	`boolean`	`false`	Whether the checkbox is disabled.
`invalid`	`boolean`	`false`	Whether the checkbox is in an invalid state.
`required`	`boolean`	`false`	Whether the checkbox is required.
`icon`	`Component<any>`	-	Custom icon component to render when checked. Auto-sized to fill the checkbox.
`onCheckedChange`	`(details: { checked: boolean \| "indeterminate" }) => void`	-	Callback invoked when the checked state changes.

Checkbox.Control

The visual control element for the checkbox (the box itself).

Prop	Type	Default	Description
`children`	`Snippet`	-	The content of the control (usually indicators).
`class`	`string`	-	Additional classes to apply to the control.
`checked`	`boolean \| "indeterminate"`	`false`	Whether the checkbox is checked.

Checkbox.Indicator

The indicator element that shows when the checkbox is checked.

Prop	Type	Default	Description
`children`	`Snippet`	-	The content of the indicator (usually an icon).
`indeterminate`	`boolean`	`false`	Whether this indicator is for the indeterminate state.
`class`	`string`	-	Additional classes to apply to the indicator.

Checkbox.Label

The text label for the checkbox.

Prop	Type	Default	Description
`children`	`Snippet`	-	The content of the label.
`class`	`string`	-	Additional classes to apply to the label.

Checkbox.Group

A container for grouping related checkboxes with shared state.

Prop	Type	Default	Description
`children`	`Snippet`	-	Content to render inside the group.
`orientation`	`"horizontal" \| "vertical"`	`"vertical"`	The layout orientation of the group.
`label`	`string`	-	The label displayed above the group.
`value`	`string[]`	-	The controlled value of the checkbox group.
`defaultValue`	`string[]`	-	The default value of the checkbox group when uncontrolled.
`name`	`string`	-	The name of the input fields in the checkbox group (useful for form submission).
`disabled`	`boolean`	-	Whether the checkbox group is disabled.
`readOnly`	`boolean`	-	Whether the checkbox group is read-only.
`invalid`	`boolean`	-	Whether the checkbox group is invalid.
`onValueChange`	`(value: string[]) => void`	-	Callback invoked when the value changes.
`class`	`string`	-	Additional CSS classes to apply.

Checkbox.HiddenInput

A hidden input element for form submission and accessibility.

Prop	Type	Default	Description