Combobox
Поле со списком ARIA с фильтрацией и выбором одного или нескольких значений.
- Браузеры
- Chrome 114+Firefox 125+Safari 17+
- Уровень
- 2
- Сжатый размер
- 5.18 kB
- Лимит принудительной компоновки
- 0 ms
- Лимит axe
- 0
- Совместим с SSR
- Да
- Публичный контракт
- Тестовый стенд
Песочница
Combobox
По умолчанию
Яблоко
Банан
Вишня
Финик
Множественный выбор
ReactUI
React
UI
TypeScript
Доступность
Дизайн-системы
Открыт
Яблоко
Банан
Вишня
Финик
Большой
API
Combobox.Root
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
children | ReactNode | — | Части Combobox: control, tags, input, trigger и content. |
items* | ComboboxItemData[] | — | Полный список вариантов для фильтрации полем ввода. |
defaultInputValue | string | — | Начальный текст поля ввода при неуправляемом значении. |
defaultOpen | boolean | — | Открыт ли список изначально при неуправляемом состоянии открытия. |
defaultValue | string | readonly string[] | — | Значение или значения, выбранные при первом рендеринге, если выбор неуправляемый. |
multiple | boolean | false | Позволяет выбирать и удалять несколько значений в виде тегов. |
allowCustomValue | boolean | false | Позволяет выбирать введённый текст, которого нет в items. |
addOnPaste | boolean | true | Добавляет несколько разделённых значений из вставленного текста в множественном режиме. |
delimiters | readonly string[] | [","] | Символы, которые подтверждают или разделяют введённые значения в множественном режиме. |
maxValues | number | — | Максимальное число выбираемых значений в множественном режиме. |
validateValue | (value: string) => boolean | — | Отклоняет собственное значение, если возвращает false. |
filterFn | (items: ComboboxItemData[], inputValue: string) => ComboboxItemData[] | — | Заменяет встроенный фильтр, который сужает список при вводе. |
inputValue | string | — | Текст поля ввода, делающий введённое значение управляемым. |
onInputValueChange | (value: string) => void | — | Вызывается с новым текстом при каждом изменении поля ввода. |
onOpenChange | (open: boolean, details: OpenChangeDetails) => void | — | Вызывается при открытии или закрытии списка с указанием причины изменения. |
onValueChange | ((value: string) => void) | ((value: string[]) => void) | — | Вызывается с выбранным значением или полным массивом выбранных значений. |
open | boolean | — | Открыт ли список; делает состояние открытия управляемым. |
value | string | readonly string[] | — | Выбранное значение или значения; делает выбор управляемым. |
Combobox.Control
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
children | ReactNode | — | Теги и поле ввода внутри общего визуального элемента управления. |
className | string | — | Класс элемента управления. |
render | ReactElement | ((props, state) => ReactElement) | — | Заменяет отображаемый элемент, сохраняя поведение и связи доступности. |
Combobox.Tags
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
children | ReactNode | — | Содержимое после созданных удаляемых тегов. |
className | string | — | Класс контейнера созданных тегов. |
render | ReactElement | ((props, state) => ReactElement) | — | Заменяет отображаемый элемент, сохраняя поведение и связи доступности. |
Combobox.Input
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
className | string | — | Класс текстового поля ввода. |
render | ReactElement | ((props, state) => ReactElement) | — | Заменяет отображаемый элемент, сохраняя поведение и связи доступности. |
Combobox.Trigger
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
children | ReactNode | — | Содержимое кнопки открытия списка, например иконка. |
className | string | — | Класс кнопки триггера. |
render | ReactElement | ((props, state) => ReactElement) | — | Заменяет отображаемый элемент, сохраняя поведение и связи доступности. |
Combobox.Content
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
align | "start" | "center" | "end" | — | Выравнивание списка относительно поля ввода вдоль выбранной стороны. |
children* | (filteredItems: ComboboxItemData[]) => ReactNode | — | Функция рендеринга, вызываемая с пунктами, оставшимися после фильтрации. |
className | string | — | Класс всплывающего списка. |
side | "top" | "right" | "bottom" | "left" | — | Сторона поля ввода, с которой размещается список. |
Combobox.Item
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
className | string | — | Класс элемента варианта. |
item* | ComboboxItemData | — | Пункт, отображаемый этим вариантом; обычно берётся из обратного вызова содержимого. |
Combobox.Empty
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
children | ReactNode | — | Содержимое, показываемое, если после фильтрации не осталось пунктов. |
className | string | — | Класс элемента пустого состояния. |
ComboboxItemData
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
disabled | boolean | — | Запрещает выбор этого пункта. |
label* | string | — | Текст пункта, который отображается и проверяется фильтром. |
value* | string | — | Значение, сообщаемое при выборе пункта. |
Клавиатура
| Клавиша | Действие |
|---|---|
| ↓ / ↑ | Открыть список и перемещаться между вариантами |
| Enter | Выбрать |
| Escape | Закрыть |
| a–z | Фильтровать варианты вводом символов |
Доступность
ARIA combobox и listbox. Активный вариант озвучивается через aria-activedescendant. Content отражает открытое/закрытое состояние; варианты — состояния выделения, отключения и, в множественном режиме, выбора. Используйте Empty, чтобы объяснить отсутствие совпадений. При предпочтении уменьшенного движения анимация появления всплывающего блока отключается.
Привязка стилей
data-statedata-highlighteddata-disableddata-selected