Checkbox

People need to be able to accept the terms and conditions they don't read somehow.

<script>
	import { Checkbox, CheckboxField, CheckboxGroup } from '$lib/components/checkbox';
	import { Description, Fieldset, Label, Legend } from '$lib/components/fieldset';
	import { Text } from '$lib/components/text';
</script>

<Fieldset>
	<Legend>Discoverability</Legend>
	<Text>Decide where your events can be found across the web.</Text>
	<CheckboxGroup>
		<CheckboxField>
			<Checkbox name="discoverability" value="show_on_events_page" defaultChecked />
			<Label>Show on events page</Label>
			<Description>Make this event visible on your profile.</Description>
		</CheckboxField>
		<CheckboxField>
			<Checkbox name="discoverability" value="allow_embedding" />
			<Label>Allow embedding</Label>
			<Description>Allow others to embed your event details on their own site.</Description>
		</CheckboxField>
	</CheckboxGroup>
</Fieldset>

Component API

Prop	Default	Description
Checkbox extends the Headless UI <Checkbox> component
color	dark/zinc	The color variant the checkbox should use.
disabled	false	Whether or not to disable the checkbox.
name	-	The name to use when submitting an HTML form.
value	-	The value to use when submitting an HTML form.
defaultChecked	-	The initial state of the checkbox.
checked	-	The controlled state of the checkbox.
onChange	-	Handler to call when the checkbox state changes.
CheckboxField extends the Headless UI <Field> component
disabled	false	Whether or not to disable the entire field.
CheckboxGroup extends the JSX <div> element
This component does not expose any component-specific props.
Label extends the Headless UI <Label> component
This component does not expose any component-specific props.
Description extends the Headless UI <Description> component
This component does not expose any component-specific props.

Examples

Basic example

Use the Checkbox component on its own to render a standalone checkbox without an associated Label component:

<script>
	import { Checkbox } from '$lib/components/checkbox';
</script>

<Checkbox aria-label="Allow embedding" name="allow_embedding" />

Make sure to provide an aria-label for assistive technology, or connect the Checkbox to your own <label> element using an id.

With label

Wrap a Label and Checkbox with the CheckboxField component to automatically associate them using a generated ID:

<script>
	import { Checkbox, CheckboxField } from '$lib/components/checkbox';
	import { Label } from '$lib/components/fieldset';
</script>

<CheckboxField>
	<Checkbox name="allow_embedding" />
	<Label>Allow embedding</Label>
</CheckboxField>

With description

Use the CheckboxField, Label, and Description components to add a description below the checkbox:

Allow embedding

Allow others to embed your event details on their own site.

<script>
	import { Checkbox, CheckboxField } from '$lib/components/checkbox';
	import { Description, Label } from '$lib/components/fieldset';
</script>

<CheckboxField>
	<Checkbox name="allow_embedding" />
	<Label>Allow embedding</Label>
	<Description>Allow others to embed your event details on their own site.</Description>
</CheckboxField>

With custom layout

Use the unstyled Field component from @headlessui/react directly instead of the styled CheckboxField component to implement a custom layout:

Allow embedding

<script>
	import { Checkbox } from '$lib/components/checkbox';
	import { Label } from '$lib/components/fieldset';
	import * as Headless from '@headlessui/react';
</script>

<Headless.Field class="flex items-center justify-between gap-4">
	<Label>Allow embedding</Label>
	<Checkbox name="allow_embedding" />
</Headless.Field>

Using the unstyled Field component will ensure important accessibility features are still handled for you like generating IDs and associating elements using aria-* attributes.

With accent color

Use the color prop to choose a different accent color for a checkbox:

<script>
	import { Checkbox } from '$lib/components/checkbox';
</script>

<Checkbox color="sky" defaultChecked />

For a full list of included color variants, check out the checkbox color reference.

With custom value

Use the value prop to specify a custom value to use when submitting a form:

<script>
	import { Checkbox } from '$lib/components/checkbox';
</script>

<Checkbox name="embed" value="allow" />

Default checked state

Use the defaultChecked prop to set the default state when using the Checkbox as an uncontrolled component:

<script>
	import { Checkbox } from '$lib/components/checkbox';
</script>

<Checkbox defaultChecked />

Indeterminate state

Use the indeterminate prop to indicate that the Checkbox is in an indeterminate state, neither toggled on nor off:

<script>
	import { Checkbox, CheckboxField, CheckboxGroup } from '$lib/components/checkbox';
	import { Label } from '$lib/components/fieldset';

	const options = ['Show on events page', 'Allow embedding'];
	let selected = $state(['Show on events page']);
</script>

<CheckboxGroup role="group" aria-label="Discoverability">
	<CheckboxField>
		<Checkbox
			checked={selected.length > 0}
			indeterminate={selected.length !== options.length}
			onChange={(checked) => (selected = checked ? options : [])}
		/>
		<Label>Select all</Label>
	</CheckboxField>

	{#each options as option (option)}
		<CheckboxField>
			<Checkbox
				name={option}
				checked={selected.includes(option)}
				onChange={(checked) => {
					selected = checked ? [...selected, option] : selected.filter((item) => item !== option);
				}}
			/>
			<Label>{option}</Label>
		</CheckboxField>
	{/each}
</CheckboxGroup>

Controlled component

Use the checked and onChange props to use a Checkbox as a controlled component:

<script>
	import { Checkbox } from '$lib/components/checkbox';

	let checked = $state(true);
</script>

<Checkbox {checked} onChange={() => (checked = !checked)} />

Multiple checkboxes

Use the CheckboxGroup component to stack multiple checkboxes together in a list:

<script>
	import { Checkbox, CheckboxField, CheckboxGroup } from '$lib/components/checkbox';
	import { Description, Label } from '$lib/components/fieldset';
</script>

<CheckboxGroup>
	<CheckboxField>
		<Checkbox name="show_on_events_page" defaultChecked />
		<Label>Show on events page</Label>
		<Description>Make this event visible on your profile.</Description>
	</CheckboxField>
	<CheckboxField>
		<Checkbox name="allow_embedding" />
		<Label>Allow embedding</Label>
		<Description>Allow others to embed your event details on their own site.</Description>
	</CheckboxField>
</CheckboxGroup>

You can optionally add role="group" and an aria-label to the CheckboxGroup if all of the checkboxes are related and you want them announced to assistive technology as a group.

With fieldset

Use the Fieldset, Legend, and Text components to add a title and description to a group of checkboxes:

<script>
	import { Checkbox, CheckboxField, CheckboxGroup } from '$lib/components/checkbox';
	import { Description, Fieldset, Label, Legend } from '$lib/components/fieldset';
	import { Text } from '$lib/components/text';
</script>

<Fieldset>
	<Legend>Discoverability</Legend>
	<Text>Decide where your events can be found across the web.</Text>
	<CheckboxGroup>
		<CheckboxField>
			<Checkbox name="discoverability" value="show_on_events_page" defaultChecked />
			<Label>Show on events page</Label>
			<Description>Make this event visible on your profile.</Description>
		</CheckboxField>
		<CheckboxField>
			<Checkbox name="discoverability" value="allow_embedding" />
			<Label>Allow embedding</Label>
			<Description>Allow others to embed your event details on their own site.</Description>
		</CheckboxField>
	</CheckboxGroup>
</Fieldset>

Disabled state

Add the disabled prop to a Checkbox or CheckboxField component to disable it:

<script>
	import { Checkbox, CheckboxField, CheckboxGroup } from '$lib/components/checkbox';
	import { Description, Fieldset, Label, Legend } from '$lib/components/fieldset';
	import { Text } from '$lib/components/text';
</script>

<Fieldset>
	<Legend>Discoverability</Legend>
	<Text>Decide where your events can be found across the web.</Text>
	<CheckboxGroup>
		<CheckboxField>
			<Checkbox name="discoverability" value="show_on_events_page" />
			<Label>Show on events page</Label>
			<Description>Make this event visible on your profile.</Description>
		</CheckboxField>
		<CheckboxField disabled>
			<Checkbox name="discoverability" value="allow_embedding" />
			<Label>Allow embedding</Label>
			<Description>Allow others to embed your event details on their own site.</Description>
		</CheckboxField>
	</CheckboxGroup>
</Fieldset>

You can also add the disabled prop to a Fieldset to disable the entire fieldset.

Appendix

Color reference

By default, Catalyst includes two adaptive color variants that automatically change color between light and dark modes to maintain a consistent level of contrast:

Color	Example
dark/zinc
dark/white

Catalyst also includes 20 solid colors that don't change outside of subtle global changes we make to all checkboxes in dark mode:

Color	Example
dark
zinc
white
red
orange
amber
yellow
lime
green
emerald
teal
cyan
sky
blue
indigo
violet
purple
fuchsia
pink
rose