CustomSelect

Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение React-компонентов, прочитать про это можно в документации React ↗.

Для использования неконтролируемого режима достаточно просто не передавать value или передавать defaultValue, если требуется задать значение по умолчанию. Для контролируемого режима используйте связку свойств value/onChange для задания значения и его изменения.

const colors = [
  {
    value: 'red',
    label: 'Красный',
  },
  {
    value: 'green',
    label: 'Зелёный',
  },
  {
    value: 'blue',
    label: 'Синий',
  },
];
 
// Неконтролируемое состояние
<CustomSelect options={colors} defaultValue="red" />;
 
// Контролируемое состояние
const [color, setColor] = React.useState('red');
 
<CustomSelect options={colors} value={color} onChange={(_, newColor) => setColor(newColor)} />;

Состояния

disabled

Свойство disabled блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

Валидация

Свойство status используется для визуализации валидации компонента - некорректности заполненного поля (значение "error") или успешной валидации (значение "valid").

Кастомизация

Визуальное оформление

С помощью свойства renderOption можно влиять на отображение конкретного элемента выпадающего списка. Вы можете изменить стандартный компонент CustomSelectOption или использовать свой компонент.

Кастомное поведение при поиске

Пример показывает, как реализовать кастомное поведение поиска: при вводе сохраняется локальный query, при отсутствии совпадений в списке появляется опция «Добавить пользователя …», её выбор добавляет новый элемент в options — вместе с пользовательским рендером опций это даёт удобный UX для создания элементов на лету.

Кастомный алгоритм поиска

Демонстрация кастомного алгоритма поиска иллюстрирует передачу filterFn для гибкого соответствия (по label и description), поддержку searchable и кастомного рендера опций — полезно, когда нужно искать по нескольким полям или использовать нестандартные критерии.

Асинхронная загрузка списка

Асинхронный пример показывает подгрузку опций с задержкой/дебаунсом, управление состояниями fetching/remoteQuery, минимальную длину запроса, очистку таймаутов и возможность заменить содержимое выпадающего списка (например, подсказкой «введите хотя бы три символа») — стандартный шаблон для работы с удалёнными API.

CustomSelectOption

Универсальный компонент для отрисовки одного из значений в выпадающем списке. Передавайте данный компонент в свойство renderOption, для кастомизации значений выпадающего списка. Помимо CustomSelect используется и в ChipsSelect.

Для реализации многоуровневых CustomSelectOption используйте свойство hierarchy, которое позволяет создать нужный отступ в зависимости от уровня вложенности.

Тестирование (e2e)

Для поиска компонента и его элементов на странице cуществует ряд вспомогательных свойств:

По умолчанию все data-* атрибуты попадают на <input> компонента, это значит, что при передаче data-testid или data-test-id идентификатор попадёт <input>. Доступ к полю ввода может быть полезен для:

• получения текста, введённого пользователем при поиске опций, в режиме searchable;
• получения информации о наличии фокуса на компоненте;
• симуляции работы с компонентом с клавиатуры.

Используйте labelTextTestId:

• для симуляции работы с компонентом с помощью мыши, тач-устройства;
• для получения текста выбранной в данный момент опции.

Для взаимодействия с кнопкой очистки состояния компонента, которая появляется, если CustomSelect имеет свойство searchable и пользователь выбрал опцию, используйте свойство clearButtonTestId.

CustomSelect внутри себя хранит невидимый <select>, для того, чтобы CustomSelect можно было использовать внутри формы. Для получения доступа к <select> используйте свойство nativeSelectTestId. Полезно для доступа к значению value, выбранной в данный момент опции.

Все перечисленные выше свойства устанавливают аттрибут data-testid у соответствующих элементов. Учитывайте это при построении селекторов.

Доступность (a11y)

Следуйте рекомендациям доступности компонента Select.

Индикация ассинхронной загрузки

Для того, чтобы уведомить пользователей скринридеров о том, что идет загрузка списка опций использутся специальные текстовые метки совместно со свойством fetching. Текст этих меток можно переопределить с помощью свойств fetchingInProgressLabel и fetchingCompletedLabel. По умолчанию они соответственно: "Список опций загружается..." и "Опций загружено: ${options.length}"

Проблема определения выбранной опции

В текущей реализации (v7) компонент CustomSelect имеет проблему с доступностью в некоторых скринридерах (например, NVDA): пользователь не может узнать, какой вариант выбран. Это происходит из-за сброса значения в input при потере фокуса.

Такое поведение было добавлено для ускорения ввода новых значений, но оно негативно влияет на доступность.

Решение

Мы изменили логику работы компонента. Чтобы включить исправленное поведение, используйте флаг accessible. Он введён для сохранения обратной совместимости в минорных обновлениях.

Рекомендация

Настоятельно рекомендуем включить этот флаг, так как в v8 он будет включён по умолчанию (accessible: true).

Свойства и методы