# SegmentedControl

Page: /docs/components/segmented-control

{/* Figma: Meridian → SegmentedControl (docs 29:38, component set 17:7584). Spec: docs/design-system/meridian/segmented-control.md */}

Switches between two to four views or modes in place. The selected segment lifts out of a soft tray, at the same heights as Button. On the site it toggles pricing periods, map and list views, and product tabs inside a section.

```tsx
import { SegmentedControl } from "@commenda/meridian/ui/segmented-control";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

const opts = (...labels: string[]) =>
	labels.map((label) => ({ value: label.toLowerCase(), label }));

export function SegmentedOptions() {
	return (
		<Stage>
			<SegmentedControl
				label="Billing period"
				options={opts("Monthly", "Annually")}
				defaultValue="monthly"
			/>
			<SegmentedControl label="Country" options={opts("US", "UK", "India")} defaultValue="us" />
			<SegmentedControl
				label="Product"
				options={opts("Sales tax", "VAT", "GST", "Payroll")}
				defaultValue="sales tax"
			/>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { SegmentedControl } from "@commenda/meridian/ui/segmented-control";

<SegmentedControl
  label="Billing period"
  value={period}
  onValueChange={setPeriod}
  options={[
    { value: "monthly", label: "Monthly" },
    { value: "annually", label: "Annually" },
  ]}
/>;
```

## Two to four options [#two-to-four-options]

Equal-weight choices that change what the section shows, with one always selected.

```tsx
import { SegmentedControl } from "@commenda/meridian/ui/segmented-control";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

const opts = (...labels: string[]) =>
	labels.map((label) => ({ value: label.toLowerCase(), label }));

export function SegmentedOptions() {
	return (
		<Stage>
			<SegmentedControl
				label="Billing period"
				options={opts("Monthly", "Annually")}
				defaultValue="monthly"
			/>
			<SegmentedControl label="Country" options={opts("US", "UK", "India")} defaultValue="us" />
			<SegmentedControl
				label="Product"
				options={opts("Sales tax", "VAT", "GST", "Payroll")}
				defaultValue="sales tax"
			/>
		</Stage>
	);
}
```

## With icons [#with-icons]

A 16 icon before the label, or icons alone for a view toggle. Icon-only segments need a Tooltip.

```tsx
import { SegmentedControl } from "@commenda/meridian/ui/segmented-control";
import { Globe01Icon } from "@commenda/pathfinder/icons/Globe01Icon";
import { Grid01Icon } from "@commenda/pathfinder/icons/Grid01Icon";
import { TableIcon } from "@commenda/pathfinder/icons/TableIcon";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

export function SegmentedIcons() {
	return (
		<Stage>
			<SegmentedControl
				label="View"
				defaultValue="map"
				options={[
					{ value: "map", label: "Map", leadingIcon: <Globe01Icon /> },
					{ value: "list", label: "List", leadingIcon: <TableIcon /> },
				]}
			/>
			<SegmentedControl
				label="Layout"
				defaultValue="grid"
				options={[
					{ value: "grid", label: "Grid view", iconOnly: true, leadingIcon: <Grid01Icon /> },
					{ value: "table", label: "Table view", iconOnly: true, leadingIcon: <TableIcon /> },
				]}
			/>
		</Stage>
	);
}
```

## Sizes [#sizes]

sm 28 and md 32, the same heights as Button so they line up in a row.

```tsx
import { SegmentedControl } from "@commenda/meridian/ui/segmented-control";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

const opts = (...labels: string[]) =>
	labels.map((label) => ({ value: label.toLowerCase(), label }));

export function SegmentedSizes() {
	return (
		<Stage>
			<Labelled label="sm · 28">
				<SegmentedControl
					label="Country"
					size="sm"
					options={opts("US", "UK", "India")}
					defaultValue="us"
				/>
			</Labelled>
			<Labelled label="md · 32">
				<SegmentedControl
					label="Country"
					size="md"
					options={opts("US", "UK", "India")}
					defaultValue="us"
				/>
			</Labelled>
		</Stage>
	);
}
```

## Segment states [#segment-states]

Hover fills the segment soft-pearl 300. Focus is the blue ring with a white gap. Disabled dims the label.

```tsx
import { SegmentedControl } from "@commenda/meridian/ui/segmented-control";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

const opts = (...labels: string[]) =>
	labels.map((label) => ({ value: label.toLowerCase(), label }));

export function SegmentedStates() {
	return (
		<Stage>
			<Labelled label="one segment disabled">
				<SegmentedControl
					label="Country"
					defaultValue="us"
					options={[
						...opts("US", "UK"),
						{ value: "india", label: "India", disabled: true, disabledReason: "Coming soon" },
					]}
				/>
			</Labelled>
			<Labelled label="whole control disabled">
				<SegmentedControl
					label="Country"
					disabled
					options={opts("US", "UK", "India")}
					defaultValue="us"
				/>
			</Labelled>
		</Stage>
	);
}
```

Hover and Tab through the controls above to see hover and focus.

## Anatomy [#anatomy]

| Part | Value |
| --- | --- |
| Tray | soft-pearl 200, 0.5 hairline soft-pearl 300, radius 8, 2 padding and 2 between segments |
| Segment | radius 6 so the corners nest, padding 8 (sm) or 12 (md), Label/13 Strong, optional 16 icon 6 before it |
| Selected | white, hairline, Elevation/control |
| Height | sm 28 · md 32 (`control/md`) |

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `options` (required) | `SegmentedControlOption[]` |  |
| `style` | `CSSProperties \| ((state: RadioGroupState) => CSSProperties \| undefined)` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `form` | `string` | Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form. |
| `disabled` | `boolean` | Whether the component should ignore user interaction. |
| `name` | `string` | Identifies the field when a form is submitted. |
| `readOnly` | `boolean` | Whether the user should be unable to select a different radio button in the group. |
| `required` | `boolean` | Whether the user must choose a value before submitting a form. |
| `inputRef` | `((instance: HTMLInputElement \| null) => void \| (() => VoidOrUndefinedOnly) \| DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) \| RefObject<HTMLInputElement \| null>` | A ref to access the hidden input element. |
| `size` | `"md" \| "sm"` |  |
| `className` | `string` |  |
| `disabledReason` | `string` |  |
| `value` (conditional) | `string` |  |
| `onValueChange` (conditional) | `(value: string) => void` |  |
| `defaultValue` (conditional) | `string` |  |

## Best practices [#best-practices]

- Use a SegmentedControl for two to four short, equal options that switch the view in place. More options, or sections with their own content, use Tabs.
- One segment is always selected. There is no empty state. Changing it updates the view at once, with no Apply.
- Keep labels to one or two words, and similar in length. Icon-only segments need a Tooltip and an aria-label.
- Never use a segment for an action. It never submits a form or opens a demo booking. For on or off, use a Switch.
- Source: Pathfinder SegmentedControl. Meridian keeps it as is.
