ToggleGroup
Контейнер для группы связанных toggle’ов (чипы, опции, сегментированный контрол) с общим режимом выбора. Предоставляет React Context — потомки читают текущий выбор через useToggleGroup.
Когда использовать
- Сегментированный контрол (выбор размера, периода, типа).
- Чипы-фильтры с
selectionMode='multiple'. - Любые связанные опции, где нужен shared state + unified controlled API.
Когда не нужен ToggleGroup: одна опция — Switch или Checkbox; взаимоисключающий выбор с нативной семантикой radio — группа Radio c общим name.
Анатомия
Mode
Тип дочерних контролов: checkbox — мультивыбор/независимые, radio — одиночный выбор.
Size
Размер вложенных тогглов: xs — плотный, s — дефолт.
Selection mode
Правила выбора: single — ровно один элемент (как radio-group), multiple — любое подмножество (как checkbox-group).
Установка
pnpm add @cloud-ru/ds-togglesimport { ToggleGroup, useToggleGroup } from '@cloud-ru/ds-toggles'Примеры использования
1. Single selection (сегментированный контрол)
tsx
import { ToggleGroup, useToggleGroup } from '@cloud-ru/ds-toggles';
import { useState } from 'react';
function Chip({ id, label }: { id: string; label: string }) {
const { isChecked, handleClick } = useToggleGroup({ value: id });
return (
<button onClick={handleClick} aria-pressed={isChecked}>
{label}
</button>
);
}
export function ToggleGroupSingle() {
const [value, setValue] = useState<string | undefined>('a');
return (
<ToggleGroup selectionMode='single' value={value} onChange={setValue}>
<Chip id='a' label='A' />
<Chip id='b' label='B' />
<Chip id='c' label='C' />
</ToggleGroup>
);
}2. Multiple selection (чипы-фильтры)
tsx
import { ToggleGroup, useToggleGroup } from '@cloud-ru/ds-toggles';
import { useState } from 'react';
function Chip({ id, label }: { id: string; label: string }) {
const { isChecked, handleClick } = useToggleGroup({ value: id });
return (
<button onClick={handleClick} aria-pressed={isChecked}>
{label}
</button>
);
}
export function ToggleGroupMultiple() {
const [value, setValue] = useState<string[]>(['a']);
return (
<ToggleGroup selectionMode='multiple' value={value} onChange={next => setValue(next ?? [])}>
<Chip id='a' label='A' />
<Chip id='b' label='B' />
<Chip id='c' label='C' />
</ToggleGroup>
);
}3. Controlled + отображение значения
Selected: —
tsx
import { ToggleGroup, useToggleGroup } from '@cloud-ru/ds-toggles';
import { useState } from 'react';
function Option({ id, label }: { id: string; label: string }) {
const { isChecked, handleClick } = useToggleGroup({ value: id });
return (
<button onClick={handleClick} aria-pressed={isChecked}>
{label}
</button>
);
}
export function ToggleGroupControlled() {
const [value, setValue] = useState<string | undefined>();
return (
<div style={{ display: 'flex', gap: 12, flexWrap: 'wrap', alignItems: 'center' }}>
<ToggleGroup selectionMode='single' value={value} onChange={setValue}>
<Option id='s' label='S' />
<Option id='m' label='M' />
<Option id='l' label='L' />
</ToggleGroup>
<p>Selected: {value ?? '—'}</p>
</div>
);
}Props
Types
Props
ToggleGroupProps| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
children | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null | undefined | — | no | |
defaultValue | string | string[] | — | no | Начальное состояние |
onChange | ((value: string) => void) | ((value: string[]) => void) | undefined | — | no | Controlled обработчик измения состояния |
selectionMode | "multiple" | "single" | single | no | Режим выбора |
value | string | string[] | — | no | Controlled состояние |