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.

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).

Checked

Indeterminate

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

Label First Layout

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

Disabled

Error

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

Checkbox Group

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

Checkbox Group with Error

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

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.

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.

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.