Checkbox
kumo-svelte

Checkbox

A control that allows the user to toggle between checked and not checked. Features built-in label support with automatic horizontal layout.

<script lang="ts">
  import { Checkbox } from 'kumo-svelte';
</script>

<Checkbox>Accept terms and conditions</Checkbox>

Installation

Barrel

import { Checkbox, CheckboxGroup, CheckboxItem, CheckboxLegend } from 'kumo-svelte';

Granular

import { Checkbox, CheckboxGroup, CheckboxItem, CheckboxLegend } from 'kumo-svelte/components/checkbox';

Usage

<script lang="ts">  import { Checkbox } from 'kumo-svelte';  let checked = $state(false);</script><Checkbox label="Accept terms" bind:checked />

Examples

Default

Checkbox with built-in label. The label automatically displays in a horizontal layout (checkbox before label).

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<Checkbox>Enable notifications</Checkbox>
</div>

Checked

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<Checkbox checked={true}>I agree</Checkbox>
</div>

Indeterminate

Used for "select all" patterns when some but not all items are selected.

<script lang="ts">
  import { Checkbox } from '$lib';

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

<div class="flex min-h-24 w-full items-center justify-center">
  <Checkbox label="Select all" bind:indeterminate />
</div>

Label First Layout

Use controlFirst={false} to place the label before the checkbox.

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<label class="inline-flex items-center gap-2 text-sm text-kumo-default">
      Remember me
      <Checkbox />
    </label>
</div>

Disabled

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<Checkbox disabled>Disabled option</Checkbox>
</div>

Error

Error variant provides visual styling (red ring). For error messages, use Checkbox.Group.

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<Checkbox class="ring-kumo-danger">Invalid option</Checkbox>
</div>

Checkbox Group

Group multiple checkboxes with a legend, description, and shared error messages. Uses Checkbox.Group and Checkbox.Item.

Email preferences

Choose how you'd like to receive updates

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<div class="grid gap-3">
      <p class={'text-sm font-medium text-kumo-default'}>{'Email preferences'}</p>
      <p class="-mt-2 text-sm text-kumo-subtle">Choose how you'd like to receive updates</p>
      <Checkbox checked={true}>Email notifications</Checkbox>
      <Checkbox>SMS notifications</Checkbox>
      <Checkbox>Push notifications</Checkbox>
    </div>
</div>

Checkbox Group with Error

Show validation errors at the group level. Error replaces description when present.

Required preferences

Please select at least one notification method

<script lang="ts">
  import { Checkbox } from '$lib';
</script>

<div class="flex min-h-24 w-full items-center justify-center">
<div class="grid gap-3">
      <p class="text-sm font-medium text-kumo-default">Required preferences</p>
      <Checkbox class="ring-kumo-danger">Email</Checkbox>
      <Checkbox class="ring-kumo-danger">SMS</Checkbox>
      <p class="text-sm text-kumo-danger">Please select at least one notification method</p>
    </div>
</div>

Visually Hidden Legend

Use Checkbox.Legend with class="sr-only" to keep the legend accessible to screen readers while hiding it visually. This is useful when the group is already labeled by a parent Field or heading, and showing the legend would create a redundant label.

Requests
1,234 req/s
Storage
56 GB
<script lang="ts">
  import { ChartLegend, ChartPalette } from 'kumo-svelte';
</script>

<div class="flex flex-wrap gap-4">
  <ChartLegend
    variant="large"
    name="Requests"
    color={ChartPalette.semantic('Neutral')}
    value="1,234"
    unit="req/s"
  />
  <ChartLegend
    variant="large"
    name="Storage"
    color={ChartPalette.semantic('Attention')}
    value="56"
    unit="GB"
  />
</div>

Custom Legend Styling

Checkbox.Legend accepts class for full control over legend presentation. Use it instead of the legend string prop when you need custom typography, colors, or layout.

Requests
1,234 req/s
Storage
56 GB
<script lang="ts">
  import { ChartLegend, ChartPalette } from 'kumo-svelte';
</script>

<div class="flex flex-wrap gap-4">
  <ChartLegend
    variant="large"
    name="Requests"
    color={ChartPalette.semantic('Neutral')}
    value="1,234"
    unit="req/s"
  />
  <ChartLegend
    variant="large"
    name="Storage"
    color={ChartPalette.semantic('Attention')}
    value="56"
    unit="GB"
  />
</div>

API Reference

Checkbox

Single checkbox component with built-in label and horizontal layout.

PropTypeDefaultDescription
variant 'default' | 'error'"default"Visual variant.
label string-Visible label content.
labelTooltip Snippet-Optional help content for the label.
controlFirst booleantrueRenders the control before label content.
checked booleanfalseChecked state.
indeterminate booleanfalseIndeterminate checked state.
disabled booleanfalseDisables the component.
name string-Form field name.
required boolean-Marks the field as required.
class string-Additional classes merged onto the root element.
value string-Controlled value.
id string-Element id.
aria-label string-Accessible label.
aria-labelledby string-Accessible labelled-by reference.
onCheckedChange (checked: boolean) => void-Called when checked changes.
onIndeterminateChange (indeterminate: boolean) => void-Called when indeterminate changes.

Checkbox.Group

Wrapper for multiple checkboxes with legend, description, and error support.

PropTypeDefaultDescription
legend string-legend prop.
error string-Validation error message or matcher.
description string | Snippet-Supporting description text.
value string[][]Controlled value.
disabled booleanfalseDisables the component.
controlFirst booleantrueRenders the control before label content.
required boolean-Marks the field as required.
name string-Form field name.
onValueChange (value: string[]) => void-Called when the value changes.

Checkbox.Legend

Composable legend sub-component for Checkbox.Group. Accepts class for full styling control (e.g. class="sr-only" to visually hide). Use instead of the legend string prop when you need custom legend styling.

PropTypeDefaultDescription
No component-specific props. Accepts standard HTML attributes.

Checkbox.Item

Individual checkbox within Checkbox.Group.

PropTypeDefaultDescription
checked boolean-Checked state.
indeterminate booleanfalseIndeterminate checked state.
disabled booleanfalseDisables the component.
variant 'default' | 'error'"default"Visual variant.
label *string-Visible label content.
value string-Controlled value.
name string-Form field name.
onCheckedChange (checked: boolean) => void-Called when checked changes.
onIndeterminateChange (indeterminate: boolean) => void-Called when indeterminate changes.

Accessibility

Label Requirement

Single checkboxes require a label prop or aria-label for accessibility. Missing labels trigger console warnings in development.

Keyboard Navigation

Space toggles the checkbox.

Tab moves focus between checkboxes.

Screen Readers

Checkbox.Group uses semantic <fieldset> and <legend> elements for proper grouping announcement.