Single и multiple режимы

Radix UI предоставляет компоненты управления состоянием выбора, среди которых особое место занимают RadioGroup и CheckboxGroup. Их поведение зависит от режима выбора: single (одиночный) и multiple (множественный). Понимание различий между этими режимами критически важно для построения корректного пользовательского интерфейса и управления состоянием.

Single режим

Single режим применяется, когда требуется выбрать только один элемент из группы. В Radix UI чаще всего это реализуется через компонент RadioGroup с дочерними элементами RadioItem.

Пример структуры:

import * as RadioGroup from '@radix-ui/react-radio-group';

<RadioGroup.Root defaultValue="apple" aria-label="Выберите фрукт">
  <RadioGroup.Item value="apple">Яблоко</RadioGroup.Item>
  <RadioGroup.Item value="orange">Апельсин</RadioGroup.Item>
  <RadioGroup.Item value="banana">Банан</RadioGroup.Item>
</RadioGroup.Root>

Ключевые особенности single режима:

  • Ограничение выбора одним элементом: пользователь не может выбрать одновременно несколько опций.
  • Событие onValueChange: срабатывает при изменении выбранного элемента, передавая новое значение.
  • Использование aria-атрибутов: aria-checked, role="radio" и role="radiogroup" обеспечивают доступность для экранных читалок.
<RadioGroup.Root
  defaultValue="apple"
  onValueCha nge={(value) => console.log("Выбран:", value)}
>
  ...
</RadioGroup.Root>

С помощью defaultValue можно задать начальное выбранное значение, а value — управлять состоянием контролируемого компонента.

Multiple режим

Multiple режим реализуется через компонент CheckboxGroup или с помощью отдельных Checkbox компонентов. Он используется, когда требуется разрешить несколько выборов одновременно.

Пример структуры:

import * as Checkbox from '@radix-ui/react-checkbox';

<Checkbox.Root defaultChecked>
  <Checkbox.Indicator />
  Согласен с условиями
</Checkbox.Root>
<Checkbox.Root>
  <Checkbox.Indicator />
  Подписка на новости
</Checkbox.Root>

Ключевые особенности multiple режима:

  • Выбор нескольких элементов одновременно: каждый элемент управляет своим состоянием независимо.
  • Событие onCheckedChange: информирует о переключении состояния конкретного чекбокса (true/false или "indeterminate").
  • Контролируемое состояние: возможно использование массивов значений для управления группой чекбоксов.

Пример контролируемого multiple режима:

const [selected, setSelected] = React.useState([]);

<Checkbox.Root
  checked={selected.includes('terms')}
  onCheckedCha nge={(checked) => {
    setSelected((prev) =>
      checked ? [...prev, 'terms'] : prev.filter(v => v !== 'terms')
    );
  }}
>
  <Checkbox.Indicator />
  Согласен с условиями
</Checkbox.Root>

Отличия single и multiple режимов

Характеристика Single Multiple
Количество выбранных 1 элемент Несколько элементов
Компоненты RadioGroup + RadioItem Checkbox или CheckboxGroup
Событие изменения onValueChange onCheckedChange
Контролируемое состояние value Массив значений / checked
aria-роль radiogroup, radio group, checkbox

Управление состоянием

Single режим удобно использовать с управляемым состоянием через useState:

const [fruit, setFruit] = React.useState('apple');

<RadioGroup.Root value={fruit} onValueCha nge={setFruit}>
  <RadioGroup.Item value="apple">Яблоко</RadioGroup.Item>
  <RadioGroup.Item value="orange">Апельсин</RadioGroup.Item>
</RadioGroup.Root>

Multiple режим требует массивного состояния, чтобы хранить все выбранные элементы:

const [selectedOptions, setSelectedOptions] = React.useState([]);

const toggleOption = (option) => {
  setSelectedOptions((prev) =>
    prev.includes(option)
      ? prev.filter(v => v !== option)
      : [...prev, option]
  );
};

Особенности UX

  • Single режим часто используется для выбора одного варианта из нескольких альтернатив, например, способы оплаты или категории товара.
  • Multiple режим полезен для выбора нескольких независимых опций, например, подписки на уведомления, теги или фильтры.
  • Radix UI автоматически обрабатывает доступность и клавиатурную навигацию: стрелки для radio и пробел/enter для checkbox.

Интеграция с формами

Single режим можно легко интегрировать с react-hook-form или Formik через value и onValueChange. Multiple режим требует, чтобы массив выбранных значений синхронизировался с состоянием формы.

<Checkbox.Root
  checked={form.values.tags.includes('news')}
  onCheckedCha nge={(checked) => {
    const updated = checked
      ? [...form.values.tags, 'news']
      : form.values.tags.filter(t => t !== 'news');
    form.setFieldValue('tags', updated);
  }}
>
  <Checkbox.Indicator />
  Новости
</Checkbox.Root>

Выводы по архитектуре

  • Single режим: структура проста, состояние представлено единичным значением.
  • Multiple режим: структура гибкая, требует массивного хранения и логики для добавления/удаления элементов.
  • Правильное использование режимов обеспечивает доступность, предсказуемое управление состоянием и согласованность интерфейса.

Оба режима Radix UI легко комбинируются с современными React-хуками, что позволяет строить сложные, но управляемые интерфейсы с минимальными усилиями.

Оглавление