SegmentController

A pill-shaped segmented control with an animated sliding indicator. Supports single-select and multi-select modes.

Import

tsx

import { SegmentController } from '@tac-ui/web';

Default

A basic single-select segmented control that uses a spring-animated sliding background to indicate the active segment. The first option is selected by default.

tsx

<SegmentController options={[
  { value: 'all', label: 'All' },
  { value: 'active', label: 'Active' },
  { value: 'inactive', label: 'Inactive' },
]} />

Sizes

Three size variants — sm (h-8), md (h-10), and lg (h-12) — adjust the height, padding, and font size of the control.

tsx

<SegmentController options={options} size="sm" />
<SegmentController options={options} size="md" />
<SegmentController options={options} size="lg" />

With Icons

Pass an icon node in each option to render it inline before the label text, sized to 16×16px automatically.

tsx

<SegmentController options={[
  { value: 'grid', label: 'Grid', icon: <Grid3X3 size={14} /> },
  { value: 'list', label: 'List', icon: <List size={14} /> },
  { value: 'board', label: 'Board', icon: <LayoutGrid size={14} /> },
]} />

Multi Select

Set mode to multi to allow toggling multiple segments independently. Each active segment shows a checkmark icon with a scale animation.

tsx

<SegmentController mode="multi" options={[
  { value: 'bold', label: 'Bold', icon: <Bold size={14} /> },
  { value: 'italic', label: 'Italic', icon: <Italic size={14} /> },
  { value: 'underline', label: 'Underline', icon: <Underline size={14} /> },
]} defaultValue={['bold', 'italic']} />

Multi Select (Controlled)

Multi-select mode also supports controlled usage — pass a string array as value and receive the updated array in onChange.

Selected: bold

tsx

const [value, setValue] = useState(['bold']);
<SegmentController mode="multi" options={options} value={value} onChange={setValue} />

Full Width

The fullWidth prop makes each segment flex-grow to fill the available container width equally.

tsx

<SegmentController options={options} fullWidth />

Disabled Options

Individual options can be disabled by setting disabled: true on the option object, rendering them at reduced opacity and blocking interaction.

tsx

<SegmentController options={[
  { value: 'daily', label: 'Daily' },
  { value: 'weekly', label: 'Weekly' },
  { value: 'monthly', label: 'Monthly', disabled: true },
]} />

Disabled

The disabled prop disables the entire control, reducing its opacity to 50% and blocking all pointer and keyboard interactions.

tsx

<SegmentController options={options} disabled />

Collapsible

The collapsible prop shows only the selected option by default. On hover, the control smoothly expands to reveal all options with a spring animation.

tsx

<SegmentController
  options={[
    { value: 'light', label: '', icon: <Sun size={14} /> },
    { value: 'dark', label: '', icon: <Moon size={14} /> },
    { value: 'system', label: '', icon: <Monitor size={14} /> },
  ]}
  collapsible
  size="sm"
/>

Controlled

In controlled mode, pass value and onChange to manage selection state externally — useful for syncing the control with other UI state.

Selected: all

tsx

const [value, setValue] = useState('all');
<SegmentController options={options} value={value} onChange={setValue} />

API Reference

Prop	Type	Default	Description
options	SegmentOption[]	-	Array of segment options to render. Each option has value, label, optional icon, and optional disabled.
mode	"single" \| "multi"	"single"	Selection mode. Single-select uses a sliding indicator; multi-select allows toggling multiple options with check icons.
value	string \| string[]	-	Controlled selected value(s). String for single mode, string[] for multi mode.
defaultValue	string \| string[]	-	Initial value(s) for uncontrolled usage. Defaults to the first option in single mode.
onChange	(value: string \| string[]) => void	-	Called when selection changes. Receives string for single mode, string[] for multi mode.
size	"sm" \| "md" \| "lg"	"md"	Size variant affecting height and font size.
fullWidth	boolean	false	When true, segments expand equally to fill the container width.
disabled	boolean	false	Disables the entire control, blocking all interaction and reducing opacity.
collapsible	boolean	false	When true, only the selected option is visible; expands on hover to reveal all options.
className	string	-	Additional CSS class names applied to the root container.