If the value must come from the list only, take CdsAutocomplete. If there are few options and free input is not needed — CdsSelect.

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 combobox repeats the variations of CdsSelect and CdsAutocomplete — grouping, "select all", filtering, auto-selecting the first item and menu settings. Below is what free input 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. The input filters the list but does not have to match an item: the typed text goes into the model right away — there is no need to press Enter or to pick an item.

Sandbox Storybook

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

const items = ['Git', 'GraphQL', 'Node.js', 'Python', 'TypeScript', 'Vue'];

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

<template>
  <div class="w-[350px] m-auto">
    <CdsCombobox
      v-model="selected"
      :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. Your own value is added with the Enter key — like "Медиация" in the example, which is not in the list. The search query is cleared automatically after every selection (clear-on-select is on by default).

Sandbox Storybook

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

const items = ref([
  'C#',
  'CSS',
  'Docker',
  'Figma',
  'Git',
  'GraphQL',
  'HTML',
  'Java',
  'JavaScript',
  'Kotlin',
  'Node.js',
  'PHP',
  'Python',
  'Rust',
  'SQL',
  'Swift',
  'TypeScript',
  'Vue'
]);

const selected = ref(['TypeScript', 'Медиация']);
</script>

<template>
  <CdsCombobox
    v-model="selected"
    class="w-[350px] m-auto"
    multiple
    chips
    closable-chips
    :items="items"
    label="Навыки"
    placeholder="Введите значение и нажмите Enter"
  />
</template>

Delimiters

The delimiters prop sets the delimiter characters: typing or pasting a string containing them splits it into separate values. It works together with multiple only; a line break is always a delimiter, so a multiline list from the clipboard turns into a set of values even without any configuration.

Sandbox Storybook

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

const items = ['аналитика', 'дизайн', 'разработка', 'тестирование'];

const selected = ref(['дизайн']);
</script>

<template>
  <CdsCombobox
    v-model="selected"
    class="w-[350px] m-auto"
    multiple
    chips
    closable-chips
    :delimiters="[',', ';']"
    :items="items"
    label="Ключевые слова"
    placeholder="Несколько значений — через запятую"
    description="Вставьте список из буфера — он разобьётся на отдельные значения"
  />
</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 combobox 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

Unlike in the autocomplete, hide-no-data is on by default: an empty result simply closes the menu, because the typed value is a valid outcome on its own. To show a placeholder or the no-data slot, pass :hide-no-data="false".

Guidelines

Storybook

Scenarios

Recipients of a letter

The combination of multiple, chips and closable-chips collects the recipients as tags, and delimiters splits a pasted list of addresses by commas and semicolons. filter-keys searches both by email and by name, hide-selected removes the already added ones from the list, and the item slot shows the avatar and the address. An address that is not in the reference book becomes a chip as is — external participants can be invited without being written into the contacts first.

Sandbox Storybook

<script setup lang="ts">
import { CdsAvatar, CdsCombobox, 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(['a.smirnova@example.com']);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsCombobox
      v-model="selected"
      multiple
      chips
      closable-chips
      hide-selected
      :items="people"
      item-title="email"
      item-value="email"
      :return-object="false"
      :filter-keys="['title', 'raw.name']"
      :delimiters="[',', ';']"
      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>
    </CdsCombobox>
  </div>
</template>

Growing the reference book

The combobox extends the reference book gently: the user picks the usual values from the list and types the rare ones. The @update:focused handler adds the new value to items when the field is left — next time it will be found by search. Enter your own unit of measurement and click outside the field — the counter in the hint will grow.

Sandbox Storybook

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

const items = ref(['Килограмм', 'Литр', 'Метр', 'Упаковка', 'Штука']);

const selected = ref('Штука');

const messages = computed(() => `В справочнике ${items.value.length} единиц`);

function onFocused(focused: boolean) {
  if (focused) return;

  const value = selected.value?.trim();
  if (value && !items.value.includes(value)) {
    items.value = [...items.value, value].sort((a, b) => a.localeCompare(b));
  }
}
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsCombobox
      v-model="selected"
      :items="items"
      :messages="messages"
      label="Единица измерения"
      placeholder="Выберите или введите свою"
      @update:focused="onFocused"
    />
  </div>
</template>

Submitting a form

The combobox takes part in CdsForm validation on a par with text fields: rules will not let the form through without a job title. Unlike in the autocomplete, it is exactly the typed text that is checked — the value goes into the model right away, picking a list item is not required.

Sandbox Storybook

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

const positions = ['Аналитик', 'Дизайнер', 'Инженер', 'Менеджер проектов', 'Разработчик', 'Тестировщик'];

const valid = ref(false);
const position = ref(null);
const department = 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">
    <CdsCombobox
      v-model="position"
      :items="positions"
      :rules="rules"
      label="Должность"
      placeholder="Выберите или введите свою"
    />

    <CdsTextInput v-model="department" label="Отдел" placeholder="Отдел разработки" />

    <CdsButton type="submit" :loading="loading" text="Создать вакансию" />

    <p v-if="sent" class="text-sm text-center">Вакансия создана</p>
  </CdsForm>
</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
alwaysFilter	boolean | undefined	—	Filters the list even when the search query has not changed since the last selection.
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	true	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 }
delimiters	readonly string[] | undefined	—	Delimiter characters: typing or pasting a string containing them splits it into several values (for multiple only).
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	true	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	true	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.
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.
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
search	string	Current value of the search query.
selectAll	() => void	Toggle the selection of all available items (for multiple + isSelectAll only).
selectionIndex	number	Index of the selected value highlighted by the arrow keys during navigation.
validate	(silent?: boolean) => Promise<string[]>	Validates the input