Inputs@knitui/components

SegmentedControl

SegmentedControl is a single-select row (or column) of mutually-exclusive options. The active option sits on a raised indicator over a muted track. Accent follows the active theme via the theme prop.

WebiOSAndroid3 style slots11 own props12 examples

Stories Source Tests Open in Storybook

import { SegmentedControl } from "@knitui/components";

Playground

Loading playground…

sizeControls height, horizontal padding and font size.

orientationLayout direction of the segments.

shadowElevation — drop shadow from the shared ladder.

fullWidth

false

disabled

false

readOnly

false

withItemsBorders

true

themeActive theme accent — recolors the control via the palette ramp.

Playground

<SegmentedControl
  data={["React", "Vue", "Svelte"]}
  size="sm"
  orientation="horizontal"
  fullWidth={false}
  disabled={false}
  readOnly={false}
  withItemsBorders
/>

Examples

Sizes

The seven token sizes, from xxs to xxl.

Loading example…

SizesSource Storybook

Shadows

The five shadow levels from the shared elevation ladder, from xs to xl.

Loading example…

ShadowsSource Storybook

Disabled

Disabled state — the whole control becomes non-interactive with reduced opacity.

Loading example…

DisabledSource Storybook

Disabled Item

A single item can be disabled while the rest remain interactive.

Loading example…

Disabled ItemSource Storybook

Read Only

Read-only mode — the selected value is visible but cannot be changed.

Loading example…

Read OnlySource Storybook

Vertical

Vertical orientation — segments stack top-to-bottom.

Loading example…

VerticalSource Storybook

Controlled

Controlled value — the parent owns the state; selection triggers the callback.

Loading example…

ControlledSource Storybook

Full Width

Full-width mode — the control stretches to fill the container.

Loading example…

Full WidthSource Storybook

Rich Labels

Segments can accept arbitrary React nodes as labels, e.g. icons with text.

Loading example…

Rich LabelsSource Storybook

Themed

The palette ramp follows the active theme — same control, different accent.

Loading example…

ThemedSource Storybook

Styles

Per-slot styles targets individual parts — here the root track and the label.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`data` required	`(string \| SegmentedControlItem)[]`	—	Options to render — bare strings or `{ value, label, disabled }`.
`autoContrast`	`boolean \| undefined`	—	Accepted for API parity; ramp already contrasts, so this is a no-op.
`defaultValue`	`string \| undefined`	—	Uncontrolled initial value.
`disabled` system	`boolean \| undefined`	`false`	Disable the whole control.
`fullWidth` system	`boolean \| undefined`	`false`	Stretch to fill the parent's width.
`name`	`string \| undefined`	—	Accessibility group name (parity).
`onChange`	`((value: string) => void) \| undefined`	—	Called when the selected value changes.
`orientation`	`SegmentedControlOrientation \| undefined` horizontal · vertical	`"horizontal"`	Layout direction of the segments.
`radius` system	`string \| number \| undefined`	—
`readOnly`	`boolean \| undefined`	`false`	Prevent changing the value (still selectable for display).
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` unset · xs · sm · md · lg · xl	—	Elevation — drop shadow from the shared ladder.
`size` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` xxs · xs · sm · md · lg · xl · xxl	`"md"`	Controls height, horizontal padding and font size.
`styles` system	`SlotStyles<SegmentedControlSlots> \| undefined`	—	Uniform per-slot style passthrough — sugar over the parts. Slots: `root` / `control` / `label`. Lowest precedence: explicit props on the parts win.
`theme` system	`ThemeName \| null \| undefined` unset · blue · red · green · yellow · pink · gray	—	Active theme accent — recolors the control via the palette ramp.
`transitionDuration`	`number \| undefined`	`200`	Indicator slide duration in ms.
`transitionTimingFunction`	`string \| undefined`	`"ease"`	Indicator slide easing (`"ease"`, `"linear"`, `"ease-in-out"`, …).
`value`	`string \| undefined`	—	Controlled value.
`withItemsBorders`	`boolean \| undefined`	`true`	Draw thin separators between items.

Style slots

Every part of SegmentedControl can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`control`	`styles={{ control: { … } }}`
`label`	`styles={{ label: { … } }}`
`root`	`styles={{ root: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 497 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.