CustomSelect

Компонент для выбора значения из выпадающего списка. Поддерживает широкие возможности по изменению внешнего вида, поиск по опциям и пользовательский рендеринг опций.

Связанные компоненты:

Select

Загружается...

Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение 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 или использовать свой компонент.

Загружается...

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 у соответствующих элементов. Учитывайте это при построении селекторов.

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

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

CustomSelect

Свойство	Описание
`after`	`ReactNode` Добавляет иконку справа. Рекомендации: Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. Используйте IconButton ↗, если вам нужна иконка, реагируюущая на нажатие. По умолчанию: `-`
`afterAlign`	`FieldIconsAlign` Вертикальное выравнивание иконки справа. По умолчанию: `-`
`align`	`AlignType` По умолчанию: `-`
`allowClearButton`	`boolean` Если `true`, то справа будет отображаться кнопка для очистки значения. По умолчанию: `-`
`before`	`ReactNode` Добавляет иконку слева. Рекомендации: Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. Используйте IconButton ↗, если вам нужна иконка, реагирующая на нажатие. По умолчанию: `-`
`beforeAlign`	`FieldIconsAlign` Вертикальное выравнивание иконки слева. По умолчанию: `-`
`ClearButton`	`ComponentType<CustomSelectClearButtonProps>` Кастомная кнопка для очистки значения. Должна принимать обязательное свойство `onClick`. По умолчанию: `-`
`clearButtonTestId`	`string` Передает атрибут `data-testid` для кнопки очистки. По умолчанию: `-`
`defaultValue`	`SelectValue` См. `value`. По умолчанию: `-`
`dropdownAutoWidth`	`boolean` Ширина раскрывающегося списка зависит от контента. По умолчанию: `-`
`dropdownOffsetDistance`	`number` Отступ от выпадающего списка. По умолчанию: `-`
`emptyText`	`string` Текст, который будет отображен, если приходит пустой `options`. По умолчанию: `-`
`fetching`	`boolean` Если `true`, то в дропдауне вместо списка опций рисуется спиннер. При переданных `renderDropdown` и `fetching: true` “победит” `renderDropdown`. По умолчанию: `-`
`filterFn`	`false \| FilterFn<OptionInterfaceT>` Функция для кастомной фильтрации. По умолчанию поиск производится по `option.label`. По умолчанию: `-`
`forceDropdownPortal`	`boolean` Использовать Portal для рендеринга выпадающего списка. По умолчанию: `-`
`getRef`	`Ref<HTMLSelectElement>` По умолчанию: `-`
`getRootRef`	`Ref<HTMLDivElement>` По умолчанию: `-`
`getSelectInputRef`	`Ref<HTMLInputElement>` Ref на внутрений компонент input. По умолчанию: `-`
`icon`	`ReactNode` Иконка раскрывающегося списка. По умолчанию: `-`
`labelTextTestId`	`string` Передает атрибут `data-testid` для элемента, внутри которого отображается текст выбранной опции `CustomSelect` или плейсхолдер. По умолчанию: `-`
`mode`	`"default" \| "plain"` Режим отображения. `default` — показывает фон, обводку и, при наличии, текст-подсказку. `plain` — показывает только текст-подсказку. По умолчанию: `-`
`multiline`	`boolean` Флаг для включения многострочного режима. По умолчанию: `-`
`nativeSelectTestId`	`string` Передает атрибут `data-testid` для нативного элемента `select`. По умолчанию: `-`
`noMaxHeight`	`boolean` Отключает максимальную высоту по умолчанию. По умолчанию: `-`
`onChange`	`((e: ChangeEvent<HTMLSelectElement>, newValue: SelectValue) => void)` Обработчик, срабатывающий при изменении выбранного значения. Вторым параметром прокидывается новое значение. ⚠️ Лучше использовать второй параметр при работе с компонентом. По умолчанию: `-`
`onClose`	`VoidFunction` Обработчик закрытия выпадающего списка. По умолчанию: `-`
`onInputChange`	`((e: ChangeEvent<HTMLInputElement>) => void)` Событие изменения текстового поля. По умолчанию: `-`
`onInputKeyDown`	`((e: KeyboardEvent<Element>, isOpen: boolean) => void)` Обработчик события `keyDown` в поле ввода. По умолчанию: `-`
`onOpen`	`VoidFunction` Обработчик открытия выпадающего списка. По умолчанию: `-`
`options`	`OptionInterfaceT[]` Список опций в списке. По умолчанию: `-`
`overscrollBehavior`	`"auto" \| "none" \| "contain"` Поведение overscroll, подробнее можно почитать в документации ↗. По умолчанию: `-`
`placeholder`	`string` Текст-подсказка при отсутствии выбранного значения. По умолчанию: `-`
`popupDirection`	`PopupDirection` Направление раскрытия выпадающего списка. По умолчанию: `-`
`renderDropdown`	`(({ defaultDropdownContent, }: { defaultDropdownContent: ReactNode; }) => ReactNode)` Рендер-проп для кастомного рендера содержимого дропдауна. В `defaultDropdownContent` содержится список опций в виде скроллящегося блока. По умолчанию: `-`
`renderOption`	`((props: CustomSelectRenderOption<OptionInterfaceT>) => ReactNode)` Рендер-проп для кастомного рендера опции. В объекте аргумента приходят свойства опции ↗. ⚠️ Важно: cвойство опции `disabled` должно выставляться только через проп `options`. Запрещается выставлять `disabled` проп опциям в обход `options`, иначе `CustomSelect` не будет знать об актуальном состоянии опции. По умолчанию: `-`
`searchable`	`boolean` Если `true`, то при нажатии на `CustomSelect` в нём появится текстовое поле для поиска по `options`. По умолчанию поиск производится по `option.label`. По умолчанию: `-`
`selectType`	`SelectType` Тип отображения компонента. По умолчанию: `-`
`status`	`"default" \| "error" \| "valid"` Статус отображения поля в форме. По умолчанию: `-`
`value`	`SelectValue` Выбранное значение. ⚠️ Важно: При прокидывании `undefined` компонент будет считаться `Uncontrolled`. Не используйте `undefined`, чтобы показать невыбранное состояние. Вместо этого используйте `null`. По умолчанию: `-`

CustomSelectOption

Свойство	Описание
`after`	`ReactNode` Вставляет элемент в конец блока после основного контента. Например, можно передать компонент `Avatar`, `Icon<Name>` или другие изображения. По умолчанию: `-`
`before`	`ReactNode` Вставляет элемент в начало блока перед основным контентом. Например, можно передать компонент `Avatar`, `Icon<Name>` или другие изображения. По умолчанию: `-`
`description`	`ReactNode` Добавляет описание под основным блоком. По умолчанию: `-`
`disabled`	`boolean` Блокирует весь блок. ⚠️ Важно: если CustomSelectOption используется внутри Select ↗, CustomSelect ↗ или ChipsSelect ↗, то свойство явно должно выставляться только через структуру `options`. Запрещается выставлять `disabled` проп опциям в обход `options`, иначе CustomSelect ↗ и ChipsSelect ↗ не будут знать об актуальном состоянии опции. По умолчанию: `-`
`focused`	`boolean` Включает состояние фокуса. По умолчанию: `-`
`getRootRef`	`Ref<HTMLDivElement>` По умолчанию: `-`
`hierarchy`	`number` Позволяет создавать вложенность. По умолчанию: `0`
`hovered`	`boolean` Включает состояние наведения. По умолчанию: `-`
`selected`	`boolean` Включает состояние выбранного элемента списка. По умолчанию: `-`

ChipsSelect

DropZone