# Segment

A single-select toggle group, like a compact tab bar, with a pill or a rounded-corner track.

- Category: Core Elements
- Page: https://wunderui.com/components/segment
- Tier: Free

## Install

```bash
npx wunderui-cli add segment
```

## Import

```tsx
import { Segment, SegmentOption, SegmentShape, SegmentSize } from "@/components/ui/segment"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Range() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

Expected result: You see a grey pill-shaped bar with Day, Week and Month, with Week selected in white. Click Month or arrow to it and the fill moves there.

## Usage

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      slide
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

## When to use

### Use Segment for

- Switching the view or scope of one piece of content: a period, a layout, a billing interval
- A choice between two to five short options that are all visible at once
- A control in a card, chart or table header that changes what is shown below it

### Use something else

- [Tabs](https://wunderui.com/components/tabs) for separate panels of content, each with its own heading or URL
- [Toggle](https://wunderui.com/components/toggle) for a single option that is on or off
- [Radio Button Group](https://wunderui.com/components/radio-button-group) for one choice in a form that is submitted with the rest of the fields
- [Checkbox Button Group](https://wunderui.com/components/checkbox-button-group) for a choice of several options at once

## Keyboard

The segment is one tab list with a single tab stop on the selected option. Arrow keys move and choose as they go, and with manual activation they only move focus while Enter or Space chooses.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the segment, onto the selected option (or onto the first enabled option when `value` matches none), and out of it again. The other options are not tab stops. |
| `ArrowRight` | Selects the next enabled option and moves focus to it. From the last option it wraps to the first. |
| `ArrowLeft` | Selects the previous enabled option and moves focus to it. From the first option it wraps to the last. |
| `Home` or `End` | Selects the first or the last enabled option and moves focus to it. |
| `ArrowRight` or `ArrowLeft` or `Home` or `End` | With `activation="manual"`: only moves focus to the next, previous, first or last enabled option (wrapping). The selection stays on the chosen option until Enter or Space. |
| `Enter` or `Space` | Chooses the focused option, as a click does. With `activation="auto"` the arrow keys have already chosen it, so you need these only when your `onValueChange` refused the change. With `activation="manual"` this is how a focused option is chosen. |

Up and Down do nothing, typing a letter does not jump to an option, and a disabled option is skipped. The rows below describe the default automatic activation.

## Behavior

What the segment does with its value, options, sliding pill, screen readers and motion.

- **Controlled:** The segment keeps no state of its own, so you pass the value and a change handler. A click or key reports the option's value, and the selection changes when you pass the new value back.
- **Options:** Options are an array with a value, a label and optionally an icon or disabled flag, and the label can be any node. Array order is visual order, and the track never wraps or scrolls.
- **Badge or counter in an option:** Put a Badge or counter in the label node as the direct, last child of the option, after the label text, such as `Unread` and a counter. Only then does the option give it the same 4 px from the top, bottom and right edge, and the option's gap to the label. A badge wrapped in another element, or placed before the label, keeps the plain padding and the gaps are uneven.
- **Width:** The track is as wide as its options. To fill a row, add a class that makes the track full width and gives each option an equal share.
- **Sizes and shapes:** The smallest sizes are 32 and 28 px, and the two largest follow the control tokens: 36 and 40 px at compact density, 40 and 44 px at comfortable. Pill rounds fully, rounded uses 8 px.
- **Sliding pill:** With sliding, one pill sits behind the selected option and moves to the next. Until the first paint the selected option fills itself, so server HTML never shows a track without a selection.
- **Activation:** Automatic activation moves focus and chooses at once, so the change handler fires on each key press. Manual only moves focus and Enter or Space chooses, which suits choices with a cost.
- **Resizing:** The pill follows a resize of the track, such as a wider container or a late font, without sliding. It slides only when the value changes.
- **Focus:** Keyboard focus draws the standard focus ring on the option: an indigo border and a 2 px light indigo ring, following the option's radius. The sliding pill stays behind it.
- **Assistive technology:** The track is a labelled tab list and each option a tab, but no panels are rendered. Name the content it switches nearby and announce changes in a live region.
- **Motion:** The pill moves with a transform, and the text colour and hover fill change quickly.
- **Reduced motion:** With reduced motion the pill does not slide. It jumps to the new option, and the selection still changes at once.

## Anatomy

- `Segment`: The track: a grey bar, as wide as its options, labelled for assistive technology. Size sets its height, and shape sets the corners: a full pill, or 8 px with concentric options.
- `Option`: One button per entry in the options array, with the selected option as the single tab stop. Hover uses the page fill, pressed the subtle fill, and a disabled option is dimmed and skipped by keys.
- `Selected pill`: The white pill behind the selected option, drawn only when sliding is on, and it moves from the old option to the new one. Without sliding the selected option paints the white fill itself.
- `Icon`: An icon you pass with an option, shown before the label at 14 or 16 px. Give a Lucide icon a 1.5 stroke, and it takes its option's text colour.

## Best practices

### When to use

- Use it to switch the view or scope of one piece of content: day, week, month, list or grid, monthly or yearly. For separate panels use Tabs, and for on or off use a switch.

### Do

- Keep it to two to five options with short labels. The track does not wrap or scroll, so five long labels are wider than a phone.
- Pass an aria-label, for example Time range. It names the tab list, and the options only carry their own labels.
- Give an icon-only option a visually hidden label such as List. Without it the option has no accessible name.
- Pick the size by place: the smaller ones inside a card or chart header, the larger ones to line up with a Button. Those heights follow the density tokens.
- Turn on sliding when the options are neighbours the eye should follow, such as a period. Use the plain version for a control that changes rarely.
- Switch to manual activation when a choice is hard to undo or costly, such as a permission level or billing interval. Keep the default when choosing only changes a view.

### Don't

- Don't pass a value that matches no option. The first enabled option becomes the tab stop, but none looks selected.
- Don't use a Segment to open panels with their own content and URL, because it renders no panels. Tabs owns the panels.

## API reference

### Segment

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: string) => void |  | Called with the `value` of an option when it is clicked or reached with an arrow key, Home or End. Store it and pass it back as `value`. |
| options* | SegmentOption[] |  | The options in the order they are shown: `{ value, label, icon?, disabled? }`. `value` is a unique string, `label` any node, `icon` an element drawn before the label (a Lucide icon with `strokeWidth={1.5}`), `disabled` dims the option and removes it from the keys. |
| value* | string |  | The `value` of the selected option. Required: the segment is controlled. A value that matches no option leaves nothing selected and makes the first enabled option the tab stop. |
| activation | "auto" \| "manual" | "auto" | What the arrow keys, Home and End do. `auto` (default) moves focus and chooses the option at once. `manual` only moves focus; Enter or Space chooses. Mouse and touch are unaffected. |
| aria-label | string |  | Names the tab list for screen readers, for example `Time range`. Pass it every time: the options only carry their own labels. |
| className | string |  | Extra classes for the track, for example the classes that make it fill its row. |
| shape | "rounded" \| "pill" | "pill" | `pill` (the default) rounds the track and the options fully. `rounded` gives the track 8 px corners and the options a concentric radius. |
| size | "lg" \| "sm" \| "xs" \| "md" | "md" | `xs` (32 px, chart filters), `sm` (28 px), `md` (the default, the Button height) or `lg`. `md` and `lg` follow the density tokens. |
| slide | boolean | true | Slides the selected pill to the next option with a transform instead of switching at once. On by default; pass `slide={false}` to switch at once. It does not slide when the user prefers reduced motion. |

## Examples

### Content: labels, an icon with a label, or an icon only

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

### Width: as wide as its options, or filling the row

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

### Options: two, three or five

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [value, setValue] = useState("yearly")

  return (
    <Segment
      aria-label="Period"
      value={value}
      onValueChange={setValue}
      options={[
        { value: "monthly", label: "Monthly" },
        { value: "yearly", label: "Yearly" },
      ]}
    />
  )
}
```

### Motion: a pill that slides, or an instant switch

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

### Activation: the arrows choose, or Enter chooses

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

### States: default and a disabled option

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

export function Example() {
  const [range, setRange] = useState("week")

  return (
    <Segment
      aria-label="Time range"
      value={range}
      onValueChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  )
}
```

## In context

### Revenue card: a period switcher in the header

A small segment sits next to the card title and the figure under it follows. The figure is announced politely, so a screen reader hears the new value.

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

const PERIODS = [
  { value: "7d", label: "7 days", revenue: "$12,480", change: "+4.1%" },
  { value: "30d", label: "30 days", revenue: "$48,210", change: "+8.2%" },
  { value: "12m", label: "12 months", revenue: "$562,940", change: "+17.6%" },
]

export function Example() {
  const [period, setPeriod] = useState("30d")
  const current = PERIODS.find((item) => item.value === period) ?? PERIODS[0]

  return (
    <div className="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <div className="flex items-center justify-between gap-3">
        <h3 className="text-sm font-medium text-foreground">Revenue</h3>
        <Segment
          size="sm"
          slide
          aria-label="Period"
          value={period}
          onValueChange={setPeriod}
          options={PERIODS.map(({ value, label }) => ({ value, label }))}
        />
      </div>
      <div aria-live="polite" className="flex flex-col gap-1">
        <p className="text-2xl font-semibold tabular-nums text-foreground">{current.revenue}</p>
        <p className="text-sm text-text-secondary">{current.change} compared with the period before</p>
      </div>
    </div>
  )
}
```

### Project list: switch between a list and a grid

Two icon-only options with the rounded shape, each with a hidden label. The list and the grid share one height so the card does not jump.

```tsx
import { useState } from "react"
import { LayoutGrid, List } from "lucide-react"
import { Segment } from "@/components/ui/segment"

const PROJECTS = [
  { name: "Website relaunch", owner: "Nora Lindgren", due: "Dec 4" },
  { name: "Billing migration", owner: "Daniel Okafor", due: "Dec 12" },
  { name: "Brand guidelines", owner: "Tomás Ferreira", due: "Dec 18" },
  { name: "Research summary", owner: "Maya Kessler", due: "Jan 8" },
]

export function Example() {
  const [view, setView] = useState("list")

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <div className="flex items-center justify-between gap-3">
        <h3 className="text-sm font-medium text-foreground">Projects</h3>
        <Segment
          shape="rounded"
          slide
          aria-label="Layout"
          value={view}
          onValueChange={setView}
          options={[
            { value: "list", label: <span className="sr-only">List</span>, icon: <List strokeWidth={1.5} /> },
            { value: "grid", label: <span className="sr-only">Grid</span>, icon: <LayoutGrid strokeWidth={1.5} /> },
          ]}
        />
      </div>
      {view === "list" ? (
        <ul className="flex flex-col divide-y divide-border rounded-xl border border-border bg-card">
          {PROJECTS.map((project) => (
            <li key={project.name} className="flex items-center justify-between gap-3 px-4 py-3 text-sm">
              <span className="text-foreground">{project.name}</span>
              <span className="text-text-secondary">{project.owner}</span>
            </li>
          ))}
        </ul>
      ) : (
        <ul className="grid grid-cols-2 gap-3">
          {PROJECTS.map((project) => (
            <li key={project.name} className="flex flex-col gap-1 rounded-xl border border-border bg-card p-4 text-sm">
              <span className="font-medium text-foreground">{project.name}</span>
              <span className="text-text-secondary">Due {project.due}</span>
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}
```

### Pricing card: a billing interval that fills the card

The segment spans the full width of the card, and the price under it changes with the interval.

```tsx
import { useState } from "react"
import { Segment } from "@/components/ui/segment"

const PRICES = {
  monthly: { price: "$29", note: "Billed monthly, cancel any time." },
  yearly: { price: "$23.20", note: "Billed $278.40 once a year. You save 20%." },
}

export function Example() {
  const [billing, setBilling] = useState<"monthly" | "yearly">("monthly")
  const plan = PRICES[billing]

  return (
    <div className="flex w-full max-w-xs flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <Segment
        slide
        aria-label="Billing interval"
        value={billing}
        onValueChange={(value) => setBilling(value as "monthly" | "yearly")}
        className="flex w-full [&>[role=tab]]:flex-1 [&>[role=tab]]:justify-center"
        options={[
          { value: "monthly", label: "Monthly" },
          { value: "yearly", label: "Yearly" },
        ]}
      />
      <div aria-live="polite" className="flex flex-col gap-1">
        <h3 className="text-sm font-medium text-foreground">Team plan</h3>
        <p className="text-3xl font-semibold tabular-nums text-foreground">
          {plan.price}
          <span className="text-sm font-normal text-text-secondary"> per seat a month</span>
        </p>
        <p className="text-sm text-text-secondary">{plan.note}</p>
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("segment")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
