Svelte Switch Showcase

📚 MultiSwitch Component

A multi-step switch (3+ options) with Svelte 5 runes, snippets, and generic typing.

Import

Basic Usage

🔧 Properties

Property	Type	Default	Description	Version
`selectedIndex`	`number`	`0`	Currently selected index (bindable via `bind:selectedIndex`)	1.0+
`items`	`readonly T[] \| null`	`null`	Array of options. Generic over `T` — type flows through to all snippets and callbacks.	2.0+ generic
`itemsCount`	`number`	`0`	Number of steps (when not deriving from `items`)	1.0+
`isDisabled`	`boolean`	`false`	Disables interaction when true	1.0+
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction	1.0+
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number`	`"md"`	Named size or numeric pixels. Default changed from `50` to `"md"` in 2.0.	2.0+ named
`itemStyles`	`StepStyle \| StepStyle[]`	`undefined`	Per-step styles. Object applies to every step; array applies per-step (length = items.length).	1.0+
`shouldDisplayLabels`	`boolean`	`false`	Show or hide option labels	1.3+
`labelPosition`	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	Position of labels relative to the switch	1.3+
`labelRenderMode`	`"absolute" \| "block"`	`"absolute"`	`"block"` reserves layout space; `"absolute"` overlays (needs manual padding)	1.4+
`labelMember`	`keyof T \| string`	`undefined`	Property name to read from each item (e.g., `"name"` reads `item.name`)	1.4+
`labelCallback`	`(item: T \| undefined, index: number) => string`	`undefined`	Custom function returning the label text for each item	1.4+
`onItemChange`	`(index: number) => void`	`undefined`	Callback fired when the selection changes	1.0+

❌ Removed in v2.0

disableThumbRender — no longer needed; just don't pass the thumb snippet.
update() instance method — Svelte 5 props are reactive; mutate the $state object passed to mount().

🎭 Snippets

Snippet	Context	Role	Version
`thumb`	`{ index, item }`	Renders once inside the moving thumb. `index` = active index.	2.0+ split
`segment`	`{ index, item, isSelected }`	Renders once per step background. Use for static per-step content.	2.0+ split
`label`	`{ index, item, isSelected }`	Custom per-step label content. Renamed from `labelTemplate` in 2.0.	2.0+ renamed

v2.0 snippet rewrite. 1.x had one ambiguous children snippet that ran in BOTH the moving thumb and each step background. 2.0 split it into thumb (one render) + segment (one render per step) so each snippet has one job. labelTemplate was also renamed to label. Snippet context shape unified: currentIndex → index, currentItem → item.

📋 Type Definitions

StepStyle interface

Generic items signature

💡 Usage Examples

Basic Multi-Option

Per-Step Styling

label snippet (rich content)

thumb + segment snippets

labelMember (object property)

labelCallback (computed string)

🏷️ Label Positioning & Rendering

💡 Recommended: Use labelRenderMode="block" in most cases — it reserves layout space automatically. "absolute" is the legacy default and requires manual padding.

Position	Required (absolute mode only)	Works With
`top`	`padding-top: 3rem`	Horizontal only
`bottom` (default)	`padding-bottom: 2.5rem`	Horizontal only
`left`	`padding-left: 5rem`	Vertical only
`right`	`padding-right: 6–8rem`	Vertical only

🔤 Label Content (priority system)

Label text resolves through this priority chain (highest to lowest):

label snippet — full custom rendering, takes precedence over everything
labelMember — read text from object property
labelCallback — compute text from item + index
Default — "Option 1", "Option 2", ...

💡 Clickable per-step labels: In vertical mode with "left"/"right" label positions, labels render as real <button> elements with keyboard activation. This activates only when no thumb snippet is provided.

🎨 Theming

v2.0 introduced a full theming layer (--base-* cascade + --sw-* per-instance overrides). See the dedicated Theming page for the live preset gallery.

MultiSwitch-specific variables added in 2.0:

--sw-step-bg / --sw-step-bg-active — step segment surfaces
--sw-label-color / --sw-label-active-color — label colours
--sw-label-hover-bg / --sw-label-hover-bg-active — clickable label hover

♿ Accessibility

Built-in Features

✅ Keyboard navigation (Arrow keys, Home, End)
✅ Per-step labels are real <button>s
✅ Focus ring with theme-aware colour
✅ ARIA role + aria-selected
✅ Disabled state handling