Checkbox

A control that allows the user to toggle between checked and not checked.

Basic

Accept terms and conditions

With Description

Accept terms and conditions

By clicking this checkbox, you agree to the terms and conditions.

Invalid

Accept terms and conditions

Disabled

Enable notifications

With Title

Enable notifications

You can enable or disable notifications at any time.

Enable notifications

You can enable or disable notifications at any time.

In Table

Name	Email	Role
Sarah Chen	sarah.chen@example.com	Admin
Marcus Rodriguez	marcus.rodriguez@example.com	User
Priya Patel	priya.patel@example.com	User
David Kim	david.kim@example.com	Editor

Group

<script lang="ts">
  import { Checkbox } from '@sveltery/components/checkbox';
  import { Example, ExampleWrapper } from '@sveltery/components/example';
  import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel, FieldTitle } from '@sveltery/components/field';
  import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@sveltery/components/table';

  const tableData = [
    { id: '1', name: 'Sarah Chen', email: 'sarah.chen@example.com', role: 'Admin' },
    { id: '2', name: 'Marcus Rodriguez', email: 'marcus.rodriguez@example.com', role: 'User' },
    { id: '3', name: 'Priya Patel', email: 'priya.patel@example.com', role: 'User' },
    { id: '4', name: 'David Kim', email: 'david.kim@example.com', role: 'Editor' },
  ];

  const desktopItems = [
    { id: 'finder-pref-9k2-hard-disks-ljj', label: 'Hard disks' },
    { id: 'finder-pref-9k2-external-disks-1yg', label: 'External disks' },
    { id: 'finder-pref-9k2-cds-dvds-fzt', label: 'CDs, DVDs, and iPods' },
    { id: 'finder-pref-9k2-connected-servers-6l2', label: 'Connected servers' },
  ];

  let selectedRows = $state(['1']);

  function setAll(checked: boolean) {
    selectedRows = checked ? tableData.map((row) => row.id) : [];
  }

  function setRow(id: string, checked: boolean) {
    selectedRows = checked ? [...selectedRows, id] : selectedRows.filter((row) => row !== id);
  }
</script>

<ExampleWrapper>
  <Example title="Basic">
    <Field orientation="horizontal">
      <Checkbox id="terms" />
      <FieldLabel for="terms">Accept terms and conditions</FieldLabel>
    </Field>
  </Example>

  <Example title="With Description">
    <Field orientation="horizontal">
      <Checkbox id="terms-2" defaultChecked />
      <FieldContent>
        <FieldLabel for="terms-2">Accept terms and conditions</FieldLabel>
        <FieldDescription>By clicking this checkbox, you agree to the terms and conditions.</FieldDescription>
      </FieldContent>
    </Field>
  </Example>

  <Example title="Invalid">
    <Field orientation="horizontal" data-invalid>
      <Checkbox id="terms-3" aria-invalid />
      <FieldLabel for="terms-3">Accept terms and conditions</FieldLabel>
    </Field>
  </Example>

  <Example title="Disabled">
    <Field orientation="horizontal">
      <Checkbox id="toggle" disabled />
      <FieldLabel for="toggle">Enable notifications</FieldLabel>
    </Field>
  </Example>

  <Example title="With Title">
    <FieldGroup>
      <FieldLabel for="toggle-2">
        <Field orientation="horizontal">
          <Checkbox id="toggle-2" defaultChecked />
          <FieldContent>
            <FieldTitle>Enable notifications</FieldTitle>
            <FieldDescription>You can enable or disable notifications at any time.</FieldDescription>
          </FieldContent>
        </Field>
      </FieldLabel>
      <FieldLabel for="toggle-4">
        <Field orientation="horizontal" data-disabled>
          <Checkbox id="toggle-4" disabled />
          <FieldContent>
            <FieldTitle>Enable notifications</FieldTitle>
            <FieldDescription>You can enable or disable notifications at any time.</FieldDescription>
          </FieldContent>
        </Field>
      </FieldLabel>
    </FieldGroup>
  </Example>

  <Example title="In Table">
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead class="w-8">
            <Checkbox
              id="select-all"
              bind:checked={() => selectedRows.length === tableData.length, setAll}
            />
          </TableHead>
          <TableHead>Name</TableHead>
          <TableHead>Email</TableHead>
          <TableHead>Role</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {#each tableData as row (row.id)}
          <TableRow data-state={selectedRows.includes(row.id) ? 'selected' : undefined}>
            <TableCell>
              <Checkbox
                id={`row-${row.id}`}
                bind:checked={() => selectedRows.includes(row.id), (checked) => setRow(row.id, checked)}
              />
            </TableCell>
            <TableCell class="font-medium">{row.name}</TableCell>
            <TableCell>{row.email}</TableCell>
            <TableCell>{row.role}</TableCell>
          </TableRow>
        {/each}
      </TableBody>
    </Table>
  </Example>

  <Example title="Group">
    <Field>
      <FieldLabel>Show these items on the desktop:</FieldLabel>
      {#each desktopItems as item (item.id)}
        <Field orientation="horizontal">
          <Checkbox id={item.id} />
          <FieldLabel for={item.id} class="font-normal">{item.label}</FieldLabel>
        </Field>
      {/each}
    </Field>
  </Example>
</ExampleWrapper>

Installation

Install the dependencies

pnpm add cn class-variance-authority github:sveltery/base

Copy the component

Copy the following files into src/lib/components/ui/checkbox.

src/lib/components/ui/checkbox/Checkbox.svelte

<script lang="ts">
  import type { ComponentProps } from 'svelte';
  import { Checkbox as Primitive } from '@sveltery/base/checkbox';
  import { cn } from 'cn';
  import CheckIcon from '@lucide/svelte/icons/check';
  let { checked = $bindable(), class: classProp, ...props }: Omit<ComponentProps<typeof Primitive.Root>, 'children'> = $props();
</script>
<Primitive.Root data-slot="checkbox" bind:checked {...props} class={cn('border-input dark:bg-input/30 data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary data-checked:border-primary aria-invalid:aria-checked:border-primary aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 flex size-4 items-center justify-center rounded-[4px] border transition-colors group-has-disabled/field:opacity-50 focus-visible:ring-3 aria-invalid:ring-3 group-has-[:focus-visible]/field-label:ring-0 group-has-[:focus-visible]/field-label:not-data-checked:border-input group-has-[:focus-visible]/field-label:data-checked:border-primary peer relative shrink-0 outline-none after:absolute after:-inset-x-3 after:-inset-y-2 disabled:cursor-not-allowed disabled:opacity-50', classProp)}>
  <Primitive.Indicator data-slot="checkbox-indicator" class="[&>svg]:size-3.5 grid place-content-center text-current transition-none">
    <CheckIcon />
  </Primitive.Indicator>
</Primitive.Root>

src/lib/components/ui/checkbox/index.ts

export { default as Checkbox } from './Checkbox.svelte';

Update the import paths

Change the imports to match your project setup.

Usage

<script lang="ts">
  import { Checkbox } from '$lib/components/ui/checkbox';
  import { Label } from '$lib/components/ui/label';
</script>

<Checkbox id="terms" />
<Label for="terms">Accept terms and conditions</Label>

Checked state

Checkbox works like an HTML checkbox. Use defaultChecked for the initial state, or bind:checked to read and set it.

<script lang="ts">
  let checked = $state(false);
</script>

<Checkbox bind:checked />

Forms

A checkbox with a name submits with its form, as on or its value when checked. An unchecked or disabled checkbox submits nothing.

<form method="POST">
  <Checkbox name="terms" value="accepted" defaultChecked />
  <button type="submit">Save</button>
</form>

Invalid state

Set aria-invalid on the checkbox to show the invalid styles.

<Checkbox id="terms" aria-invalid="true" />

Disabled

Set disabled to prevent interaction.

<Checkbox id="toggle" disabled />

API reference

Checkbox is styled on top of the Sveltery Base Checkbox primitive, which owns its behavior, form submission and accessibility. See the Base UI Checkbox documentation for the behavior it ports.