- Accordion
- Alert
- Alert Dialog
- Autocomplete
- Avatar
- Badge
- Breadcrumb
- Button
- Calendar
- Card
- Checkbox
- Checkbox Group
- Collapsible
- Combobox
- ComposerNew
- Command
- Context Menu
- Date Picker
- Dialog
- Drawer
- Empty
- Field
- Fieldset
- Form
- Frame
- Group
- Input
- Input Group
- Kbd
- Label
- Menu
- Meter
- Number Field
- OTP Field
- Pagination
- Popover
- Preview Card
- Progress
- Radio Group
- Scroll Area
- Select
- Segmented Control
- Separator
- Sheet
- Skeleton
- Slider
- Spinner
- Switch
- Table
- Tabs
- Textarea
- Toast
- Toggle
- Toggle Group
- Toolbar
- Tooltip
Segmented Control
A visual pattern for presenting related choices, navigation destinations, filters, or content views.
"use client";
import {
RadioGroupPrimitive,
RadioPrimitive,
} from "@/components/ui/radio-group";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
export default function Particle() {
return (
<SegmentedControl
aria-label="Billing period"
render={<RadioGroupPrimitive defaultValue="monthly" />}
>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="monthly" />}
>
Monthly
</SegmentedControlItem>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="yearly" />}
>
Yearly
</SegmentedControlItem>
</SegmentedControl>
);
}
About
A segmented control is a visual pattern, not a standalone behavior. SegmentedControl and SegmentedControlItem provide the presentation and the sliding indicator; the element you pass to render provides the semantics, keyboard interactions, and state model.
Choose the right primitive
| Intent | Use | Why |
|---|---|---|
| Choose one value in a form | Radio Group | Represents a mutually exclusive value and participates in form state. |
| Navigate to another URL or route | Navigation links | Preserves link behavior, browser history, and aria-current. |
| Apply an exclusive filter or mode | Toggle Group | Represents the pressed state of an action that may be cleared. |
| Switch between related panels | Tabs | Connects each tab to an associated content panel. |
Choose the primitive from the interaction first, then render it through the segmented control. Visual similarity alone is not a reason to use Tabs or Toggle Group.
Installation
pnpm dlx shadcn@latest add @coss/segmented-control
Usage
import {
RadioGroupPrimitive,
RadioPrimitive,
} from "@/components/ui/radio-group"
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control"<SegmentedControl
aria-label="Billing period"
render={<RadioGroupPrimitive defaultValue="monthly" />}
>
<SegmentedControlItem render={<RadioPrimitive.Root value="monthly" />}>
Monthly
</SegmentedControlItem>
<SegmentedControlItem render={<RadioPrimitive.Root value="yearly" />}>
Yearly
</SegmentedControlItem>
</SegmentedControl>Put behavior props such as defaultValue, value, onValueChange, or href on the element passed to render. Use the Radio Group primitives rather than RadioGroup and Radio, so the native radio indicator is not rendered.
The same composition works for navigation links:
<SegmentedControl aria-label="Project sections" render={<nav />}>
<SegmentedControlItem render={<a aria-current="page" href="/overview" />}>
Overview
</SegmentedControlItem>
<SegmentedControlItem render={<a href="/activity" />}>
Activity
</SegmentedControlItem>
</SegmentedControl>And for an exclusive filter that may be cleared:
<SegmentedControl render={<ToggleGroupPrimitive aria-label="Status" />}>
<SegmentedControlItem render={<TogglePrimitive value="open" />}>
Open
</SegmentedControlItem>
<SegmentedControlItem render={<TogglePrimitive value="closed" />}>
Closed
</SegmentedControlItem>
</SegmentedControl>API Reference
SegmentedControl
The segmented surface. Renders a <div> by default and appends the sliding indicator after its children. Provides the size to its items via context.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "default" | "lg" | "default" | Controls the height and horizontal padding of every item |
render | ReactElement | function | — | Replaces the rendered element, for example with a Radio Group primitive or <nav /> |
SegmentedControlItem
A single segment. Renders a <button type="button"> by default.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "sm" | "default" | "lg" | Inherited from root | Overrides the size inherited from SegmentedControl |
render | ReactElement | function | — | Replaces the rendered element, for example with a radio or a link |
An item is active when it has data-checked (Radio Group), aria-current="page" (links), or data-pressed (Toggle Group). The indicator slides to the active item over 200ms with an ease-in-out curve, stays still when the user prefers reduced motion, and is hidden when no item is active. Before hydration or without JavaScript, the active item paints its own static pill instead. For navigation, the pill animates only when the control persists across route changes, such as in a shared layout; otherwise it appears in place on each page.
At the outside edges, the item padding and the surface’s inset combine to match the horizontal padding of the corresponding Button size. The surface is slightly taller than that Button to optically balance its inset selected item when the controls appear next to each other.
Examples
Small Radio Group
"use client";
import {
RadioGroupPrimitive,
RadioPrimitive,
} from "@/components/ui/radio-group";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
export default function Particle() {
return (
<SegmentedControl
aria-label="Billing period"
render={<RadioGroupPrimitive defaultValue="monthly" />}
size="sm"
>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="monthly" />}
>
Monthly
</SegmentedControlItem>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="yearly" />}
>
Yearly
</SegmentedControlItem>
</SegmentedControl>
);
}
Default Radio Group
"use client";
import {
RadioGroupPrimitive,
RadioPrimitive,
} from "@/components/ui/radio-group";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
export default function Particle() {
return (
<SegmentedControl
aria-label="Billing period"
render={<RadioGroupPrimitive defaultValue="monthly" />}
>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="monthly" />}
>
Monthly
</SegmentedControlItem>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="yearly" />}
>
Yearly
</SegmentedControlItem>
</SegmentedControl>
);
}
Large Radio Group
"use client";
import {
RadioGroupPrimitive,
RadioPrimitive,
} from "@/components/ui/radio-group";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
export default function Particle() {
return (
<SegmentedControl
aria-label="Billing period"
render={<RadioGroupPrimitive defaultValue="monthly" />}
size="lg"
>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="monthly" />}
>
Monthly
</SegmentedControlItem>
<SegmentedControlItem
className="grow"
render={<RadioPrimitive.Root value="yearly" />}
>
Yearly
</SegmentedControlItem>
</SegmentedControl>
);
}
Small Navigation
"use client";
import { useState } from "react";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
const links = [
{ href: "#overview", label: "Overview" },
{ href: "#activity", label: "Activity" },
{ href: "#settings", label: "Settings" },
];
export default function Particle() {
const [current, setCurrent] = useState("#overview");
return (
<SegmentedControl aria-label="Project sections" render={<nav />} size="sm">
{links.map((link) => (
<SegmentedControlItem
key={link.href}
render={
// biome-ignore lint/a11y/useAnchorContent: SegmentedControlItem supplies the link content through the render prop.
<a
aria-current={link.href === current ? "page" : undefined}
href={link.href}
onClick={() => setCurrent(link.href)}
/>
}
>
{link.label}
</SegmentedControlItem>
))}
</SegmentedControl>
);
}
Default Navigation
"use client";
import { useState } from "react";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
const links = [
{ href: "#overview", label: "Overview" },
{ href: "#activity", label: "Activity" },
{ href: "#settings", label: "Settings" },
];
export default function Particle() {
const [current, setCurrent] = useState("#overview");
return (
<SegmentedControl aria-label="Project sections" render={<nav />}>
{links.map((link) => (
<SegmentedControlItem
key={link.href}
render={
// biome-ignore lint/a11y/useAnchorContent: SegmentedControlItem supplies the link content through the render prop.
<a
aria-current={link.href === current ? "page" : undefined}
href={link.href}
onClick={() => setCurrent(link.href)}
/>
}
>
{link.label}
</SegmentedControlItem>
))}
</SegmentedControl>
);
}
Large Navigation
"use client";
import { useState } from "react";
import {
SegmentedControl,
SegmentedControlItem,
} from "@/components/ui/segmented-control";
const links = [
{ href: "#overview", label: "Overview" },
{ href: "#activity", label: "Activity" },
{ href: "#settings", label: "Settings" },
];
export default function Particle() {
const [current, setCurrent] = useState("#overview");
return (
<SegmentedControl aria-label="Project sections" render={<nav />} size="lg">
{links.map((link) => (
<SegmentedControlItem
key={link.href}
render={
// biome-ignore lint/a11y/useAnchorContent: SegmentedControlItem supplies the link content through the render prop.
<a
aria-current={link.href === current ? "page" : undefined}
href={link.href}
onClick={() => setCurrent(link.href)}
/>
}
>
{link.label}
</SegmentedControlItem>
))}
</SegmentedControl>
);
}
Related content
Use Tabs when each segment controls an associated content panel. Tabs keep Base UI’s own indicator and add orientation support and panel semantics, but share the segmented control’s sizes, icon layout, and indicator surface so both look the same.
Tab 1 content
import { Tabs, TabsList, TabsPanel, TabsTab } from "@/components/ui/tabs";
export default function Particle() {
return (
<Tabs defaultValue="tab-1">
<TabsList>
<TabsTab value="tab-1">Tab 1</TabsTab>
<TabsTab value="tab-2">Tab 2</TabsTab>
<TabsTab value="tab-3">Tab 3</TabsTab>
</TabsList>
<TabsPanel value="tab-1">
<p className="p-4 text-center text-muted-foreground text-xs">
Tab 1 content
</p>
</TabsPanel>
<TabsPanel value="tab-2">
<p className="p-4 text-center text-muted-foreground text-xs">
Tab 2 content
</p>
</TabsPanel>
<TabsPanel value="tab-3">
<p className="p-4 text-center text-muted-foreground text-xs">
Tab 3 content
</p>
</TabsPanel>
</Tabs>
);
}
Changelog
- Oct 20, 2026 — Segmented control is now a component with a built-in sliding indicator