Segmented Control

A linear set of two or more segments, each of which functions as a mutually exclusive button. Use this when you want users to switch between different views or modes.

Use Tabs when each option leads to distinct content in its own panel.

#Example

#Usage

#Variants

There are two variants, rectangular (default) and pill.

#Sizes

The Segmented Control comes in two sizes: md (32px, default) and lg (40px).

#Widths

The Segmented Control comes in two widths: fit-content (default) and 100%.

#Disabled

Set isDisabled on the <SegmentedControl /> to disable all options.

Or set isDisabled on a specific <SegmentedControlOption />. You can use the tooltip prop to explain why an option is disabled.

#With Complex Values

Just like the RadioGroup, the SegmentedControl supports generic types for values (numbers, objects, etc).

#Icons

Use the icon prop on SegmentedControlOption to display an icon before the label.

Icon-only options work well for compact controls. Omit the label prop to show only the icon. Always provide an aria-label for accessibility when there is no visible text.

#Custom Children and Icons

You can pass an icon or children to SegmentedControlOption to render more complex layouts.

#Guidelines

#When to use

• When each option is a different view or lens on the same content, and the user is choosing how the content renders rather than what to look at. For example, switching a report between list, table, and heatmap views, or a chart between daily, weekly, and monthly granularity.
• When switching between options is instant and low-cost — no data is lost, no navigation occurs, and the user can flip back and forth freely.
• When the options are a small set (2–5) of mutually exclusive settings with short labels.

#When not to use

• When each option leads to distinct content sectioned into its own panel (for example, "Overview" vs. "Messages" vs. "Configuration"). Use Tabs instead — the user is choosing what to look at, not how to look at it.
• When selecting an option navigates to a different URL. Use Tab Nav instead.
• When options need decorators such as counts, badges, or status indicators. Use Tabs, which supports these.
• When there is a single on/off setting. Use a Switch or Checkbox instead.
• When there are more than 5 options, or options have long labels or descriptions. Use a Select or Radio group instead.
• As part of a form where the selection is submitted as data. Use a Radio group inside a Form Field instead.

#Content

• Use sentence case for option labels.
• Keep labels short (1–2 words) and parallel in structure, since all options render side by side.
• Icon-only options must have an aria-label.

#Accessibility

Segmented Control is semantically a radio group styled as buttons — not a tab list. Screen readers announce it as a set of mutually exclusive options rather than as navigable tabs with associated panels. This is the desired behavior when options are views or modes on the same content; if your options control distinct panels of content, use Tabs so assistive technology can communicate the tab/panel relationship.

#Props

#SegmentedControl

Name	Default	Description
value	—	T The value of the segmented control.
onChange	—	(value: T) => void Callback called when the value changes.
isDisabled	—	boolean If true, the segmented control will be disabled.
name	—	string The name of the input field in a form.
variant	—	SegmentedControlVariant Variants have different styling.
width	—	"fit-content" | "100%" By default, will be as small as possible
children	—	ReactNode The options to render.
size	—	"md" | "lg"

#SegmentedControlOption

Name	Default	Description
value	—	T The value of the option.
icon	—	ComponentType<SVGAttributes<SVGElement>> Icon displayed before the label.
status	—	"empty" | "success" | "error" The status of the option displayed as an icon.
isDisabled	—	boolean
tooltip	—	ReactNode Optional tooltip shown when hovering the option.
px	"md"	"sm" | "md" Horizontal padding of the option.
label	—	NonNullableReactNode
children	—	ReactNode | NonNullableReactNode
aria-label	—	string Accessible label for screen readers. Optional when visible text is provided via `label` or `children`.