# SegmentedControl (/components/segmented-control)

<ReferenceLinks
  links={[
    { label: "Source", href: meta.links.source, iconName: "code" },
    { label: "Stories", href: meta.links.stories },
  ]}
/>

<Stage code={"<SegmentedControl\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  aria-label=\"Chart view\"\n  value=\"list\"\n  onChange={() => {}}\n  items={[\n    { iconName: \"list\", value: \"list\", tooltip: \"List view\" },\n    { iconName: \"grid\", value: \"grid\", tooltip: \"Grid view\" },\n    { iconName: \"chartBar\", value: \"chart\", tooltip: \"Chart view\" },\n  ]}\n/>\n<SegmentedControl\n  variant=\"embossed\"\n  aria-label=\"Schema editor mode\"\n  value=\"builder\"\n  onChange={() => {}}\n  items={[\n    { label: \"Builder\", value: \"builder\" },\n    { label: \"JSON\", value: \"json\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      aria-label="Chart view"
      value="list"
      onChange={noop}
      items={[
        { iconName: "list", value: "list", tooltip: "List view" },
        { iconName: "grid", value: "grid", tooltip: "Grid view" },
        { iconName: "chartBar", value: "chart", tooltip: "Chart view" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      variant="embossed"
      aria-label="Schema editor mode"
      value="builder"
      onChange={noop}
      items={[
        { label: "Builder", value: "builder" },
        { label: "JSON", value: "json" },
      ]}
    />
  </DemoState>
</Stage>

## Installation [#installation]

1. Install the package.

```sh
npm install @hashintel/ds-components
```

2. Import the component.

```tsx
import { useState } from "react";

import { SegmentedControl } from "@hashintel/ds-components";

export const RunHistoryRange = () => {
  const [range, setRange] = useState("7d");

  return (
    <SegmentedControl
      aria-label="Time range"
      value={range}
      onChange={setRange}
      items={[
        { label: "24h", value: "24h" },
        { label: "7d", value: "7d" },
        { label: "30d", value: "30d" },
      ]}
    />
  );
};
```

### When to use [#when-to-use]

<DoList
  items={[
    "Use SegmentedControl to pick one of 2–5 closely related options that applies immediately: a view mode, a time range, a display density.",
    "Use it to switch between alternate views of the same data — a table, graph, or grid of the same entities.",
    "Use icon-only segments with tooltips in dense chrome such as toolbars and panel headers.",
  ]}
/>

### When not to use [#when-not-to-use]

<DontList
  items={[
    "Don't use it in forms where the choice needs validation or applies on submit — use RadioGroup, which supports required and invalid states.",
    "Don't use it to switch a single setting on or off — use Toggle.",
    "Don't use it for more than 5 options, or options with long labels — use Select.",
    "Don't use it to trigger actions — use Button, or ButtonGroup for a set of related actions.",
  ]}
/>

## Examples [#examples]

### Basic [#basic]

The control is always controlled: pass the selected `value` and update it from
`onChange` — there is no internal state or `defaultValue`. Each item pairs a
visible `label` with the `value` your state stores.

<Stage code={"<SegmentedControl\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
</Stage>

### Disabled [#disabled]

Set `disabled` on the control to lock the whole choice, or on one item to
remove a single option while the rest stay selectable. When you must disable a
segment, say why in its `tooltip` — a greyed option without explanation looks
broken.

<Stage code={"<SegmentedControl\n  disabled\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  aria-label=\"Chart view\"\n  value=\"line\"\n  onChange={() => {}}\n  items={[\n    { label: \"Line\", value: \"line\" },\n    { label: \"Bar\", value: \"bar\" },\n    {\n      label: \"Map\",\n      value: \"map\",\n      disabled: true,\n      tooltip: \"No location data\",\n    },\n  ]}\n/>"}>
  <SegmentedControl
    disabled
    aria-label="Entity view"
    value="table"
    onChange={noop}
    items={[
      { label: "Table", value: "table" },
      { label: "Graph", value: "graph" },
      { label: "Grid", value: "grid" },
    ]}
  />
  <DemoState>
    <SegmentedControl
      aria-label="Chart view"
      value="line"
      onChange={noop}
      items={[
        { label: "Line", value: "line" },
        { label: "Bar", value: "bar" },
        {
          label: "Map",
          value: "map",
          disabled: true,
          tooltip: "No location data",
        },
      ]}
    />
  </DemoState>
</Stage>

### Variants [#variants]

`default` fills the track and rings it with a hairline; `embossed` recesses the
track with an inset shadow and subtly raises the selected segment out of it.
Consider `embossed` inside dialogs and panels where the filled track adds too
much chrome.

<Stage code={"<SegmentedControl\n  variant=\"default\"\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  variant=\"embossed\"\n  aria-label=\"Schema editor mode\"\n  value=\"builder\"\n  onChange={() => {}}\n  items={[\n    { label: \"Builder\", value: \"builder\" },\n    { label: \"JSON\", value: \"json\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      variant="default"
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      variant="embossed"
      aria-label="Schema editor mode"
      value="builder"
      onChange={noop}
      items={[
        { label: "Builder", value: "builder" },
        { label: "JSON", value: "json" },
      ]}
    />
  </DemoState>
</Stage>

### Sizes [#sizes]

`md` is the default. Use `xxs`–`sm` in dense chrome such as toolbars and panel
headers, and `lg` where the switch is the main control on the page.

<Stage code={"<SegmentedControl\n  size=\"xxs\"\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  size=\"xs\"\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  size=\"sm\"\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  size=\"md\"\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>\n<SegmentedControl\n  size=\"lg\"\n  aria-label=\"Entity view\"\n  value=\"table\"\n  onChange={() => {}}\n  items={[\n    { label: \"Table\", value: \"table\" },\n    { label: \"Graph\", value: \"graph\" },\n    { label: \"Grid\", value: \"grid\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      size="xxs"
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      size="xs"
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      size="sm"
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      size="md"
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      size="lg"
      aria-label="Entity view"
      value="table"
      onChange={noop}
      items={[
        { label: "Table", value: "table" },
        { label: "Graph", value: "graph" },
        { label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
</Stage>

### Vertical layout [#vertical-layout]

Set `layout="vertical"` to stack segments when the control lives in a narrow
column, such as a properties panel.

<Stage code={"<SegmentedControl\n  layout=\"vertical\"\n  aria-label=\"Entity panel\"\n  value=\"properties\"\n  onChange={() => {}}\n  items={[\n    { label: \"Properties\", value: \"properties\" },\n    { label: \"Links\", value: \"links\" },\n    { label: \"History\", value: \"history\" },\n  ]}\n/>\n<SegmentedControl\n  layout=\"vertical\"\n  aria-label=\"Chart view\"\n  value=\"list\"\n  onChange={() => {}}\n  items={[\n    { iconName: \"list\", value: \"list\", tooltip: \"List view\" },\n    { iconName: \"grid\", value: \"grid\", tooltip: \"Grid view\" },\n    { iconName: \"chartBar\", value: \"chart\", tooltip: \"Chart view\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      layout="vertical"
      aria-label="Entity panel"
      value="properties"
      onChange={noop}
      items={[
        { label: "Properties", value: "properties" },
        { label: "Links", value: "links" },
        { label: "History", value: "history" },
      ]}
    />
  </DemoState>
  <DemoState>
    <SegmentedControl
      layout="vertical"
      aria-label="Chart view"
      value="list"
      onChange={noop}
      items={[
        { iconName: "list", value: "list", tooltip: "List view" },
        { iconName: "grid", value: "grid", tooltip: "Grid view" },
        { iconName: "chartBar", value: "chart", tooltip: "Chart view" },
      ]}
    />
  </DemoState>
</Stage>

### With icons [#with-icons]

Add `iconName` beside a label when the icon aids recognition. Give every
segment one or none — a mixed row reads unevenly.

<Stage code={"<SegmentedControl\n  aria-label=\"Entity view\"\n  value=\"list\"\n  onChange={() => {}}\n  items={[\n    { iconName: \"list\", label: \"List\", value: \"list\" },\n    { iconName: \"diagramProject\", label: \"Graph\", value: \"graph\" },\n    { iconName: \"grid\", label: \"Grid\", value: \"grid\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      aria-label="Entity view"
      value="list"
      onChange={noop}
      items={[
        { iconName: "list", label: "List", value: "list" },
        { iconName: "diagramProject", label: "Graph", value: "graph" },
        { iconName: "grid", label: "Grid", value: "grid" },
      ]}
    />
  </DemoState>
</Stage>

### Icon-only segments [#icon-only-segments]

Omit `label` to render an icon alone — right for tight toolbars. Every
icon-only segment needs a `tooltip`: it names the option on hover and focus,
and doubles as its accessible label.

<Stage code={"<SegmentedControl\n  aria-label=\"Chart view\"\n  value=\"list\"\n  onChange={() => {}}\n  items={[\n    { iconName: \"list\", value: \"list\", tooltip: \"List view\" },\n    { iconName: \"grid\", value: \"grid\", tooltip: \"Grid view\" },\n    { iconName: \"chartBar\", value: \"chart\", tooltip: \"Chart view\" },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      aria-label="Chart view"
      value="list"
      onChange={noop}
      items={[
        { iconName: "list", value: "list", tooltip: "List view" },
        { iconName: "grid", value: "grid", tooltip: "Grid view" },
        { iconName: "chartBar", value: "chart", tooltip: "Chart view" },
      ]}
    />
  </DemoState>
</Stage>

### Tooltips [#tooltips]

Any segment can take a `tooltip` for context beyond its label, with
`tooltipOptions` adjusting placement and timing. Tooltips open on hover and
keyboard focus after a slow delay, and stay open while arrow keys move the
selection.

<Stage code={"<SegmentedControl\n  aria-label=\"Type diff view\"\n  value=\"split\"\n  onChange={() => {}}\n  items={[\n    { label: \"Split\", value: \"split\", tooltip: \"Changes side by side\" },\n    {\n      label: \"Unified\",\n      value: \"unified\",\n      tooltip: \"Changes in one column\",\n    },\n  ]}\n/>"}>
  <DemoState>
    <SegmentedControl
      aria-label="Type diff view"
      value="split"
      onChange={noop}
      items={[
        { label: "Split", value: "split", tooltip: "Changes side by side" },
        {
          label: "Unified",
          value: "unified",
          tooltip: "Changes in one column",
        },
      ]}
    />
  </DemoState>
</Stage>

## Behavior [#behavior]

- The control is `width: fit-content` by default. Widen it via `className` and
  segments share the extra space equally; constrain it and labels ellipsize
  while icon-only segments stay square.
- There is no deselection: `onChange` only ever fires with a segment's value,
  so clicking the selected segment never empties the choice.

## Content [#content]

- Name the resulting view or option with nouns, 1–2 words: "Table", "Graph",
  "30d". Segments show state — they don't perform actions.
- Keep labels similar lengths so segments read as equal peers — one long label
  unbalances the whole control.
- Use one content type per control: all text, all icons, or all icon + text.
- Write icon-only tooltips as option names ("Line chart"), not instructions
  ("Switch to line chart").

## Accessibility [#accessibility]

SegmentedControl implements the
[WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/):
Tab moves into and out of the group, arrow keys move the selection.

### What SegmentedControl provides [#what-segmentedcontrol-provides]

- Each segment is a label wrapping a hidden radio input, so form association
  (`name`) and keyboard behavior are native.
- Icon-only segments take their accessible name from `tooltip`, falling back to
  the item's `value`.

### What you must do [#what-you-must-do]

- Label the group: pass `aria-label` — the segment labels alone don't say what the choice is.
- Give every icon-only segment a `tooltip`; the fallback accessible name is the
  raw `value` string, which rarely reads well.

## API reference [#api-reference]

### SegmentedControl [#segmentedcontrol]

<PropsTable
  of={SegmentedControl}
  defaults={{
    layout: '"horizontal"',
    variant: '"default"',
    size: '"md"',
    items: "[]",
  }}
/>

### SegmentedControlItem [#segmentedcontrolitem]

The shape of `items` entries. Each takes a `label`, an `iconName`, or both —
give icon-only segments a `tooltip`, which doubles as their accessible name.

<PropsTable of={SegmentedControlItemDoc} />
