К содержимому
uiify

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

СвойствоТипПо умолчаниюОписание
childrenReactNode—Части Combobox: control, tags, input, trigger и content.
items*ComboboxItemData[]—Полный список вариантов для фильтрации полем ввода.
defaultInputValuestring—Начальный текст поля ввода при неуправляемом значении.
defaultOpenboolean—Открыт ли список изначально при неуправляемом состоянии открытия.
defaultValuestring | readonly string[]—Значение или значения, выбранные при первом рендеринге, если выбор неуправляемый.
multiplebooleanfalseПозволяет выбирать и удалять несколько значений в виде тегов.
allowCustomValuebooleanfalseПозволяет выбирать введённый текст, которого нет в items.
addOnPastebooleantrueДобавляет несколько разделённых значений из вставленного текста в множественном режиме.
delimitersreadonly string[][","]Символы, которые подтверждают или разделяют введённые значения в множественном режиме.
maxValuesnumber—Максимальное число выбираемых значений в множественном режиме.
validateValue(value: string) => boolean—Отклоняет собственное значение, если возвращает false.
filterFn(items: ComboboxItemData[], inputValue: string) => ComboboxItemData[]—Заменяет встроенный фильтр, который сужает список при вводе.
inputValuestring—Текст поля ввода, делающий введённое значение управляемым.
onInputValueChange(value: string) => void—Вызывается с новым текстом при каждом изменении поля ввода.
onOpenChange(open: boolean, details: OpenChangeDetails) => void—Вызывается при открытии или закрытии списка с указанием причины изменения.
onValueChange((value: string) => void) | ((value: string[]) => void)—Вызывается с выбранным значением или полным массивом выбранных значений.
openboolean—Открыт ли список; делает состояние открытия управляемым.
valuestring | readonly string[]—Выбранное значение или значения; делает выбор управляемым.

Combobox.Control

СвойствоТипПо умолчаниюОписание
childrenReactNode—Теги и поле ввода внутри общего визуального элемента управления.
classNamestring—Класс элемента управления.
renderReactElement | ((props, state) => ReactElement)—Заменяет отображаемый элемент, сохраняя поведение и связи доступности.

Combobox.Tags

СвойствоТипПо умолчаниюОписание
childrenReactNode—Содержимое после созданных удаляемых тегов.
classNamestring—Класс контейнера созданных тегов.
renderReactElement | ((props, state) => ReactElement)—Заменяет отображаемый элемент, сохраняя поведение и связи доступности.

Combobox.Input

СвойствоТипПо умолчаниюОписание
classNamestring—Класс текстового поля ввода.
renderReactElement | ((props, state) => ReactElement)—Заменяет отображаемый элемент, сохраняя поведение и связи доступности.

Combobox.Trigger

СвойствоТипПо умолчаниюОписание
childrenReactNode—Содержимое кнопки открытия списка, например иконка.
classNamestring—Класс кнопки триггера.
renderReactElement | ((props, state) => ReactElement)—Заменяет отображаемый элемент, сохраняя поведение и связи доступности.

Combobox.Content

СвойствоТипПо умолчаниюОписание
align"start" | "center" | "end"—Выравнивание списка относительно поля ввода вдоль выбранной стороны.
children*(filteredItems: ComboboxItemData[]) => ReactNode—Функция рендеринга, вызываемая с пунктами, оставшимися после фильтрации.
classNamestring—Класс всплывающего списка.
side"top" | "right" | "bottom" | "left"—Сторона поля ввода, с которой размещается список.

Combobox.Item

СвойствоТипПо умолчаниюОписание
classNamestring—Класс элемента варианта.
item*ComboboxItemData—Пункт, отображаемый этим вариантом; обычно берётся из обратного вызова содержимого.

Combobox.Empty

СвойствоТипПо умолчаниюОписание
childrenReactNode—Содержимое, показываемое, если после фильтрации не осталось пунктов.
classNamestring—Класс элемента пустого состояния.

ComboboxItemData

СвойствоТипПо умолчаниюОписание
disabledboolean—Запрещает выбор этого пункта.
label*string—Текст пункта, который отображается и проверяется фильтром.
value*string—Значение, сообщаемое при выборе пункта.

Клавиатура

КлавишаДействие
↓ / ↑Открыть список и перемещаться между вариантами
EnterВыбрать
EscapeЗакрыть
a–zФильтровать варианты вводом символов

Доступность

ARIA combobox и listbox. Активный вариант озвучивается через aria-activedescendant. Content отражает открытое/закрытое состояние; варианты — состояния выделения, отключения и, в множественном режиме, выбора. Используйте Empty, чтобы объяснить отсутствие совпадений. При предпочтении уменьшенного движения анимация появления всплывающего блока отключается.

Привязка стилей

data-statedata-highlighteddata-disableddata-selected