Skip to content
Browse documentation
whisk/ui

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.

Coming from another library?
Use 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

View
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.

Default view
Colored view
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.

Small
Medium
Large
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.

Report 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.

Project view
Atlas
Beacon
Cascade
Delta
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.

Time range
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.

Page layout
Choose how project items appear.
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.

Editor layout
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.

Project visibility
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.

Plan
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.

Layout
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.

Layout
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.

Default view
Managed by your organization.
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.

Report format
CSV export isn't available for this 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

PropTypeDefaultDescription
optionsreadonly SegmentedControlOption[]noneProvide unique, nonempty values and labels. An icon is decorative; every option still needs a label.
valuestringnoneControl the selected option. Do not provide defaultValue at the same time.
defaultValuestringnoneInitialize the selected option without controlling later changes.
onValueChange(value: string) => voidnoneReceive a newly selected enabled value so the application can update its state.
labelReactNodenoneName the related set of options.
descriptionReactNodenoneAdd context for the whole choice.
errorReactNodenoneShow validation or server feedback when the control is invalid.
namestringgenerated group IDName the selected native radio for form submission.
formstringnoneAssociate the group with a native form by ID.
requiredbooleanfalseRequire one selection before native form submission.
variantdefault | coloreddefaultChoose the visual treatment.
sizesm | md | lgmdChoose the control density.
itemContenttext | icon | iconTexttextShow text, a decorative icon, or both without changing the option's accessible name.
orientationhorizontal | verticalhorizontalArrange the options in a row or column.
layouthug | fillhugKeep options content-sized or divide the available width equally.
disabledbooleanfalseDisable every option in the group.
readOnlybooleanfalseKeep the current selection visible without allowing changes.
invalidbooleanfalseExpose invalid state and associate the error when present.

Shared props

PropSupportedNotes
as / asChildNoSegmentedControl owns its native fieldset and radio items.
Style propsNoSegmentedControl exposes its documented appearance props instead. See Style props.
className / styleYesApplied to the native fieldset.
refYesForwards to the native fieldset.
Native HTML attributesYesNative fieldset attributes are forwarded, except semantics that SegmentedControl owns.

Option shape

PropTypeDefaultDescription
valuestringrequiredUnique, nonempty submitted value.
labelstringrequiredVisible option name and accessible name, including for icon-only options.
iconReactNodenoneDecorative, noninteractive icon content.
disabledbooleanfalseKeep an unavailable option visible but prevent selection.

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.

DoDon't
List, BoardShow list, Switch to board