Select

Select — составной компонент из корневого контейнера состояния и экспортируемых дочерних частей для триггера, значения, вариантов и нативного участия в форме.

Storybook Исходники Figma

API корня

Select — корневой контейнер состояния для всей композиции.

Проп	Тип	По умолчанию
`disabled`	`boolean`	—
Отключён ли select. Запрещает взаимодействие и применяет стиль отключённого состояния.
`readOnly`	`boolean`	`false`
Если true, значение select нельзя изменить, но он остаётся фокусируемым.
`variant`	`SelectVariant`	`'field'`
Вариант визуального стиля элемента выбора.
`size`	`SelectSize`	`'md'`
Визуальный размер элемента выбора.
`value`	`V \| null`	—
Текущее выбранное значение (контролируемо). `null` очищает выбор, а `undefined` делает select неконтролируемым.
`defaultValue`	`V`	—
Значение, выбранное по умолчанию (неконтролируемо).
`onChangeValue`	`(value: V \| undefined) => void`	—
Колбэк, вызываемый при выборе варианта.
`ref`	`Ref<HTMLDivElement>`	—
Ref на корневой элемент.
`open`	`boolean`	—
Управляет состоянием открытия выпадающего списка Select. Если задан, Select становится контролируемым компонентом и по этому значению определяет, открыт список или закрыт.
`onChangeOpen`	`(open: boolean) => void`	—
Колбэк, вызываемый при изменении состояния открытия. Вызывается со следующим состоянием открытия (`true` или `false`) каждый раз, когда пользователь открывает или закрывает Select. Полезен для синхронизации состояния Select с внешней логикой.
`defaultOpen`	`boolean`	`false`
Задаёт начальное состояние открытия Select в неконтролируемом режиме. Применяется только при первом рендере и дальше игнорируется.
`typeahead`	`boolean`	`true`
Включает переход к варианту при наборе начала его подписи.

Также принимает все атрибуты <div>.

API дочерних частей

`SelectCombobox`

Видимая поверхность триггера select.

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLButtonElement>`	—
Ref на нижележащий элемент `<button>`. Полезен для управления фокусом, позиционирования и императивного доступа.

Также принимает все атрибуты <button>.

Типичные дочерние элементы: SelectValue, SelectIcon
Должна оставаться внутри Select

`SelectValue`

Рендерит выбранное значение или плейсхолдер.

Проп	Тип	По умолчанию
`placeholder`	`string`	—
Текст-заполнитель, который показывается, когда не выбран ни один вариант. Отображается, когда значение select пустое или undefined. После выбора значения заполнитель заменяется содержимым выбранного варианта.
`ref`	`Ref<HTMLSpanElement>`	—
Ref, передаваемый на корневой элемент span.

Также принимает все атрибуты <span>.

Поддерживает содержимое плейсхолдера
Может рендерить собственные дочерние элементы для более богатого отображения выбранного значения

`SelectIcon`

Необязательная визуальная подсказка триггера.

Проп	Тип	По умолчанию
`size`	`IconSize`	—
Предопределённый токен размера иконки. Может быть переопределён явными шириной и высотой.
`ref`	`Ref<SVGSVGElement>`	—
Ref на SVG-элемент
`strokeWidth`	`number`	—
Толщина обводки линий и фигур SVG (в px или pt).
`children`	`ReactNode`	—
Содержимое иконки (обязательно). Принимает: иконки из `~/icons`; собственный встроенный SVG; компоненты иконок сторонних библиотек (например, Lucide, Tabler)

Также принимает все HTML-атрибуты.

Обычно рендерится в конце SelectCombobox
Чисто визуальная, если намеренно не добавлено собственное взаимодействие

`SelectListbox`

Контейнер зарегистрированных вариантов.

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLDivElement>`	—
Ref на элемент-контейнер списка. Можно использовать для императивного доступа, например для измерений.

Также принимает все атрибуты <div>.

Ожидаемые дочерние элементы: SelectOption
Обычное место для ограничений прокрутки, полей поиска и собственного макета списка
Рендерится в top layer через popover="manual" и сам управляет фокусом

`SelectOption`

Выбираемый элемент списка.

Проп	Тип	По умолчанию
`value`обязательный	`V`	—
Значение этого варианта, которое передаётся в колбэк изменения при его выборе.
`label`	`string`	—
Простой текст варианта для поиска при наборе; используется вместо текста его содержимого.
`children`	`ReactNode`	—
Содержимое, отображаемое для этого варианта. Может включать текст, иконки или сложную разметку.
`size`	`OptionSize`	—
Размер варианта для визуальной стилизации.
`disabled`	`boolean`	—
Отключает весь Option.
`ref`	`Ref<HTMLDivElement>`	—
Ref, передаваемый на корневой div варианта.

Также принимает все атрибуты <div>.

value должен быть string или number
Сам регистрируется в модели вариантов корня
Может рендерить более богатое дочернее содержимое, но значение выбора остаётся скалярным

`SelectHiddenSelect`

Скрытый нативный элемент select.

Также принимает все атрибуты <select>.

Рекомендуется для форм
Помогает с нативной отправкой и интеграцией с инструментами для форм

Хуки

`useSelectContext`

Продвинутый хук для собственных обёрток вокруг готовых частей.

Используйте его, только когда экспортируемых частей недостаточно для нужной композиции.

Типы

Тип	Определение	Примечания
`SelectProps<V extends string \| number = string>`	Тип пропсов корня	Обобщённый тип значения для выбора.
`SelectSize`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| string`	Токен визуального размера.
`SelectVariant`	`'inline' \| 'field' \| string`	Визуальный вариант триггера.

Модель состояния

Выбранное значение может быть контролируемым через value или неконтролируемым через defaultValue.
Состояние открытия может быть контролируемым через open или неконтролируемым через defaultOpen.
Навигацией с клавиатуры, активным вариантом и поиском при наборе управляет корень.
value={null} очищает контролируемое значение, а undefined делает select неконтролируемым.
typeahead={false} рекомендуется, когда внутри списка рендерится настоящее текстовое поле.

Заметки по интеграции

Используйте SelectHiddenSelect, когда значение должно участвовать в нативной отправке формы.
Список рендерится в top layer, поэтому overflow, трансформации и модальные диалоги не обрезают и не перекрывают его.
Избегайте значений-объектов. Публичный API рассчитан только на значения string и number.