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
NameTypeDefaultDescription
id required text Unique identifier for the control.
value bindable discriminated-union Currently selected value.
label required text Accessible label for the group.
name text Native form field name. Renders hidden input(s) carrying the selected value(s).
labelVisible boolean true Whether the label is visibly rendered. Set false to visually hide it while keeping it available to assistive technology.
disabled boolean 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 false Render segments as detached individual buttons instead of a unified strip.
fullWidth boolean 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".
selectionRequired discriminated-union true When true, clicking the already-selected option is a no-op. When false, clicking the selected option clears value to undefined.
onValueChange ((value: T) => void) | undefined Called when the selected value changes (single mode only).
children required snippet Child <Segment> elements.