SegmentedControl

Segmented toggle group for mutually exclusive options. Built on React Aria ToggleButtonGroup with an animated indicator. Prefer this over a row of standalone ToggleButtons when only one choice should be active.

Examples

Default

Pass options as { id, label } and seed selection with defaultSelectedKeys.

import { SegmentedControl } from '@var-ui/react';

<SegmentedControl
  selectionMode="single"
  defaultSelectedKeys={['list']}
  options={[
    { id: 'list', label: 'List' },
    { id: 'grid', label: 'Grid' },
  ]}
/>

Controlled selection

Drive selection with selectedKeys and onSelectionChange when the active segment must sync with app state.

import { SegmentedControl } from '@var-ui/react';
import { useState } from 'react';
import type { Selection } from 'react-aria-components';

const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set(['list']));

<SegmentedControl
  selectionMode="single"
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}
  options={[
    { id: 'list', label: 'List' },
    { id: 'grid', label: 'Grid' },
    { id: 'board', label: 'Board' },
  ]}
/>

Props

Accessibility

Each segment is a toggle button inside a group; keyboard users can move between segments with arrow keys (React Aria). For icon-only options, set aria-label on the option. Use selectionMode="single" (default) for exclusive choices.