Pricing

Switch handbook

v1.2.0 · @snowui-design-system/components

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Toggle between on and off for settings and features that take effect immediately.

When to use it

Use it for an immediate two-state setting. Use Checkbox for multiple form selections, and Radio or Segmented for mutually exclusive options.

  • bind:checked synchronizes the on/off state. value only sets the internal input value; it does not determine whether the switch is on.

  • Currently name and form are not forwarded to the internal input. To submit through a native form, explicitly synchronize the field at the form layer. Provide a readable label.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Switch } from '@snowui-design-system/components';	let subscribed = $state(false);</script> <Switch bind:checked={subscribed}>Email me product updates</Switch>

API

Keyword Type Default Description
checked boolean false On/off state; supports bind:checked. Clicking the label or pressing Space while focused toggles it. The bound variable, visible track, and native input remain synchronized. User interaction cannot change it while disabled.
value any — Value passed to the internal native checkbox. It neither determines on/off state nor creates a selection group. Other attributes such as name and form currently go to the outer label, not the internal input; setting value alone does not create a named form submission.
size ResourceSize | number — Visible track height. Numeric values are nominal px at a 16px root font size; outer transparent space is additional. Supports 12 / 16 / 20 / 24 / 28 / 32 / 40 / 48 / 80 and other finite positive numbers. When omitted, uses the parent size Context’s iconSize, then size, then 16. Invalid numbers fall back to the default size Token. Explicit values take precedence and scale with root font size.
disabled boolean false Disables the native input and user toggling while retaining the current value and label; removes it from Tab order. External code may still update checked.
singleLine boolean true Labels and controls use one line by default, with stable attachments. A constrained label may show an ellipsis while retaining its complete accessible name and original children. Set false for complex multiline content. Compose Text lines={1} when a full-text tooltip is needed.
gap number — Inherited Frame gap token index. Omit it for the existing component gap; an explicit value overrides the preferred gap. Effective spacing stays at least 4 CSS px, including zero and root-font or gap-scale reductions. Larger preferred gaps are preserved.
children Snippet — Optional no-argument label content after the track. Its text also provides the internal switch’s accessible name; a content Snippet can compose that text.
enableResponsive boolean false Passed to the root Frame to enable container-content adaptation observation. It does not change Switch’s standard size value range. See Frame capability switches.
enableContext boolean false Passed to the root Frame to control Context for descendants, including state, loading, and motion. It does not control Switch reading the parent size Context. See Frame capability switches.

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Layout model

Primary layout model: inline shell layout. See ../../../specs/maintainers/LayoutProtocol.md §12.4 (source reference: specs/maintainers/LayoutProtocol.md).

Switch is the “control body + label” subtype of inline shell layout:

  • The root remains inline-flex, and the full content hugs its contents.

  • .snowui-switch-track is the control body with fixed, content-hugging size.

  • .snowui-switch-label is an optional label. It hugs its contents when there is room and can shrink with a single-line ellipsis when constrained. Original content and the complete native accessible name are preserved.

  • track and label spacing uses --snowui-switch-gap. Set a preferred value with gap or --snowui-switch-gap-override; effective spacing stays at least 4 CSS px.

  • size is visible track height. Transparent hit-area space on each side is size / 14; occupied height is size × 8 / 7, and occupied width is size × (1.8 + 1 / 7). At size={28}, the track is 50.4×28px with 2px on each side, for a 54.4×32px occupied area.

  • Transparent space, track, and thumb scale together with size, root font size, and size Tokens. The transparent space remains clickable; the label is outside that shell.

Usage examples

<script>  import { Switch } from '@snowui-design-system/components';  let checked = $state(false);</script>  <Switch bind:checked>Switch</Switch>  <Switch bind:checked size={20}>Large switch</Switch>  <Switch checked disabled>Disabled switch</Switch>

States

  • unchecked: off state with a gray track

  • checked: on state with a brand-color track

  • disabled: unavailable with reduced opacity

Accessibility

  • Uses a native <input type="checkbox"> for keyboard navigation

  • Can receive focus with Tab

  • Toggles with Space

  • Uses tabindex=-1 while disabled

Switch style overrides

Read the full LICENSE first; reuse that review for the same task, version, and scope.

First use public component Props to match the desired appearance, preserving the existing look where possible. If changes are necessary, follow the style selection and override order: use your own class (including Tailwind already in the project) or an instance style. The names below are public overrides actually consumed by source; check their scope and do not modify private DOM. Choose the correct SnowUI token family. External apps need not install SnowUI website utilities.

Variable Purpose and default reference
--snowui-switch-color-override Color (see component source for the default)
--snowui-switch-gap-override Gap (default var(--gap-1) = 4px)
--snowui-switch-height-override Height (see component source for the default)
--snowui-switch-label-font-size-override Label font size (see component source for the default)
--snowui-switch-label-line-height-override Label line height (see component source for the default)
--snowui-switch-motion-duration-override Motion duration (see component source for the default)
--snowui-switch-motion-easing-override Motion curve (see component source for the default)
--snowui-switch-overlay-color-override Overlay color (see component source for the default)
--snowui-switch-overlay-opacity-override Overlay opacity (see component source for the default)
--snowui-switch-primary-override Primary color (see component source for the default)
--snowui-switch-radius-override Corner radius (see component source for the default)
--snowui-switch-size-override Overall size in px (see component source for the default)
--snowui-switch-thumb-gap-override Thumb spacing (see component source for the default)
--snowui-switch-thumb-size-override Thumb size in px (see component source for the default)
--snowui-switch-width-override Width (see component source for the default)

Design guide · Tokens · Composition boundaries

Switch types and states

Required Props: no named required Props.

Two-way binding: bind:checked.

Inherited declaration: Omit<FrameProps, "size">. Consult the base component’s public documentation for inherited capabilities; fields excluded by Omit cannot be used as if inherited unchanged.

Shared Frame API · Back to API

The following type declarations are actually referenced by public Props and come from source. A Svelte Snippet denotes a content fragment; ComponentProps denotes the Props of the corresponding component.

ResourceSize

Source: components/src/context.ts

export type ResourceSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;