SegmentedControl
Choose one visible option from a compact set.
Overview
SegmentedControl keeps a small set of mutually exclusive choices visible. It uses RadioGroup semantics, while application code owns what the selected value changes.
options, not children. Use onValueChange, not onChange; use Tabs, not SegmentedControl, to control panels.Use when
A small set of mutually exclusive options should remain visible.
Use instead
Use Radio when options need descriptions or longer labels. Use Switch for on/off. Use ButtonGroup for actions.
Usage
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
name="view"
label="View"
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>Examples
Variants
Use default for a quiet local choice and colored when the selection needs more emphasis.
import { SegmentedControl, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={4}>
<SegmentedControl
label="Default view"
variant="default"
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>
<SegmentedControl
label="Colored view"
variant="colored"
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>
</Stack>Sizes
Match the control size to the density of the surrounding interface.
import { SegmentedControl, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={4}>
<SegmentedControl
label="Small"
size="sm"
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>
<SegmentedControl
label="Medium"
size="md"
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>
<SegmentedControl
label="Large"
size="lg"
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>
</Stack>Forms
Use react-hook-form with value and onValueChange to read the selected export format.
import { useState } from "react";
import { Controller, useForm } from "react-hook-form";
import { Box, Button, SegmentedControl, Stack, Text } from "@smoothie-framework/whisk-react";
type ReportValues = { reportFormat: string };
export function ReportFormatForm() {
const [status, setStatus] = useState<string>();
const { control, handleSubmit } = useForm<ReportValues>({
defaultValues: { reportFormat: "pdf" },
});
const onSubmit = (values: ReportValues) => {
setStatus(`Exporting as ${values.reportFormat.toUpperCase()}.`);
};
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Controller
name="reportFormat"
control={control}
render={({ field }) => (
<SegmentedControl
label="Report format"
name={field.name}
value={field.value}
onValueChange={field.onChange}
options={[
{ value: "pdf", label: "PDF" },
{ value: "csv", label: "CSV" },
]}
/>
)}
/>
<Button type="submit">Export report</Button>
{status ? <Text color="subtle" aria-live="polite">{status}</Text> : undefined}
</Stack>
</Box>
);
}Controlled
Control the selection when it changes the visible content.
import { useState } from "react";
import { Box, Grid, SegmentedControl, Stack } from "@smoothie-framework/whisk-react";
const items = ["Atlas", "Beacon", "Cascade", "Delta"];
export function ProjectView() {
const [view, setView] = useState("list");
return (
<Stack gap={3}>
<SegmentedControl
label="Project view"
value={view}
onValueChange={setView}
options={[
{ value: "list", label: "List" },
{ value: "grid", label: "Grid" },
]}
/>
{view === "list" ? (
<Stack gap={2}>
{items.map((item) => (
<Box key={item} padding={3} background="surface2">{item}</Box>
))}
</Stack>
) : (
<Grid columns={2} gap={2}>
{items.map((item) => (
<Box key={item} padding={3} background="surface2">{item}</Box>
))}
</Grid>
)}
</Stack>
);
}Full width
Use fill layout when the choices should share their parent’s available width.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Time range"
layout="fill"
defaultValue="week"
options={[
{ value: "day", label: "Day" },
{ value: "week", label: "Week" },
{ value: "month", label: "Month" },
]}
/>Description
Add a description when people need context before making the choice.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Page layout"
description="Choose how project items appear."
defaultValue="list"
options={[
{ value: "list", label: "List" },
{ value: "grid", label: "Grid" },
]}
/>Vertical
Use vertical orientation when the choices belong in a narrow settings column.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Editor layout"
orientation="vertical"
defaultValue="split"
options={[
{ value: "split", label: "Split view" },
{ value: "preview", label: "Preview" },
]}
/>Disabled
Disable the whole group when the choice is unavailable.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Project visibility"
defaultValue="team"
disabled
options={[
{ value: "team", label: "Team" },
{ value: "private", label: "Private" },
]}
/>Disabled item
Disable an individual option when it is unavailable but should remain visible.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Plan"
defaultValue="starter"
options={[
{ value: "starter", label: "Starter" },
{ value: "enterprise", label: "Enterprise", disabled: true },
]}
/>Icon only
Prefer Icon text unless the icons are universally recognised; icon-only options keep their label as the accessible name.
import { GridIcon, ListIcon } from "@smoothie-framework/whisk-react/icons";
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Layout"
itemContent="icon"
defaultValue="list"
options={[
{ value: "list", label: "List", icon: <ListIcon size="sm" aria-hidden /> },
{ value: "grid", label: "Grid", icon: <GridIcon size="sm" aria-hidden /> },
]}
/>Icon text
Use an icon and text together when the icon makes the familiar option quicker to scan.
import { GridIcon, ListIcon } from "@smoothie-framework/whisk-react/icons";
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Layout"
itemContent="iconText"
defaultValue="list"
options={[
{ value: "list", label: "List", icon: <ListIcon size="sm" aria-hidden /> },
{ value: "grid", label: "Grid", icon: <GridIcon size="sm" aria-hidden /> },
]}
/>Read-only
Use readOnly when the selected view is visible but managed elsewhere.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Default view"
description="Managed by your organization."
defaultValue="board"
readOnly
options={[
{ value: "list", label: "List" },
{ value: "board", label: "Board" },
]}
/>Invalid
Show a server-side error when a selected option is unavailable for the current report.
import { SegmentedControl } from "@smoothie-framework/whisk-react";
<SegmentedControl
label="Report format"
defaultValue="csv"
invalid
error="CSV export isn't available for this report."
options={[
{ value: "pdf", label: "PDF" },
{ value: "csv", label: "CSV" },
]}
/>Props
Component props
Shared props
Option shape
Accessibility
SegmentedControl renders a labelled native radio group. Tab focuses the selected option, or the first option when none is selected; Arrow keys move and select choices in the group. Use Tabs when the choice switches related panels. Prefer Icon text unless the icons are universally recognised; icon-only options keep their label as the accessible name.
Content guidance
Keep it to 2–5 options with similar-length labels. Name each state, not the action someone takes to reach it.