Skip to content

CdsAutocomplete

Автокомплит — поле выбора из длинного списка: пользователь вводит запрос, список фильтруется на лету, совпадения подсвечиваются. Поле построено на CdsTextInput, а меню и список — те же, что у CdsSelect, поэтому лейбл, сообщения, валидация и устройство меню работают одинаково.

Storybook GitLab Figma
Покрытие тестами: 83% — частичное покрытие
API в спеках
127 / 127 пропсы, события, слоты и exposed, у которых есть тест
Тест-кейсы
106 юнит · 11 браузерных
Известные баги
12 зафиксированы тестом it.fails
Покрытие кода
82.5% строк · 82.8% ветвей замер v4.0.0-alpha.13
A11y (axe)
3 рекомендаций в 11 историях замер v4.0.0-alpha.11

Если вариантов немного и поиск не нужен — возьмите CdsSelect. Если пользователь может вводить значения вне списка — CdsCombobox.

Анатомия ​

Первая схема — каркас компонента: лейбл, описание, поле и блок сообщений. Вторая — устройство самого поля: зона выбранного значения, кнопка очистки и индикатор меню; внутренние и внешние зоны иконок — те же, что у CdsTextInput.

Вариации ​

Автокомплит повторяет вариации CdsSelect — группировку, «Выбрать все», настройку списка и меню. Ниже — то, что добавляет поиск.

Элементы списка ​

Список задаёт проп items — массив строк или объектов с тем же интерфейсом, что у CdsList. Начните вводить — список отфильтруется по заголовкам элементов, совпавшие фрагменты подсветятся.

Sandbox Storybook

Поиск по нескольким полям ​

По умолчанию фильтр сравнивает запрос с заголовком элемента. Проп filter-keys расширяет область поиска: title — заголовок, raw.* — путь к полю исходного объекта. Своя логика сравнения задаётся функцией custom-filter, а no-filter отключает встроенную фильтрацию целиком — например, когда результаты уже отфильтрованы сервером.

Sandbox Storybook

Автовыбор первого элемента ​

Свойство auto-select-first подсвечивает первый подходящий элемент — Enter или Tab выбирают его без стрелок и клика. Значение exact подсвечивает элемент, только когда запрос совпал с заголовком полностью.

Sandbox Storybook

Множественный выбор и чипы ​

Свойство multiple разрешает выбрать несколько значений, chips показывает их тегами CdsTag, а closable-chips добавляет крестик — значение снимается прямо в поле. clear-on-select очищает поисковый запрос после каждого выбора, hide-selected убирает уже выбранные элементы из списка.

Sandbox Storybook

Слоты ​

Слоты меню и поля — те же, что у CdsSelect и CdsTextInput; примеры item, selection, chip и слотов меню смотрите на странице селекта — в автокомплите они работают так же.

Имя слотаОписание
itemЭлемент списка целиком; получает item, index и props
selectionВыбранное значение в поле
chipЧип выбранного значения (при chips)
prepend-item / append-itemКонтент до и после списка
no-dataКонтент меню при пустом результате поиска
subheader / dividerПодзаголовок и разделитель группы
menu-header / menu-footerШапка и подвал меню; получают search и filteredItems

Слот no-data в автокомплите видят чаще, чем в селекте: запрос легко опечатать. Свяжите запрос через v-model:search и предложите выход — например, добавить введённое значение в справочник.

Sandbox Storybook

Рекомендации ​

Сценарии использования ​

Поиск с сервера ​

Когда справочник слишком большой для загрузки целиком, ищите на сервере: v-model:search отдаёт запрос, ответ кладётся в items, а no-filter отключает повторную фильтрацию на клиенте. loading показывает, что идёт запрос, а слот no-data меняет надпись пустого меню по состоянию: подсказка до ввода, «Ищем…» во время запроса, «Ничего не найдено» после пустого ответа — меню никогда не остаётся пустым.

Sandbox Storybook

Выбор получателей ​

Сочетание multiple, chips, closable-chips и clear-on-select собирает получателей тегами и сразу готово к следующему вводу. filter-keys ищет и по имени, и по почте, hide-selected убирает уже добавленных из списка, а слот item показывает аватар и адрес — так проще не ошибиться в однофамильцах.

Sandbox Storybook

Отправка формы ​

Автокомплит участвует в валидации CdsForm наравне с текстовыми полями: rules не пропустит форму без выбранного города. Помните, что значением остаётся только выбранный элемент — набранный текст без выбора в модель не попадает.

Sandbox Storybook

Большой справочник ​

Меню рендерит элементы через виртуальную прокрутку, поэтому список на десятки тысяч позиций не тормозит ни при открытии, ни при фильтрации. auto-select-first ускоряет ввод: набрали номер — нажали Enter.

Sandbox Storybook

API ​

Пропсы

ИмяТипПо умолчаниюОписание
activeboolean | undefined—Активное состояние поля
activeColorstring | undefined—Цвет компонента, когда он находится в активном состоянии
appendIconIconValue | undefined—Иконка в слоте append после контента
appendInnerIconIconValue | undefined—Иконка во внутреннем слоте append после содержимого поля
autocompletestring | undefined'off'Помогает влиять на предложения браузера. Значение «suppress» изменяет атрибут name полей, а значение «off» полагается на то, что браузер по собственной инициативе перестанет предлагать значения. Любое другое значение передается встроенной функции автозаполнения для соответствующего элемента.
autofocusboolean | undefined—Включает автофокус
autoSelectFirstboolean | "exact" | undefined—Подсвечивает первый подходящий элемент списка при вводе; Enter или Tab выбирают его. Значение exact подсвечивает только при полном совпадении поискового запроса с заголовком элемента.
baseColorstring | undefined—Цвет неактивного компонента
bgColorstring | undefined—Цвет фона компонента
centerAffixboolean | undefined—Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру.
chipsboolean | undefined—Отображает выбранные значения в виде удаляемых чипов (CdsTag).
clearableboolean | undefined—Отображать кнопку очистки значения
clearIconIconValue | undefined'remove'Иконка кнопки очистки
clearOnSelectboolean | undefined—Очищает поисковый запрос после выбора элемента (актуально для multiple).
closableChipsboolean | undefined—Добавляет чипам кнопку удаления (актуально вместе с chips).
closeTextstring | undefined'$cds.close'Текст для скринридеров, описывающий действие закрытия меню.
colorstring | undefined—Цвет компонента
counterstring | number | boolean | undefined—Счетчик символов. Принимает булево значение, число или строку
counterValuenumber | ((value: any) => number) | undefined—Пользовательское значение счетчика. Может быть числом или функцией вычисления от текущего значения
customFilterFilterFunction | undefined—Своя функция фильтрации значений. Получает значение, поисковый запрос и элемент, возвращает совпадение или -1
customKeyFilterFilterKeyFunctions | undefined—Отдельные функции фильтрации для конкретных ключей элемента — объект вида { ключ: функция }
descriptionstring | undefined—Описание компонента, отображаемое под меткой
disabledboolean | null | undefinednullЗаблокированное состояние
eagerboolean | undefined—Рендерит контент меню заранее, не дожидаясь первого открытия.
ellipsisboolean | undefined—В режиме multiple удерживает выбранные значения в одну строку с многоточием
errorboolean | undefined—Состояние ошибки
errorMessagesstring | readonly string[] | null | undefined[]Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках. Будет объединяться с любыми проверками, заданными в свойстве rules. Это поле не запускает валидацию.
filterKeysFilterKeys | undefined['title']Ключи элемента, по которым идёт поиск. По умолчанию фильтрация идёт по заголовку элемента
filterModeFilterMode | undefined'intersection'Как объединяются результаты customKeyFilter и общей фильтрации: пересечением, объединением или заменой
focusedboolean | undefined—Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
hideDetailsboolean | "auto" | undefined—Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений
hideMessagesboolean | undefined—Скрыть сообщения под полем ввода
hideNoDataboolean | undefined—Скрывает меню и плейсхолдер «нет данных», когда список элементов пуст.
hideSelectedboolean | undefined—Скрывает уже выбранные элементы из списка меню.
hintstring | undefined—Текст подсказки, отображаемый под полем ввода
iconColorstring | boolean | undefined—Цвет иконки. Принимает булево значение или строку с цветом
idstring | undefined—Уникальный идентификатор компонента
isSelectAllstring | boolean | undefinedfalseДобавляет первым элементом списка пункт «Выбрать все» (только для multiple). true использует надпись по умолчанию $cds.selectAll, строка задаёт собственную надпись.
itemChildrenSelectItemKeyfalseСвойство объекта, содержащее дочерние элементы, либо функция для их получения
itemColorstring | undefined—Цвет выбранных элементов в списке меню. По умолчанию используется color.
itemPropsSelectItemKey'props'Свойство объекта, содержащее пропсы для элемента, либо функция для их получения
itemsany[] | undefined[]Массив элементов для отображения
itemTitleSelectItemKey'title'Свойство объекта, используемое как заголовок элемента, либо функция для его получения
itemTypeSelectItemKey'type'Свойство объекта, определяющее тип элемента (item, divider, subheader), либо функция для его получения
itemValueSelectItemKey'value'Свойство объекта, используемое как значение элемента, либо функция для его получения
labelstring | undefined—Текст метки (label) компонента
listPropsCdsListProps | undefined—Пропсы, прокидываемые во внутренний компонент CdsList.
loadingstring | boolean | undefined—Индикатор загрузки для компонента
maxErrorsstring | number | undefined1Максимальное число отображаемых ошибок при валидации
maxWidthstring | number | undefined—Максимальная ширина компонента
menuboolean | undefined—Управляет состоянием открытия выпадающего меню (v-model:menu).
menuHeightstring | number | undefined178Максимальная высота выпадающего меню.
menuIconIconValue | undefined'chevron-down'Иконка-индикатор раскрытия меню.
menuPropsCdsMenuProps | undefined—Пропсы, прокидываемые во внутренний компонент CdsMenu.
messagesstring | readonly string[] | undefined[]Сообщения для отображения под полем ввода
minWidthstring | number | undefined—Минимальная ширина компонента
modelModifiersRecord<string, boolean> | undefined—Модификаторы v-model, переданные Vue для обработки значения поля
modelValueanynullЗначение компонента в v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив.
multipleboolean | undefined—Разрешает выбор нескольких значений. Выбранные элементы отображаются чипами или списком.
namestring | undefined—Имя поля ввода
noDataTextstring | undefined'$cds.noDataText'Текст, отображаемый в меню, когда список элементов пуст.
noFilterboolean | undefined—Отключает встроенную фильтрацию — список показывается как есть, поиск обрабатывается снаружи
openOnClearboolean | undefined—Открывает меню после очистки значения.
openTextstring | undefined'$cds.open'Текст для скринридеров, описывающий действие открытия меню.
persistentClearableboolean | undefined—Всегда отображать кнопку очистки, а не только при наведении или фокусе
persistentCounterboolean | undefined—Всегда отображать счетчик, а не только при взаимодействии с полем
persistentHintboolean | undefined—Всегда отображать подсказку, а не только при фокусе
persistentPlaceholderboolean | undefined—Всегда отображать placeholder, а не скрывать его при взаимодействии с полем
placeholderstring | undefined—Текст-заполнитель, отображаемый в пустом поле
prefixstring | undefined—Текстовый префикс, отображаемый перед значением поля
prependIconIconValue | undefined—Иконка в слоте prepend перед контентом
prependInnerIconIconValue | undefined—Иконка во внутреннем слоте prepend перед содержимым поля
readonlyboolean | null | undefinednullТолько для чтения
returnObjectboolean | undefined—Возвращать в значении модели объект вместо массива
reverseboolean | undefined—Обратный порядок расположения элементов внутри поля
rolestring | undefined'combobox'ARIA-роль для нативного элемента ввода
rulesreadonly ValidationRule[] | undefined[]Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой.
searchstring | undefined—Текущее значение поискового запроса для фильтрации элементов (v-model:search).
sizenumber | "xs" | "sm" | "md" | "lg" | "xl" | undefined'md'Размер компонента
suffixstring | undefined—Текстовый суффикс, отображаемый после значения поля
textColorstring | undefined—Цвет текста компонента
themestring | undefined—Тема компонента
transitionstring | boolean | (TransitionProps & { component?: Component | undefined; }) | { component: Component; } | null | undefined{ component: CdsModalTransition }Анимация перехода
typestring | undefined'text'Тип нативного поля ввода
validateOnValidateOn | undefined—Изменяет тип события, при котором запускается валидация
valueComparatorValueComparator | undefined—Функция сравнения значений элементов для определения выбранного состояния
widthstring | number | undefined—Ширина компонента

События

ИмяТипОписание
update:focused[focused: boolean]Изменение состояния фокуса компонента (v-model:focused).
update:menu[value: boolean]Изменение состояния открытия выпадающего меню (v-model:menu).
update:modelValue[value: any]Изменение выбранного значения (v-model).
update:search[value: string]Изменение поискового запроса (v-model:search).
update:selectedAll[value: boolean]Изменение состояния «выбраны все» (только для multiple + isSelectAll).

Слоты

ИмяТипОписание
appendCdsInputSlotДобавляет элемент после поля ввода
append-innerCdsInputDefaultSlotСлот, добавляемый в конце инпута ввода
append-itemanyКонтент после списка элементов в меню.
chip{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }Кастомный рендеринг чипа выбранного значения (актуально вместе с chips).
clearCdsInputDefaultSlot & { props: Record<string, any>; }Слот для пользовательского иконки очистки (отображается, когда свойство clearable имеет значение «true»).
description{ description: string | undefined; props: Record<string, any>; }Слот по умолчанию для компонента CdsDescription
detailsCdsInputSlotСлот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
divider{ props: Record<string, unknown>; index: number; }Кастомный рендеринг разделителя в списке меню.
item{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }Кастомный рендеринг элемента списка в меню.
label{ label: string | undefined; props: Record<string, any>; }Слот по умолчанию для компонента CdsLabel
loaderLoaderSlotPropsСлот для пользовательского загрузчика (отображается, если свойство loading имеет значение true).
menu-footer{ search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; }Контент подвала меню. Получает текущий поисковый запрос и отфильтрованные элементы.
menu-header{ search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; }Контент шапки меню. Получает текущий поисковый запрос и отфильтрованные элементы.
messageCdsMessageSlotСлот для настройки содержания сообщения
messagesCdsInputSlotСлот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
no-dataanyКонтент, отображаемый в меню, когда список элементов пуст.
prependCdsInputSlotДобавляет элемент до поля ввода
prepend-innerCdsInputDefaultSlotСлот, добавляемый в начало инпута ввода
prepend-itemanyКонтент перед списком элементов в меню.
selection{ item: any; internalItem: ListItem<any>; index: number; }Кастомный рендеринг выбранного значения в поле ввода.
subheader{ props: Record<string, unknown>; index: number; }Кастомный рендеринг подзаголовка группы в списке меню.

Exposed

ИмяТипОписание
controlRefHTMLElement | undefinedRef-ссылка на контролл поля ввода
fieldIconColorstring | undefinedЦвет иконки
filteredItemsListItem<any>[]Элементы, отфильтрованные по текущему поисковому запросу.
isDirtybooleanЯвляется ли поле ввода "грязным"
isDisabledbooleanЯвляется ли поле ввода заблокированным
isFocusedbooleanНаходится ли компонент в фокусе.
isPurebooleanНе изменялся ли поисковый запрос с момента последнего выбора. Является ли поле ввода "чистым"
isReadonlybooleanЯвляется ли поле ввода только для чтения
isValidboolean | nullЯвляется ли поле ввода валидным
isValidatingbooleanЯвляется ли поле ввода в процессе валидации
reset() => Promise<void>Функция сброса поля ввода в исходное состояние
resetValidation() => Promise<void>Функция сброса валидации поля ввода
selectAll() => voidПереключить выбор всех доступных элементов (только для multiple + isSelectAll).
validate(silent?: boolean) => Promise<string[]>Функция валидации поля ввода