> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# SegmentedControl

Switches between renditions of the same content, with every option visible — reach for `Tabs` when the sections are distinct places rather than views of one thing, and `Radio` when the choice is an answer a form submits. It owns no panel: it reports the chosen value and you re-render the content yourself.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/SegmentedControl) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/inputs-segmentedcontrol--overview)

```tsx
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const Basic = () => (
  <SegmentedControl defaultValue='1' data-testid='segmented-control'>
    <SegmentedControlItem value='1'>
      Headers
      <NumericBadge>33</NumericBadge>
    </SegmentedControlItem>
    <SegmentedControlItem value='2'>
      Parameters
      <NumericBadge>100</NumericBadge>
    </SegmentedControlItem>
    <SegmentedControlItem value='3'>Schema</SegmentedControlItem>
  </SegmentedControl>
);
```

## Usage

```tsx
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';
```

## Examples

### Disabled

A disabled option stays visible rather than disappearing, so the set of choices doesn't
change shape between visits.

```tsx
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const Disabled = () => (
  <SegmentedControl defaultValue='1'>
    <SegmentedControlItem value='1'>Active</SegmentedControlItem>
    <SegmentedControlItem value='2' disabled>
      Disabled
    </SegmentedControlItem>
    <SegmentedControlItem value='3'>Normal</SegmentedControlItem>
  </SegmentedControl>
);
```

### Icons

Icons beside the labels, which helps when the options are renditions — a list against a
grid — rather than categories.

```tsx
import { ChevronLeft, ChevronRight, Search } from '@wallarm-org/design-system/icons';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const Icons = () => (
  <SegmentedControl defaultValue='1'>
    <SegmentedControlItem value='1'>
      <ChevronLeft />
      Previous
    </SegmentedControlItem>
    <SegmentedControlItem value='2'>
      <Search />
      Search
    </SegmentedControlItem>
    <SegmentedControlItem value='3'>
      Next
      <ChevronRight />
    </SegmentedControlItem>
  </SegmentedControl>
);
```

### Icon only

Icon-only segments for a toolbar. Each still needs an accessible name; the icon is the
label only visually.

```tsx
import { Home, Search, SlidersHorizontal } from '@wallarm-org/design-system/icons';
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const IconOnly = () => (
  <SegmentedControl defaultValue='user'>
    <SegmentedControlItem value='user'>
      <Home />
      <NumericBadge>1</NumericBadge>
    </SegmentedControlItem>
    <SegmentedControlItem value='settings'>
      <SlidersHorizontal />
    </SegmentedControlItem>
    <SegmentedControlItem value='search'>
      <Search />
    </SegmentedControlItem>
  </SegmentedControl>
);
```

### More button

An overflow trigger for the options that didn't fit. If you need this often, the choice
probably wants a `Select`.

```tsx
import { Ellipsis } from '@wallarm-org/design-system/icons';
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlButton, SegmentedControlItem, SegmentedControlSeparator } from '@wallarm-org/design-system/SegmentedControl';

export const MoreButton = () => (
  <SegmentedControl defaultValue='1'>
    <SegmentedControlItem value='1'>
      Headers
      <NumericBadge>33</NumericBadge>
    </SegmentedControlItem>
    <SegmentedControlItem value='2'>
      Parameters
      <NumericBadge>100</NumericBadge>
    </SegmentedControlItem>
    <SegmentedControlItem value='3'>Schema</SegmentedControlItem>
    <SegmentedControlSeparator />
    <SegmentedControlButton onClick={onShowMore}>
      <Ellipsis />
      More
    </SegmentedControlButton>
  </SegmentedControl>
);
```

### Many

What too many options looks like — worth seeing so the limit is a judgement rather than a
rule you took on trust.

```tsx
import { Ellipsis } from '@wallarm-org/design-system/icons';
import { SegmentedControl, SegmentedControlButton, SegmentedControlItem, SegmentedControlSeparator } from '@wallarm-org/design-system/SegmentedControl';

export const Many = () => {
  const items = Array.from({ length: 10 }, (_, i) => ({
    id: String(i + 1),
    text: `Item ${i + 1}`,
  }));

  return (
    <SegmentedControl defaultValue='1'>
      {items.slice(0, 7).map(item => (
        <SegmentedControlItem key={item.id} value={item.id}>
          {item.text}
        </SegmentedControlItem>
      ))}
      <SegmentedControlSeparator />
      <SegmentedControlButton onClick={onShowMore}>
        <Ellipsis />
        More
      </SegmentedControlButton>
    </SegmentedControl>
  );
};
```

### Badge

A count on a segment, for when each view holds a different number of things and the reader
would otherwise have to switch to find out.

```tsx
import { CircleDashed } from '@wallarm-org/design-system/icons';
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const Badge = () => (
  <SegmentedControl defaultValue='icon-badge'>
    <SegmentedControlItem value='icon-only'>
      <CircleDashed />
    </SegmentedControlItem>
    <SegmentedControlItem value='icon-badge'>
      <CircleDashed />
      <NumericBadge>1</NumericBadge>
    </SegmentedControlItem>
    <SegmentedControlItem value='text-badge'>
      Items
      <NumericBadge>99</NumericBadge>
    </SegmentedControlItem>
  </SegmentedControl>
);
```

### Full width

Stretches to its container, dividing the width evenly. Suits a narrow panel; in a wide one
it leaves the segments floating far apart.

```tsx
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const FullWidth = () => (
  <div className='min-w-800'>
    <SegmentedControl defaultValue='1' fullWidth>
      <SegmentedControlItem value='1'>
        Overview
        <NumericBadge>12</NumericBadge>
      </SegmentedControlItem>
      <SegmentedControlItem value='2'>Analytics</SegmentedControlItem>
      <SegmentedControlItem value='3'>
        Reports
        <NumericBadge>5</NumericBadge>
      </SegmentedControlItem>
      <SegmentedControlItem value='4'>Settings</SegmentedControlItem>
    </SegmentedControl>
  </div>
);
```

### Controlled

Own the value when something else has to move with it, which is the usual case, since the
control renders no panel of its own.

```tsx
import { useState } from 'react';
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';

export const Controlled = () => {
  const [value, setValue] = useState<string>('1');

  return (
    <SegmentedControl value={value} onChange={setValue}>
      <SegmentedControlItem value='1'>
        Headers
        <NumericBadge>33</NumericBadge>
      </SegmentedControlItem>
      <SegmentedControlItem value='2'>
        Parameters
        <NumericBadge>100</NumericBadge>
      </SegmentedControlItem>
      <SegmentedControlItem value='3'>Schema</SegmentedControlItem>
    </SegmentedControl>
  );
};
```

### Form field

Inside `Field`, for when the choice really is a form answer — the case where `Radio` is
often the better call.

```tsx
import { Field, FieldDescription, FieldLabel } from '@wallarm-org/design-system/Field';
import { Info } from '@wallarm-org/design-system/icons';
import { NumericBadge } from '@wallarm-org/design-system/NumericBadge';
import { SegmentedControl, SegmentedControlItem } from '@wallarm-org/design-system/SegmentedControl';
import { Tooltip, TooltipContent, TooltipTrigger } from '@wallarm-org/design-system/Tooltip';

export const FormField = () => (
  <Field>
    <FieldLabel>
      Label
      <Tooltip>
        <TooltipTrigger>
          <Info />
        </TooltipTrigger>
        <TooltipContent>Additional information</TooltipContent>
      </Tooltip>
    </FieldLabel>

    <FieldDescription>This is an input description.</FieldDescription>

    <SegmentedControl defaultValue='1'>
      <SegmentedControlItem value='1'>
        Headers
        <NumericBadge>33</NumericBadge>
      </SegmentedControlItem>
      <SegmentedControlItem value='2'>
        Parameters
        <NumericBadge>100</NumericBadge>
      </SegmentedControlItem>
      <SegmentedControlItem value='3'>Schema</SegmentedControlItem>
    </SegmentedControl>
  </Field>
);
```

## Props

| Prop           | Type                                     | Default | Description                                         |
| -------------- | ---------------------------------------- | ------- | --------------------------------------------------- |
| title          | `string \| undefined`                    |         |                                                     |
| defaultChecked | `boolean \| undefined`                   |         |                                                     |
| autoFocus      | `boolean \| undefined`                   |         |                                                     |
| id             | `string \| undefined`                    |         |                                                     |
| tabIndex       | `number \| undefined`                    |         |                                                     |
| rel            | `string \| undefined`                    |         |                                                     |
| fullWidth      | `{ true: string; false: string; }`       | `false` |                                                     |
| value          | `string \| undefined`                    |         | The currently selected value                        |
| defaultValue   | `string \| undefined`                    |         | The default selected value                          |
| onChange       | `((value: string) => void) \| undefined` |         | Callback function called when the selection changes |
| data-testid    | `string \| undefined`                    |         |                                                     |

### SegmentedControlButton

| Prop           | Type                                                                       | Default  | Description |
| -------------- | -------------------------------------------------------------------------- | -------- | ----------- |
| size           | `{ small: string; medium: string; large: string; 'inline-edit': string; }` | `medium` |             |
| loading        | `{ true: string; }`                                                        |          |             |
| fullWidth      | `{ true: string; false: string; }`                                         |          |             |
| asChild        | `boolean \| undefined`                                                     |          |             |
| data-testid    | `string \| undefined`                                                      |          |             |
| as             | `C \| undefined`                                                           |          |             |
| title          | `string \| undefined`                                                      |          |             |
| defaultChecked | `boolean \| undefined`                                                     |          |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined`                       |          |             |
| autoFocus      | `boolean \| undefined`                                                     |          |             |
| id             | `string \| undefined`                                                      |          |             |
| tabIndex       | `number \| undefined`                                                      |          |             |
| rel            | `string \| undefined`                                                      |          |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`                              |          |             |
| type           | `"button" \| "submit" \| "reset" \| undefined`                             |          |             |
| disabled       | `boolean \| undefined`                                                     |          |             |
| name           | `string \| undefined`                                                      |          |             |
| value          | `string \| number \| readonly string[] \| undefined`                       |          |             |

### SegmentedControlItem

| Prop           | Type                                                              | Default | Description                            |
| -------------- | ----------------------------------------------------------------- | ------- | -------------------------------------- |
| value \*       | `string`                                                          |         | Unique value that identifies this item |
| disabled       | `boolean \| undefined`                                            |         | Whether this item is disabled          |
| onKeyDown      | `((event: KeyboardEvent<HTMLLabelElement>) => void) \| undefined` |         |                                        |
| title          | `string \| undefined`                                             |         |                                        |
| defaultChecked | `boolean \| undefined`                                            |         |                                        |
| defaultValue   | `string \| number \| readonly string[] \| undefined`              |         |                                        |
| autoFocus      | `boolean \| undefined`                                            |         |                                        |
| id             | `string \| undefined`                                             |         |                                        |
| tabIndex       | `number \| undefined`                                             |         |                                        |
| rel            | `string \| undefined`                                             |         |                                        |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`                     |         |                                        |
| htmlFor        | `string \| undefined`                                             |         |                                        |
| data-testid    | `string \| undefined`                                             |         |                                        |

### SegmentedControlSeparator

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| title          | `string \| undefined`                                |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| orientation    | `{ horizontal: string; vertical: string; }`          |         |             |
| spacing        | `complex`                                            |         |             |
| data-testid    | `string \| undefined`                                |         |             |
| decorative     | `boolean \| undefined`                               |         |             |
| mx             | `complex`                                            | `2`     |             |

## Explorer