Switch
kumo-svelte

Switch

A two-state button that can be either on or off.

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

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

<Switch label="Switch" bind:checked />

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

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

<Switch label="Switch" checked={false} />

On State

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

<Switch label="Switch" checked={true} />

Disabled

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

<Switch label="Disabled" checked={false} disabled />

Variants

The Switch supports two variants: default (blue when on) and neutral (monochrome). Both use a squircle shape.

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

<div class="grid grid-cols-2 gap-x-8 gap-y-4">
  <Switch label="Default off" checked={false} />
  <Switch label="Default on" checked={true} />
  <Switch label="Neutral off" variant="neutral" checked={false} />
  <Switch label="Neutral on" variant="neutral" checked={true} />
</div>

Neutral Variant

The neutral variant uses monochrome colors and a squircle shape, ideal for subtle, less prominent toggles.

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

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

<Switch label="Neutral switch" variant="neutral" bind:checked />

Neutral States

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

<div class="flex flex-col gap-4">
  <Switch label="Neutral off" variant="neutral" checked={false} />
  <Switch label="Neutral on" variant="neutral" checked={true} />
  <Switch label="Neutral disabled" variant="neutral" checked={false} disabled />
</div>

Sizes

Three sizes available: sm, base (default), and lg.

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

<div class="flex flex-col gap-4">
  <Switch label="Small" size="sm" checked={true} />
  <Switch label="Base (default)" size="base" checked={true} />
  <Switch label="Large" size="lg" checked={true} />
</div>

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.

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

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

<Switch id="my-custom-switch" label="Custom ID" bind:checked />

Switch Group

Group related switches with Switch.Group. Provides a shared legend, description, and error message for the group.

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

<Switch.Group legend="Notification settings">
  <Switch.Item label="Email notifications" />
  <Switch.Item label="SMS notifications" />
  <Switch.Item label="Push notifications" />
</Switch.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.

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

<Switch.Group>
  <Switch.Legend class="sr-only">Notification settings</Switch.Legend>
  <Switch.Item label="Email notifications" />
  <Switch.Item label="SMS notifications" />
  <Switch.Item label="Push notifications" />
</Switch.Group>

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.

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

<Switch.Group>
  <Switch.Legend class="text-sm font-normal text-kumo-subtle">
    Notification settings
  </Switch.Legend>
  <Switch.Item label="Email notifications" />
  <Switch.Item label="SMS notifications" />
  <Switch.Item label="Push notifications" />
</Switch.Group>

API Reference

Switch

Individual switch toggle with built-in label.

PropTypeDefaultDescription
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 booleantrueRenders the control before label content.
size 'sm' | 'base' | 'lg'"base"Size preset.
checked booleanfalseChecked state.
disabled booleanfalseDisables 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.

PropTypeDefaultDescription
legend string-legend prop.
error string-Validation error message or matcher.
description string-Supporting description text.
disabled booleanfalseDisables the component.
controlFirst booleantrueRenders 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.

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

Switch.Item

Individual switch within Switch.Group.

PropTypeDefaultDescription
checked booleanfalseChecked state.
disabled booleanfalseDisables 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.