---
description: Компонент для выбора значения из выпадающего списка.
tags: selection
---
# CustomSelect [tag:component]
Компонент для выбора значения из выпадающего списка.
Поддерживает широкие возможности по изменению внешнего вида, поиск по опциям и пользовательский рендеринг опций.
Связанные компоненты:
- [`Select`](/components/select)
> Важно: для отображения невыбранного состояния нужно использовать `value=null` вместо `undefined`.
>
> `undefined` ипользуется только для неконтролируемого компонента.
{/* @example-description: Базовый `CustomSelect` с набором опций и кнопкой очистки выбора. */}
```jsx
```
## Режим работы
Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).
Для использования неконтролируемого режима достаточно просто _не_ передавать `value` или передавать `defaultValue`, если
требуется задать значение по умолчанию.
Для контролируемого режима используйте связку свойств `value`/`onChange` для задания значения и его изменения.
```jsx
const colors = [
{
value: 'red',
label: 'Красный',
},
{
value: 'green',
label: 'Зелёный',
},
{
value: 'blue',
label: 'Синий',
},
];
// Неконтролируемое состояние
;
// Контролируемое состояние
const [color, setColor] = React.useState('red');
setColor(newColor)} />;
```
## Состояния
### `disabled`
Свойство `disabled` блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.
{/* @example-description: `CustomSelect` в неактивном состоянии с предвыбранным значением. */}
```jsx
```
## Валидация
Свойство `status` используется для визуализации валидации компонента - некорректности заполненного поля (значение `"error"`)
или успешной валидации (значение `"valid"`).
> Если вы используете `CustomSelect` вместе с [`FormItem`](/components/form-item), вам достаточно указать свойство `status` только у
> [`FormItem`](/components/form-item).
{/* @example-description: Варианты валидации `CustomSelect` со статусами `error` и `valid`. */}
```jsx
```
## Кастомизация
### Визуальное оформление
С помощью свойства `renderOption` можно влиять на отображение конкретного элемента выпадающего списка.
Вы можете изменить стандартный компонент [`CustomSelectOption`](#customselectoption) или использовать свой компонент.
{/* @example-description: Кастомный рендер опций `CustomSelect` с дополнительным описанием города. */}
```jsx
(
)}
/>
```
## Кастомное поведение при поиске
Пример показывает, как реализовать кастомное поведение поиска: при вводе сохраняется локальный `query`, при отсутствии совпадений в списке появляется опция «Добавить пользователя …»,
её выбор добавляет новый элемент в `options` — вместе с пользовательским рендером опций это даёт удобный UX для создания элементов на лету.
{/* @example-description: Кастомный поиск с возможностью добавления новой опции прямо из выпадающего списка. */}
```jsx
const users = [
{
id: 58690866,
first_name: 'Эльдар',
last_name: 'Мухаметханов',
screen_name: 'e.muhamethanov',
},
{
id: 1771114,
first_name: 'Ином',
last_name: 'Мирджамолов',
screen_name: 'inomdzhon',
},
{
id: 16790455,
first_name: 'Вика',
last_name: 'Жижонкова',
screen_name: 'BlackySoul',
},
{
id: 117253521,
first_name: 'Даниил',
last_name: 'Суворов',
screen_name: 'SevereCloud',
},
{
id: 99539515,
first_name: 'Никита',
last_name: 'Денисов',
screen_name: 'qurle',
},
{
id: 296221155,
first_name: 'Алексей',
last_name: 'Зайцев',
screen_name: 'Zaycevq',
},
];
const getUsers = (usersArray) =>
usersArray.map((user) => ({
label: `${user.first_name} ${user.last_name}`,
value: `${user.id}`,
description: user.screen_name,
}));
const [value, setValue] = React.useState('');
const [query, setQuery] = React.useState('');
const [newUsers, setNewUsers] = React.useState([...getUsers(users)]);
const customSearchOptions = () => {
const options = [...newUsers];
if (query.length > 0 && !options.find((user) => user.value === query || user.label === query)) {
options.unshift({
label: `Добавить пользователя ${query}`,
value: '0',
});
}
return options;
};
const onCustomSearchChange = (_, newValue) => {
if (newValue === '0') {
setNewUsers([...newUsers, { label: query, value: query }]);
setValue(query);
} else {
setValue(newValue);
}
setQuery('');
};
const onCustomSearchInputChange = (e) => {
setQuery(e.target.value);
};
return (
(
{option.label}
)}
onChange={onCustomSearchChange}
/>
);
```
## Кастомный алгоритм поиска
Демонстрация кастомного алгоритма поиска иллюстрирует передачу `filterFn` для гибкого соответствия (по `label` и `description`),
поддержку `searchable` и кастомного рендера опций — полезно, когда нужно искать по нескольким полям или использовать нестандартные критерии.
{/* @example-description: Кастомный алгоритм фильтрации опций через `filterFn` по нескольким полям. */}
```jsx
const cities = [
{
label: 'Санкт-Петербург',
description: 'Россия',
value: '0',
},
{
label: 'Москва',
description: 'Россия',
value: '1',
},
{
label: 'Новосибирск',
description: 'Россия',
disabled: true,
value: '2',
},
{
label: 'Нью-Йорк',
description: 'США',
value: '3',
},
{
label: 'Чикаго',
description: 'США',
value: '4',
},
];
const customSearchFilter = (value, option) =>
option.label.toLowerCase().includes(value.toLowerCase()) ||
option.description.toLowerCase().includes(value.toLowerCase());
return (
(
)}
options={cities}
/>
);
```
## Асинхронная загрузка списка
Асинхронный пример показывает подгрузку опций с задержкой/дебаунсом, управление состояниями `fetching`/`remoteQuery`,
минимальную длину запроса, очистку таймаутов и возможность заменить содержимое выпадающего списка (например, подсказкой «введите хотя бы три символа») — стандартный шаблон для работы с удалёнными API.
{/* @example-description: Асинхронная подгрузка опций `CustomSelect` с поиском, дебаунсом и состоянием загрузки. */}
```jsx
const users = [
{
id: 58690866,
first_name: 'Эльдар',
last_name: 'Мухаметханов',
screen_name: 'e.muhamethanov',
},
{
id: 1771114,
first_name: 'Ином',
last_name: 'Мирджамолов',
screen_name: 'inomdzhon',
},
{
id: 16790455,
first_name: 'Вика',
last_name: 'Жижонкова',
screen_name: 'BlackySoul',
},
{
id: 117253521,
first_name: 'Даниил',
last_name: 'Суворов',
screen_name: 'SevereCloud',
},
{
id: 99539515,
first_name: 'Никита',
last_name: 'Денисов',
screen_name: 'qurle',
},
{
id: 296221155,
first_name: 'Алексей',
last_name: 'Зайцев',
screen_name: 'Zaycevq',
},
];
const getUsers = (usersArray) =>
usersArray.map((user) => ({
label: `${user.first_name} ${user.last_name}`,
value: `${user.id}`,
description: user.screen_name,
}));
const [searchable, setSearchable] = React.useState(false);
const [remoteQuery, setRemoteQuery] = React.useState('');
const [fetching, setFetching] = React.useState(false);
const [remoteUsers, setRemoteUsers] = React.useState([]);
let timeout;
const cleanFetchingTimeout = () => {
if (timeout) {
clearTimeout(timeout);
}
};
const fetchRemoteUsers = () => {
setFetching(true);
timeout = setTimeout(() => {
setRemoteUsers([...getUsers(users)]);
setFetching(false);
cleanFetchingTimeout();
}, 1500);
};
const searchRemoteUsers = (e) => {
const _remoteQuery = e.target.value;
cleanFetchingTimeout();
setRemoteQuery(_remoteQuery);
if (_remoteQuery.length < 3) {
setRemoteUsers([]);
setFetching(false);
} else {
fetchRemoteUsers();
}
};
const clearRemoteUsers = () => {
setRemoteUsers([]);
setRemoteQuery('');
cleanFetchingTimeout();
};
const renderDropdown = ({ defaultDropdownContent }) => {
if (remoteQuery.length < 3) {
return (
Нужно ввести хотя бы три символа
);
}
return defaultDropdownContent;
};
React.useEffect(() => {
return () => cleanFetchingTimeout();
}, []);
return (
{
console.log('CLOSED [async CustomSelect]');
}}
fetching={fetching}
renderDropdown={searchable && !fetching && renderDropdown}
/>
{
setSearchable(e.target.checked);
clearRemoteUsers();
}}
>
Использовать поиск
);
```
## CustomSelectOption [#custom-select-option]
Универсальный компонент для отрисовки одного из значений в выпадающем списке.
Передавайте данный компонент в свойство `renderOption`, для кастомизации значений выпадающего списка.
Помимо `CustomSelect` используется и в `ChipsSelect`.
{/* @example-description: Базовый пример `CustomSelectOption` с иконками в `before` и `after`. */}
```jsx
} after={}>
Иван Иванов
```
Для реализации многоуровневых `CustomSelectOption` используйте свойство `hierarchy`,
которое позволяет создать нужный отступ в зависимости от уровня вложенности.
{/* @example-description: Многоуровневые опции с отступами через свойство `hierarchy`. */}
```jsx
ДискПапкаФайл 1
Файл 2
```
## Тестирование (e2e) [#e2e]
Для поиска компонента и его элементов на странице cуществует ряд вспомогательных свойств:
По умолчанию все `data-*` атрибуты попадают на `` компонента, это значит, что при передаче
`data-testid` или `data-test-id` идентификатор попадёт ``.
Доступ к полю ввода может быть полезен для:
- получения текста, введённого пользователем при поиске опций, в режиме `searchable`;
- получения информации о наличии фокуса на компоненте;
- симуляции работы с компонентом с клавиатуры.
Используйте `labelTextTestId`:
- для симуляции работы с компонентом с помощью мыши, тач-устройства;
- для получения текста выбранной в данный момент опции.
Для взаимодействия с кнопкой очистки состояния компонента, которая появляется,
если `CustomSelect` имеет свойство `searchable` и пользователь выбрал опцию, используйте свойство `clearButtonTestId`.
`CustomSelect` внутри себя хранит невидимый `