Installation
Barrel
import { Switch, SwitchGroup, SwitchItem, SwitchLegend } from 'kumo-svelte';Granular
import { Switch, SwitchGroup, SwitchItem, SwitchLegend } from 'kumo-svelte/components/switch';Usage
<script lang="ts"> import { Switch } from 'kumo-svelte'; let checked = $state(false);</script><Switch bind:checked />Examples
Off State
On State
Disabled
Variants
The Switch supports two variants: default (blue when on) and neutral (monochrome). Both use a squircle shape.
Neutral Variant
The neutral variant uses monochrome colors and a squircle shape, ideal for subtle, less prominent toggles.
Neutral States
Sizes
Three sizes available: sm, base (default), and lg.
Custom ID
When a custom id is provided, clicking the label still toggles the switch.
The id is forwarded to Base UI so the label's htmlFor stays in sync.
Switch Group
Group related switches with Switch.Group. Provides a shared legend,
description, and error message for the group.
Visually Hidden Legend
Use Switch.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
Switch.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
Switch
Individual switch toggle with built-in label.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | 'default' | 'neutral' | "default" | Visual variant. |
| label | string | - | Visible label content. |
| labelTooltip | string | Snippet | - | Optional help content for the label. |
| required | boolean | - | Marks the field as required. |
| controlFirst | boolean | true | Renders the control before label content. |
| size | 'sm' | 'base' | 'lg' | "base" | Size preset. |
| checked | boolean | false | Checked state. |
| disabled | boolean | false | Disables the component. |
| transitioning | boolean | - | transitioning prop. |
| class | string | - | Additional classes merged onto the root element. |
| id | string | - | Element id. |
| aria-label | string | - | Accessible label. |
| onchange | (checked: boolean) => void | - | Change event handler. |
| onCheckedChange | (checked: boolean) => void | - | Called when checked changes. |
Switch.Group
Container for multiple switches with legend, description, and error support.
| Prop | Type | Default | Description |
|---|---|---|---|
| legend | string | - | legend prop. |
| error | string | - | Validation error message or matcher. |
| description | string | - | Supporting description text. |
| disabled | boolean | false | Disables the component. |
| controlFirst | boolean | true | Renders the control before label content. |
Switch.Legend
Composable legend sub-component for Switch.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.
| Prop | Type | Default | Description |
|---|---|---|---|
| No component-specific props. Accepts standard HTML attributes. | |||
Switch.Item
Individual switch within Switch.Group.
| Prop | Type | Default | Description |
|---|---|---|---|
| checked | boolean | false | Checked state. |
| disabled | boolean | false | Disables the component. |
| size | 'sm' | 'base' | 'lg' | "base" | Size preset. |
| variant | 'default' | 'neutral' | "default" | Visual variant. |
| label * | string | - | Visible label content. |
| transitioning | boolean | - | transitioning prop. |
| onchange | (checked: boolean) => void | - | Change event handler. |
| onCheckedChange | (checked: boolean) => void | - | Called when checked changes. |