Forms

SegmentedControl

Compact segmented selector that surfaces a small fixed set of options as a connected bar, including bindable selections and route-backed links.

import { SegmentedControl } from '@lostgradient/cinder/segmented-control';
formselection
01

Overview

Compact segmented selector for a small fixed set of options, including bindable selections and route-backed navigation links.

Usage

svelte 
<script lang="ts">
  import { Segment } from '@lostgradient/cinder/segment';
  import SegmentedControl from '@lostgradient/cinder/segmented-control';
</script>

<SegmentedControl id="view-filter" label="View filter" variant="navigation">
  <Segment href="/costs?source=actual" current>Actual</Segment>
  <Segment href="/costs?source=forecast">Forecast</Segment>
</SegmentedControl>
Live preview
02

When to use

Use when
  • Choosing one of two to five mutually exclusive options that all fit on screen at once.
  • Picking a view filter where seeing every option beats hiding them inside a toggle or tabs control.
  • Rendering route-backed filters as real links with `variant="navigation"` and `Segment href`.
Avoid when
  • Toggling a single binary on or off — use toggle or checkbox instead.
  • Switching between panels of associated content — use tabs instead.
03

Examples

Basic segmented control

A compact radio-group control with keyboard navigation.

Multi-select segmented control

Multiple options can be toggled independently. Pass a SvelteSet to track selection.

Navigation route filters

Use the navigation variant with linked segments when each option should update the URL.

Sizing — size vs. toolbar density

Compares the three sizes (sm/md/lg) against `density="toolbar"`. Toolbar density resolves to the same compact visual size as `size="sm"` and ignores any explicit `size` value, so the toolbar-with-md and toolbar-with-lg controls render identically to the toolbar-without-size control and to `size="sm"`.

Tablist variant

The `variant="tablist"` treatment for picker-shaped controls that switch between externally owned panels. Unlike the default radiogroup, the tablist has no enclosing surface and marks the selected tab with an accent underline (horizontal) or inline-start bar (vertical). Each tab wires `aria-controls` to a panel rendered elsewhere in the layout. See docs/decisions/segmented-control-tablist-variant.md.

04

Props

Props for segmented-control
Name Type Default Required Bindable Description
id text req Unique identifier for the control.
value discriminated-union bind Currently selected value.
label text req Accessible label for the group.
name string | undefined Native form field name. Renders hidden input(s) carrying the selected value(s).
hideLabel boolean | undefined false Visually hide the label while keeping it available to assistive technology.
disabled boolean | undefined false Disable the whole control.
size 'sm' | 'md' | 'lg' | undefined 'md' Requested visual size of the control. Defaults to "md". The resolved size is reflected as data-cinder-size on the root; when density="toolbar" is set, the resolved size is forced to "sm" and any explicit size value is ignored. size="md" option text uses --cinder-text-sm; size="sm" and density="toolbar" use --cinder-text-xs; size="lg" uses --cinder-text-sm.
density 'toolbar' | undefined Opt the control into compact toolbar sizing so it lines up cleanly with sibling Button (size="sm"), Chip (density="toolbar"), and other toolbar elements. Toolbar density resolves to the compact "sm" font and padding scale — when set, any explicit size value is ignored and the resolved size (data-cinder-size) is "sm" — while pinning the option min-block-size to --cinder-control-height-sm so the bounding height matches sibling toolbar controls.
orientation 'horizontal' | 'vertical' | undefined 'horizontal' Layout orientation.
detached boolean | undefined false Render segments as detached individual buttons instead of a unified strip.
fullWidth boolean | undefined false Stretch the control to fill available width.
variant 'radiogroup' | 'tablist' | 'navigation' | undefined 'radiogroup' ARIA interaction pattern. Use navigation for route-backed links.
selectionMode discriminated-union 'single' Selection mode. "single" allows exactly one segment to be selected at a time; "multiple" allows any number of segments to be selected simultaneously. Default "single".
disallowEmptySelection discriminated-union true When true (default), clicking the already-selected option is a no-op. When false, clicking the selected option clears value to undefined.
onchange ((value: T) => void) | undefined Called when the selected value changes (single mode only).
children snippet req Child <Segment> elements.