# Segmented control

A hybrid somewhere between a button group, radio buttons, and tabs; segmented controls are used to switch between different options or views.

Tabs: [Guidelines](/components/web/segmented-control/segmented-control.guidelines.md) · [Code](/components/web/segmented-control/segmented-control.code.md)

## Basic usage

First, import the component.

```tsx
import {SegmentedControl} from '@pleo-io/telescope'
```

Then use it like so:

```tsx
<SegmentedControl
    options={[
        {value: 'apples', label: 'Apples'},
        {value: 'bananas', label: 'Bananas'},
    ]}
    value="bananas"
    onChange={() => {}}
/>
```

## Controlled

`SegmentedControl` is a controlled component. Pass the selected option as `value` (or `null` for no selection) and update it from `onChange`, which receives the selected option's `value`. Pass a type argument to narrow the values.

```tsx
type View = 'list' | 'grid'

const ViewSwitcher = () => {
    const [view, setView] = React.useState<View>('list')

    return (
        <SegmentedControl<View>
            options={[
                {value: 'list', label: 'List'},
                {value: 'grid', label: 'Grid'},
            ]}
            value={view}
            onChange={setView}
        />
    )
}
```

## Full width

Use `fullWidth` to stretch the control and share the width equally between options.

```tsx
<SegmentedControl
    options={[
        {value: 'apples', label: 'Apples'},
        {value: 'bananas', label: 'Bananas'},
    ]}
    value="apples"
    onChange={() => {}}
    fullWidth
/>
```

## Accessibility

Each option renders a native radio input with an associated label, grouped by `name` (generated when not passed). The selection animation is skipped when the user prefers reduced motion, or when `disableAnimation` is set.

## API reference

Radio group element styled as an inline toggle with multiple options Use instead of a select element if there are few options or instead of a checkbox if options are not strictly on/off

#### `disableAnimation`

Type: `boolean`

Default: -

Disable the animation

#### `fullWidth`

Type: `boolean`

Default: -

Full width

#### `id`

Type: `string | undefined`

Default: -

HTML id passed to outer most element

#### `name`

Type: `string | undefined`

Default: -

HTML name passed to input elements

#### `onChange`

Type: `(newValue: Value) => void`

Default: `() => {}`

Callback called with the selected value

#### `options` (required)

Type: `SegmentedControlOption<Value>[]`

Default: -

An array of options, with value and label

#### `value` (required)

Type: `string | null`

Default: -

Currently selected value

- string, which should be one of provided SegmentedControlOption' values
- null, which means that no option is selected