If there are few options and search is not needed, take CdsSelect. If the user may enter values outside the list — CdsCombobox.

Anatomy

The first diagram shows the frame of the component: the label, the description, the field and the messages block. The second one shows how the field itself is built: the zone of the selected value, the clear button and the menu indicator; the inner and outer icon zones are the same as in CdsTextInput.

Storybook

Variations

The autocomplete repeats the variations of CdsSelect — grouping, "select all", list and menu settings. Below is what search adds.

List items

The list is set by the items prop — an array of strings or of objects with the same interface as in CdsList. Start typing and the list is filtered by item titles, with the matching fragments highlighted.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete } from '@central-design-system/components';
import { ref } from 'vue';

const items = ['Австрия', 'Бельгия', 'Болгария', 'Венгрия', 'Германия', 'Греция', 'Дания', 'Ирландия'];

const selected = ref(null);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsAutocomplete
      v-model="selected"
      :items="items"
      label="Страна"
      placeholder="Начните вводить"
      description="Вспомогательное описание для выбора из списка"
    />
  </div>
</template>

Search across several fields

By default the filter compares the query with the item title. The filter-keys prop widens the search area: title — the title, raw.* — a path to a field of the source object. Your own comparison logic is set by the custom-filter function, and no-filter turns the built-in filtering off entirely — when the results are already filtered by the server, for example.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete } from '@central-design-system/components';
import { ref } from 'vue';

const people = [
  { name: 'Анна Смирнова', role: 'Дизайнер' },
  { name: 'Дмитрий Орлов', role: 'Разработчик' },
  { name: 'Елена Васильева', role: 'Аналитик' },
  { name: 'Игорь Крылов', role: 'Разработчик' },
  { name: 'Мария Соколова', role: 'Тестировщик' },
  { name: 'Павел Зайцев', role: 'Менеджер проекта' }
];

const selected = ref(null);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsAutocomplete
      v-model="selected"
      :items="people"
      item-title="name"
      item-value="name"
      :filter-keys="['title', 'raw.role']"
      label="Сотрудник"
      placeholder="Имя или роль"
      description="Попробуйте ввести «разработчик»"
    />
  </div>
</template>

Auto-selecting the first item

The auto-select-first prop highlights the first matching item — Enter or Tab select it without arrow keys or a click. The exact value highlights an item only when the query matches its title completely.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete } from '@central-design-system/components';
import { ref } from 'vue';

const items = ['Австрия', 'Бельгия', 'Болгария', 'Венгрия', 'Германия', 'Греция', 'Дания', 'Ирландия'];

const first = ref(null);
const exact = ref(null);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsAutocomplete
      v-model="first"
      auto-select-first
      :items="items"
      label="Автовыбор первого"
      placeholder="Начните вводить"
      description="Введите «гер» и нажмите Enter"
    />

    <CdsAutocomplete
      v-model="exact"
      auto-select-first="exact"
      :items="items"
      label="Только при полном совпадении"
      placeholder="Начните вводить"
      description="Подсветится только полностью введённая «Германия»"
    />
  </div>
</template>

Multiple selection and chips

The multiple prop allows selecting several values, chips shows them as CdsTag tags, and closable-chips adds a cross — the value is removed right in the field. clear-on-select clears the search query after every selection, hide-selected removes the already selected items from the list.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete } from '@central-design-system/components';
import { ref } from 'vue';

const items = ref([
  'Австрия',
  'Бельгия',
  'Болгария',
  'Венгрия',
  'Германия',
  'Греция',
  'Дания',
  'Ирландия',
  'Испания',
  'Италия',
  'Кипр',
  'Латвия',
  'Литва',
  'Люксембург',
  'Мальта',
  'Нидерланды',
  'Польша',
  'Португалия',
  'Румыния',
  'Словакия',
  'Словения',
  'Финляндия',
  'Франция',
  'Хорватия',
  'Чехия',
  'Швеция',
  'Эстония'
]);

const selected = ref(['Германия', 'Франция']);
</script>

<template>
  <CdsAutocomplete
    v-model="selected"
    class="w-[350px] m-auto"
    multiple
    chips
    closable-chips
    clear-on-select
    :items="items"
    label="Множественный выбор"
    placeholder="Начните вводить"
  />
</template>

Slots

The menu and field slots are the same as in CdsSelect and CdsTextInput; for examples of item, selection, chip and the menu slots see the select page — in the autocomplete they work the same way.

Slot name	Description
item	The whole list item; receives item, index and props
selection	The selected value in the field
chip	The chip of a selected value (with chips)
prepend-item / append-item	Content before and after the list
no-data	Menu content when the search result is empty
subheader / divider	Group subheader and divider
menu-header / menu-footer	Menu header and footer; receive search and filteredItems

The no-data slot is seen more often in the autocomplete than in the select: a query is easy to mistype. Bind the query through v-model:search and offer a way out — adding the entered value to the reference book, for example.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete, CdsButton } from '@central-design-system/components';
import { ref } from 'vue';

const items = ref(['Отдел продаж', 'Отдел закупок', 'Бухгалтерия', 'Юридический отдел']);

const selected = ref<string | null>(null);
const search = ref('');

function addItem() {
  items.value = [...items.value, search.value];
  selected.value = search.value;
}
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsAutocomplete
      v-model="selected"
      v-model:search="search"
      :items="items"
      label="Отдел"
      placeholder="Начните вводить название"
    >
      <template #no-data>
        <div class="flex flex-col items-start gap-2 p-4">
          <span class="text-sm">По запросу «{{ search }}» ничего не найдено.</span>
          <CdsButton variant="soft" color="brand" size="sm" :text="`Добавить «${search}»`" @click="addItem" />
        </div>
      </template>
    </CdsAutocomplete>
  </div>
</template>

Guidelines

Storybook

Scenarios

Search on the server

When the reference book is too large to load in full, search on the server: v-model:search gives out the query, the response goes into items, and no-filter turns off the repeated filtering on the client. loading shows that a request is in progress, and the no-data slot changes the caption of the empty menu by state: a hint before the input, "Searching…" during the request, "Nothing found" after an empty response — the menu never stays blank.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete, CdsListItem } from '@central-design-system/components';
import { computed, ref, watch } from 'vue';

const cities = [
  'Барнаул',
  'Владивосток',
  'Волгоград',
  'Воронеж',
  'Екатеринбург',
  'Казань',
  'Краснодар',
  'Красноярск',
  'Москва',
  'Нижний Новгород',
  'Новосибирск',
  'Омск',
  'Пермь',
  'Ростов-на-Дону',
  'Самара',
  'Санкт-Петербург',
  'Саратов',
  'Тюмень',
  'Уфа',
  'Челябинск'
];

const items = ref<string[]>([]);
const selected = ref(null);
const search = ref('');
const loading = ref(false);

const noDataText = computed(() => {
  if (loading.value) return 'Ищем…';
  return search.value ? 'Ничего не найдено' : 'Начните вводить название';
});

let timer: ReturnType<typeof setTimeout>;

watch(search, (query) => {
  clearTimeout(timer);

  if (!query) {
    items.value = [];
    loading.value = false;
    return;
  }

  loading.value = true;

  // Имитация запроса к серверу: фильтрация выполняется на «бэкенде».
  timer = setTimeout(() => {
    items.value = cities.filter((city) => city.toLowerCase().includes(query.toLowerCase()));
    loading.value = false;
  }, 600);
});
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsAutocomplete
      v-model="selected"
      v-model:search="search"
      no-filter
      :items="items"
      :loading="loading"
      label="Город"
      placeholder="Начните вводить название"
      hint="Результаты приходят с сервера"
    >
      <template #no-data>
        <CdsListItem :title="noDataText" />
      </template>
    </CdsAutocomplete>
  </div>
</template>

Picking recipients

The combination of multiple, chips, closable-chips and clear-on-select collects the recipients as tags and is immediately ready for the next input. filter-keys searches both by name and by email, hide-selected removes the already added ones from the list, and the item slot shows the avatar and the address — that way it is easier not to confuse namesakes.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete, CdsAvatar, CdsListItem } from '@central-design-system/components';
import { ref } from 'vue';

const people = [
  { name: 'Анна Смирнова', email: 'a.smirnova@example.com', image: 'https://i.pravatar.cc/80?img=47' },
  { name: 'Дмитрий Орлов', email: 'd.orlov@example.com', image: 'https://i.pravatar.cc/80?img=12' },
  { name: 'Елена Васильева', email: 'e.vasileva@example.com', image: 'https://i.pravatar.cc/80?img=44' },
  { name: 'Игорь Крылов', email: 'i.krylov@example.com', image: 'https://i.pravatar.cc/80?img=32' },
  { name: 'Мария Соколова', email: 'm.sokolova@example.com', image: 'https://i.pravatar.cc/80?img=26' },
  { name: 'Павел Зайцев', email: 'p.zaycev@example.com', image: 'https://i.pravatar.cc/80?img=59' }
];

const selected = ref(['Анна Смирнова']);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsAutocomplete
      v-model="selected"
      multiple
      chips
      closable-chips
      clear-on-select
      hide-selected
      :items="people"
      item-title="name"
      item-value="name"
      :filter-keys="['title', 'raw.email']"
      label="Получатели"
      placeholder="Имя или почта"
    >
      <template #item="{ item, props }">
        <CdsListItem v-bind="props" :title="item.name">
          <template #prepend>
            <CdsAvatar :image="item.image" size="sm" class="mr-3" />
          </template>
          <template #description>{{ item.email }}</template>
        </CdsListItem>
      </template>
    </CdsAutocomplete>
  </div>
</template>

Submitting a form

The autocomplete takes part in CdsForm validation on a par with text fields: rules will not let the form through without a chosen city. Remember that only the selected item stays as the value — text typed without a selection does not get into the model.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete, CdsButton, CdsForm, CdsTextInput } from '@central-design-system/components';
import { ref } from 'vue';

const cities = [
  'Владивосток',
  'Волгоград',
  'Екатеринбург',
  'Казань',
  'Краснодар',
  'Москва',
  'Нижний Новгород',
  'Новосибирск',
  'Санкт-Петербург',
  'Челябинск'
];

const valid = ref(false);
const city = ref(null);
const street = ref('');
const loading = ref(false);
const sent = ref(false);

const rules = [(value: string) => !!value || 'Выберите город из списка'];

async function submit() {
  if (!valid.value) return;

  try {
    loading.value = true;
    sent.value = false;
    await new Promise((resolve) => setTimeout(resolve, 1500));
    sent.value = true;
  } finally {
    loading.value = false;
  }
}
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsAutocomplete
      v-model="city"
      :items="cities"
      :rules="rules"
      label="Город доставки"
      placeholder="Начните вводить"
    />

    <CdsTextInput v-model="street" label="Улица и дом" placeholder="Тверская, 1" />

    <CdsButton type="submit" :loading="loading" text="Оформить доставку" />

    <p v-if="sent" class="text-sm text-center">Заявка отправлена</p>
  </CdsForm>
</template>

A large reference book

The menu renders items through virtual scrolling, so a list of tens of thousands of entries does not slow down either on opening or on filtering. auto-select-first speeds up the input: type the number — press Enter.

Sandbox Storybook

<script setup lang="ts">
import { CdsAutocomplete } from '@central-design-system/components';
import { ref } from 'vue';

const items = Array.from({ length: 10000 }, (_, index) => `Артикул ${String(index + 1).padStart(5, '0')}`);

const selected = ref(null);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsAutocomplete
      v-model="selected"
      auto-select-first
      :items="items"
      label="Позиция каталога"
      placeholder="Начните вводить номер"
      :description="`В списке ${items.length.toLocaleString('ru-RU')} позиций`"
    />
  </div>
</template>

API

Props

Name	Type	Default	Description
active	boolean | undefined	—	Active state of the field
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
appendInnerIcon	IconValue | undefined	—	Icon in the inner append slot, after the content of the field
autocomplete	string | undefined	'off'	Helps to influence browser suggestions. The suppress value changes the name attribute of the fields, and off relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element.
autofocus	boolean | undefined	—	Enables autofocus
autoSelectFirst	boolean | "exact" | undefined	—	Highlights the first matching item as you type; Enter or Tab select it. The exact value highlights it only on a full match of the search query with the item title.
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
centerAffix	boolean | undefined	—	Vertically center the appendInner, prependInner, clearIcon and label elements.
chips	boolean | undefined	—	Shows the selected values as removable chips (CdsTag).
clearable	boolean | undefined	—	Shows the clear button
clearIcon	IconValue | undefined	'remove'	Icon of the clear button
clearOnSelect	boolean | undefined	—	Clears the search query after an item is selected (relevant for multiple).
closableChips	boolean | undefined	—	Adds a remove button to the chips (relevant together with chips).
closeText	string | undefined	'$cds.close'	Text for screen readers describing the close action of the menu.
color	string | undefined	—	Component color
counter	string | number | boolean | undefined	—	Character counter. Accepts a boolean, a number or a string
counterValue	number | ((value: any) => number) | undefined	—	Custom counter value. Either a number or a function computing it from the current value
customFilter	FilterFunction | undefined	—	Your own value filtering function. Receives the value, the search query and the item, returns a match or -1
customKeyFilter	FilterKeyFunctions | undefined	—	Separate filtering functions for specific item keys — an object of the form { key: function }
description	string | undefined	—	Description of the component, shown under the label
disabled	boolean | null | undefined	null	Disabled state
eager	boolean | undefined	—	Renders the menu content upfront, without waiting for the first opening.
ellipsis	boolean | undefined	—	In multiple mode keeps the selected values on a single line with an ellipsis
error	boolean | undefined	—	Error state
errorMessages	string | readonly string[] | null | undefined	[]	Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the rules prop. This field does not trigger validation.
filterKeys	FilterKeys | undefined	['title']	Item keys the search runs over. By default filtering goes by the item title
filterMode	FilterMode | undefined	'intersection'	How the results of customKeyFilter and of the general filtering are combined: by intersection, by union or by replacement
focused	boolean | undefined	—	Controls the focus state of the component. When true, the component is considered focused and may apply the corresponding styles or behavior.
hideDetails	boolean | "auto" | undefined	—	Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages
hideMessages	boolean | undefined	—	Hide the messages under the input
hideNoData	boolean | undefined	—	Hides the menu and the "no data" placeholder when the item list is empty.
hideSelected	boolean | undefined	—	Hides the already selected items from the menu list.
hint	string | undefined	—	Hint text shown under the input
iconColor	string | boolean | undefined	—	Icon color. Accepts a boolean or a color string
id	string | undefined	—	Unique identifier of the component
isSelectAll	string | boolean | undefined	false	Adds a "select all" entry as the first item of the list (for multiple only). true uses the default $cds.selectAll caption, a string sets your own caption.
itemChildren	SelectItemKey	false	Object field that holds the child items, or a function that returns them
itemColor	string | undefined	—	Color of the selected items in the menu list. color is used by default.
itemProps	SelectItemKey	'props'	Object field that holds the props of the item, or a function that returns them
items	any[] | undefined	[]	Array of items to display
itemTitle	SelectItemKey	'title'	Object field used as the item title, or a function that returns it
itemType	SelectItemKey	'type'	Object field that defines the item type (item, divider, subheader), or a function that returns it
itemValue	SelectItemKey	'value'	Object field used as the item value, or a function that returns it
label	string | undefined	—	Label text of the component
listProps	CdsListProps | undefined	—	Props passed through to the inner CdsList component.
loading	string | boolean | undefined	—	Loading indicator for the component
maxErrors	string | number | undefined	1	Maximum number of validation errors shown
maxWidth	string | number | undefined	—	Maximum component width
menu	boolean | undefined	—	Controls the open state of the dropdown menu (v-model:menu).
menuHeight	string | number | undefined	178	Maximum height of the dropdown menu.
menuIcon	IconValue | undefined	'chevron-down'	Icon indicating that the menu can be expanded.
menuProps	CdsMenuProps | undefined	—	Props passed through to the inner CdsMenu component.
messages	string | readonly string[] | undefined	[]	Messages shown under the input
minWidth	string | number | undefined	—	Minimum component width
modelModifiers	Record<string, boolean> | undefined	—	v-model modifiers passed by Vue to process the field value
modelValue	any	null	Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default.
multiple	boolean | undefined	—	Allows selecting several values. The selected items are shown as chips or as a list.
name	string | undefined	—	Name of the input
noDataText	string | undefined	'$cds.noDataText'	Text shown in the menu when the item list is empty.
noFilter	boolean | undefined	—	Turns off the built-in filtering — the list is shown as is, the search is handled outside
openOnClear	boolean | undefined	—	Opens the menu after the value is cleared.
openText	string | undefined	'$cds.open'	Text for screen readers describing the open action of the menu.
persistentClearable	boolean | undefined	—	Always show the clear button, not only on hover or focus
persistentCounter	boolean | undefined	—	Always show the counter, not only while the field is in use
persistentHint	boolean | undefined	—	Always show the hint, not only on focus
persistentPlaceholder	boolean | undefined	—	Always show the placeholder instead of hiding it while the field is in use
placeholder	string | undefined	—	Placeholder text shown in an empty field
prefix	string | undefined	—	Text prefix shown before the field value
prependIcon	IconValue | undefined	—	Icon in the prepend slot, before the content
prependInnerIcon	IconValue | undefined	—	Icon in the inner prepend slot, before the content of the field
readonly	boolean | null | undefined	null	Read-only state
returnObject	boolean | undefined	—	Return an object in the model value instead of an array
reverse	boolean | undefined	—	Reverses the order of the elements inside the field
role	string | undefined	'combobox'	ARIA role for the native input element
rules	readonly ValidationRule[] | undefined	[]	Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string.
search	string | undefined	—	Current value of the search query used to filter the items (v-model:search).
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
suffix	string | undefined	—	Text suffix shown after the field value
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | { component: Component; } | null | undefined	{ component: CdsModalTransition }	Transition animation
type	string | undefined	'text'	Type of the native input
validateOn	ValidateOn | undefined	—	Changes the type of the event that triggers validation
valueComparator	ValueComparator | undefined	—	Function that compares item values to determine the selected state
width	string | number | undefined	—	Component width

Events

Name	Type	Description
update:focused	[focused: boolean]	The focus state of the component changed (v-model:focused).
update:menu	[value: boolean]	The open state of the dropdown menu changed (v-model:menu).
update:modelValue	[value: any]	The selected value changed (v-model).
update:search	[value: string]	The search query changed (v-model:search).
update:selectedAll	[value: boolean]	The "all selected" state changed (for multiple + isSelectAll only).

Slots

Name	Type	Description
append	CdsInputSlot	Adds an element after the input
append-inner	CdsInputDefaultSlot	Slot added at the end of the input
append-item	any	Content after the item list in the menu.
chip	{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }	Custom rendering of the chip of a selected value (relevant together with chips).
clear	CdsInputDefaultSlot & { props: Record<string, any>; }	Slot for a custom clear icon (shown when the clearable prop is true).
description	{ description: string | undefined; props: Record<string, any>; }	Default slot of the CdsDescription component
details	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
divider	{ props: Record<string, unknown>; index: number; }	Custom rendering of a divider in the menu list.
item	{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }	Custom rendering of an item of the menu list.
label	{ label: string | undefined; props: Record<string, any>; }	Default slot of the CdsLabel component
loader	LoaderSlotProps	Slot for a custom loader (shown when the loading prop is true).
menu-footer	{ search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; }	Content of the menu footer. Receives the current search query and the filtered items.
menu-header	{ search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; }	Content of the menu header. Receives the current search query and the filtered items.
message	CdsMessageSlot	Slot for customizing the content of a message
messages	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
no-data	any	Content shown in the menu when the item list is empty.
prepend	CdsInputSlot	Adds an element before the input
prepend-inner	CdsInputDefaultSlot	Slot added at the start of the input
prepend-item	any	Content before the item list in the menu.
selection	{ item: any; internalItem: ListItem<any>; index: number; }	Custom rendering of the selected value inside the field.
subheader	{ props: Record<string, unknown>; index: number; }	Custom rendering of a group subheader in the menu list.

Exposed

Name	Type	Description
controlRef	HTMLElement | undefined	Ref to the control of the input
fieldIconColor	string | undefined	Icon color
filteredItems	ListItem<any>[]	Items filtered by the current search query.
isDirty	boolean	Whether the input is dirty
isDisabled	boolean	Whether the input is disabled
isFocused	boolean	Whether the component is focused.
isPure	boolean	Whether the search query has not changed since the last selection.
isReadonly	boolean	Whether the input is read-only
isValid	boolean | null	Whether the input is valid
isValidating	boolean	Whether the input is being validated
reset	() => Promise<void>	Resets the input to its initial state
resetValidation	() => Promise<void>	Resets the validation of the input
selectAll	() => void	Toggle the selection of all available items (for multiple + isSelectAll only).
validate	(silent?: boolean) => Promise<string[]>	Validates the input