Report an issue

Checkbox

Allow users to switch between checked, unchecked, and indeterminate states.

	<script lang="ts">
  import { Checkbox, Label } from "bits-ui";
  import Check from "phosphor-svelte/lib/Check";
  import Minus from "phosphor-svelte/lib/Minus";
</script>
 
<div class="flex items-center space-x-3">
  <Checkbox.Root
    id="terms"
    aria-labelledby="terms-label"
    class="peer inline-flex size-[25px] items-center justify-center rounded-md border border-muted bg-foreground transition-all duration-150 ease-in-out active:scale-98 data-[state=unchecked]:border-border-input data-[state=unchecked]:bg-background data-[state=unchecked]:hover:border-dark-40"
    name="hello"
  >
    {#snippet children({ checked })}
      <div class="inline-flex items-center justify-center text-background">
        {#if checked === true}
          <Check class="size-[15px]" weight="bold" />
        {:else if checked === "indeterminate"}
          <Minus class="size-[15px]" weight="bold" />
        {/if}
      </div>
    {/snippet}
  </Checkbox.Root>
  <Label.Root
    id="terms-label"
    for="terms"
    class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
  >
    Accept terms and conditions
  </Label.Root>
</div>

Structure

	<script lang="ts">
	import { Checkbox } from "bits-ui";
</script>
 
<Checkbox.Root>
	{#snippet children({ checked })}
		{#if checked === "indeterminate"}
			-
		{:else if checked}
			✅
		{:else}
			❌
		{/if}
	{/snippet}
</Checkbox.Root>

Reusable Components

It's recommended to use the Checkbox primitive to create your own custom checkbox component that can be used throughout your application. In the example below, we're using the Checkbox and Label components to create a custom checkbox component.

MyCheckbox.svelte
	<script lang="ts">
	import { Checkbox, Label, useId, type WithoutChildrenOrChild } from "bits-ui";
 
	let {
		id = useId(),
		checked = $bindable(false),
		ref = $bindable(null),
		...restProps
	}: WithoutChildrenOrChild<Checkbox.RootProps> & {
		labelText: string;
	} = $props();
</script>
 
<Checkbox.Root bind:checked bind:ref {...restProps}>
	{#snippet children({ checked })}
		{#if checked === "indeterminate"}
			-
		{:else if checked}
			✅
		{:else}
			❌
		{/if}
	{/snippet}
</Checkbox.Root>
<Label.Root for={id}>
	{labelText}
</Label.Root>

You can then use the MyCheckbox component in your application like so:

+page.svelte
	<script lang="ts">
	import MyCheckbox from "$lib/components/MyCheckbox.svelte";
</script>
 
<MyCheckbox labelText="Enable notifications" />

Managing Checked State

The checked prop is used to determine whether the checkbox is in one of three states: checked, unchecked, or indeterminate. Bits UI provides flexible options for controlling and synchronizing the Checkbox's checked state.

Two-Way Binding

Use the bind:checked directive for effortless two-way synchronization between your local state and the Checkbox's internal state.

	<script lang="ts">
	import MyCheckbox from "$lib/components/MyCheckbox.svelte";
	let myChecked = $state(false);
</script>
 
<button onclick={() => (myChecked = false)}> uncheck </button>
 
<MyCheckbox bind:checked={myChecked} />

This setup enables toggling the Checkbox via the custom button and ensures the local myChecked state updates when the Checkbox changes through any internal means (e.g., clicking on the checkbox).

Change Handler

You can also use the onCheckedChange prop to update local state when the Checkbox's checked state changes. This is useful when you don't want two-way binding for one reason or another, or you want to perform additional logic when the Checkbox changes.

	<script lang="ts">
	import MyCheckbox from "$lib/components/MyCheckbox.svelte";
	let myChecked = $state(false);
</script>
 
<MyCheckbox
	checked={myChecked}
	onCheckedChange={(checked) => {
		myChecked = checked;
		if (checked === "indeterminate") {
			// do something different
		}
		// additional logic here.
	}}
/>

Disabled State

You can disable the checkbox by setting the disabled prop to true.

	<MyCheckbox disabled labelText="Enable notifications" />

HTML Forms

If you set the name prop, a hidden checkbox input will be rendered to submit the value of the checkbox to a form. By default, the checkbox will be submitted with default checkbox values of on or off depending on the checked prop. You can customize the value by setting the value prop.

	<MyCheckbox name="myCheckbox" value="on" labelText="Enable notifications" />

API Reference

Checkbox.Root

The button component used to toggle the state of the checkbox.

Property Type Description
checked bindable prop
enum

The checkbox button's checked state. This can be a boolean or the string 'indeterminate', which would typically display a dash in the checkbox.

Default: false
onCheckedChange
function

A callback that is fired when the checkbox button's checked state changes.

Default: undefined
disabled
boolean

Whether or not the checkbox button is disabled. This prevents the user from interacting with it.

Default: false
required
boolean

Whether or not the checkbox is required.

Default: false
name
string

The name of the checkbox. If provided a hidden input will be render to use for form submission. If not provided, the hidden input will not be rendered.

Default: undefined
value
string

The value of the checkbox. This is what is submitted with the form when the checkbox is checked.

Default: undefined
ref bindable prop
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-state
enum

The checkbox's state of checked, unchecked, or indeterminate.

data-disabled
''

Present when the checkbox is disabled.

data-checkbox-root
''

Present on the root element.