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

Анатомия

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

Storybook

Вариации

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

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

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

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 разрешает выбрать несколько значений, chips показывает их тегами CdsTag, а closable-chips добавляет крестик — значение снимается прямо в поле. Своё значение добавляется клавишей Enter — как «Медиация» в примере, её нет в списке. Поисковый запрос после каждого выбора очищается автоматически (clear-on-select включён по умолчанию).

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 задаёт символы-разделители: ввод или вставка строки с ними разбивает её на отдельные значения. Работает только вместе с multiple; перенос строки — разделитель всегда, поэтому многострочный список из буфера превратится в набор значений даже без настройки.

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>

Слоты

Слоты меню и поля — те же, что у 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

В отличие от автокомплита, hide-no-data включён по умолчанию: пустой результат просто закрывает меню, ведь введённое значение — само по себе валидный выход. Чтобы показать заглушку или слот no-data, передайте :hide-no-data="false".

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

Storybook

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

Получатели письма

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

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>

Пополнение справочника

Комбобокс мягко расширяет справочник: пользователь выбирает привычные значения из списка, а редкие вводит сам. Обработчик @update:focused при уходе из поля добавляет новое значение в items — в следующий раз оно найдётся поиском. Введите свою единицу измерения и кликните мимо поля — счётчик в подсказке вырастет.

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>

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

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

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

Пропсы

Имя	Тип	По умолчанию	Описание
active	boolean | undefined	—	Активное состояние поля
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
alwaysFilter	boolean | undefined	—	Фильтрует список даже когда поисковый запрос не менялся с момента последнего выбора.
appendIcon	IconValue | undefined	—	Иконка в слоте append после контента
appendInnerIcon	IconValue | undefined	—	Иконка во внутреннем слоте append после содержимого поля
autocomplete	string | undefined	'off'	Помогает влиять на предложения браузера. Значение «suppress» изменяет атрибут name полей, а значение «off» полагается на то, что браузер по собственной инициативе перестанет предлагать значения. Любое другое значение передается встроенной функции автозаполнения для соответствующего элемента.
autofocus	boolean | undefined	—	Включает автофокус
autoSelectFirst	boolean | "exact" | undefined	—	Подсвечивает первый подходящий элемент списка при вводе; Enter или Tab выбирают его. Значение exact подсвечивает только при полном совпадении поискового запроса с заголовком элемента.
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	string | undefined	—	Цвет фона компонента
centerAffix	boolean | undefined	—	Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру.
chips	boolean | undefined	—	Отображает выбранные значения в виде удаляемых чипов (CdsTag).
clearable	boolean | undefined	—	Отображать кнопку очистки значения
clearIcon	IconValue | undefined	'remove'	Иконка кнопки очистки
clearOnSelect	boolean | undefined	true	Очищает поисковый запрос после выбора элемента (актуально для multiple).
closableChips	boolean | undefined	—	Добавляет чипам кнопку удаления (актуально вместе с chips).
closeText	string | undefined	'$cds.close'	Текст для скринридеров, описывающий действие закрытия меню.
color	string | undefined	—	Цвет компонента
counter	string | number | boolean | undefined	—	Счетчик символов. Принимает булево значение, число или строку
counterValue	number | ((value: any) => number) | undefined	—	Пользовательское значение счетчика. Может быть числом или функцией вычисления от текущего значения
customFilter	FilterFunction | undefined	—	Своя функция фильтрации значений. Получает значение, поисковый запрос и элемент, возвращает совпадение или -1
customKeyFilter	FilterKeyFunctions | undefined	—	Отдельные функции фильтрации для конкретных ключей элемента — объект вида { ключ: функция }
delimiters	readonly string[] | undefined	—	Символы-разделители: ввод или вставка строки с ними разбивает её на несколько значений (только для multiple).
description	string | undefined	—	Описание компонента, отображаемое под меткой
disabled	boolean | null | undefined	null	Заблокированное состояние
eager	boolean | undefined	—	Рендерит контент меню заранее, не дожидаясь первого открытия.
ellipsis	boolean | undefined	—	В режиме multiple удерживает выбранные значения в одну строку с многоточием
error	boolean | undefined	—	Состояние ошибки
errorMessages	string | readonly string[] | null | undefined	[]	Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках. Будет объединяться с любыми проверками, заданными в свойстве rules. Это поле не запускает валидацию.
filterKeys	FilterKeys | undefined	['title']	Ключи элемента, по которым идёт поиск. По умолчанию фильтрация идёт по заголовку элемента
filterMode	FilterMode | undefined	'intersection'	Как объединяются результаты customKeyFilter и общей фильтрации: пересечением, объединением или заменой
focused	boolean | undefined	—	Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение.
hideDetails	boolean | "auto" | undefined	—	Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений
hideMessages	boolean | undefined	—	Скрыть сообщения под полем ввода
hideNoData	boolean | undefined	true	Скрывает меню и плейсхолдер «нет данных», когда список элементов пуст.
hideSelected	boolean | undefined	—	Скрывает уже выбранные элементы из списка меню.
hint	string | undefined	—	Текст подсказки, отображаемый под полем ввода
iconColor	string | boolean | undefined	—	Цвет иконки. Принимает булево значение или строку с цветом
id	string | undefined	—	Уникальный идентификатор компонента
isSelectAll	string | boolean | undefined	false	Добавляет первым элементом списка пункт «Выбрать все» (только для multiple). true использует надпись по умолчанию $cds.selectAll, строка задаёт собственную надпись.
itemChildren	SelectItemKey	false	Свойство объекта, содержащее дочерние элементы, либо функция для их получения
itemColor	string | undefined	—	Цвет выбранных элементов в списке меню. По умолчанию используется color.
itemProps	SelectItemKey	'props'	Свойство объекта, содержащее пропсы для элемента, либо функция для их получения
items	any[] | undefined	[]	Массив элементов для отображения
itemTitle	SelectItemKey	'title'	Свойство объекта, используемое как заголовок элемента, либо функция для его получения
itemType	SelectItemKey	'type'	Свойство объекта, определяющее тип элемента (item, divider, subheader), либо функция для его получения
itemValue	SelectItemKey	'value'	Свойство объекта, используемое как значение элемента, либо функция для его получения
label	string | undefined	—	Текст метки (label) компонента
listProps	CdsListProps | undefined	—	Пропсы, прокидываемые во внутренний компонент CdsList.
loading	string | boolean | undefined	—	Индикатор загрузки для компонента
maxErrors	string | number | undefined	1	Максимальное число отображаемых ошибок при валидации
maxWidth	string | number | undefined	—	Максимальная ширина компонента
menu	boolean | undefined	—	Управляет состоянием открытия выпадающего меню (v-model:menu).
menuHeight	string | number | undefined	178	Максимальная высота выпадающего меню.
menuIcon	IconValue | undefined	'chevron-down'	Иконка-индикатор раскрытия меню.
menuProps	CdsMenuProps | undefined	—	Пропсы, прокидываемые во внутренний компонент CdsMenu.
messages	string | readonly string[] | undefined	[]	Сообщения для отображения под полем ввода
minWidth	string | number | undefined	—	Минимальная ширина компонента
modelModifiers	Record<string, boolean> | undefined	—	Модификаторы v-model, переданные Vue для обработки значения поля
modelValue	any	null	Значение компонента в v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив.
multiple	boolean | undefined	—	Разрешает выбор нескольких значений. Выбранные элементы отображаются чипами или списком.
name	string | undefined	—	Имя поля ввода
noDataText	string | undefined	'$cds.noDataText'	Текст, отображаемый в меню, когда список элементов пуст.
noFilter	boolean | undefined	—	Отключает встроенную фильтрацию — список показывается как есть, поиск обрабатывается снаружи
openOnClear	boolean | undefined	—	Открывает меню после очистки значения.
openText	string | undefined	'$cds.open'	Текст для скринридеров, описывающий действие открытия меню.
persistentClearable	boolean | undefined	—	Всегда отображать кнопку очистки, а не только при наведении или фокусе
persistentCounter	boolean | undefined	—	Всегда отображать счетчик, а не только при взаимодействии с полем
persistentHint	boolean | undefined	—	Всегда отображать подсказку, а не только при фокусе
persistentPlaceholder	boolean | undefined	—	Всегда отображать placeholder, а не скрывать его при взаимодействии с полем
placeholder	string | undefined	—	Текст-заполнитель, отображаемый в пустом поле
prefix	string | undefined	—	Текстовый префикс, отображаемый перед значением поля
prependIcon	IconValue | undefined	—	Иконка в слоте prepend перед контентом
prependInnerIcon	IconValue | undefined	—	Иконка во внутреннем слоте prepend перед содержимым поля
readonly	boolean | null | undefined	null	Только для чтения
returnObject	boolean | undefined	true	Возвращать в значении модели объект вместо массива
reverse	boolean | undefined	—	Обратный порядок расположения элементов внутри поля
role	string | undefined	'combobox'	ARIA-роль для нативного элемента ввода
rules	readonly ValidationRule[] | undefined	[]	Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой.
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
suffix	string | undefined	—	Текстовый суффикс, отображаемый после значения поля
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента
transition	string | boolean | (TransitionProps & { component?: Component | undefined; }) | { component: Component; } | null | undefined	{ component: CdsModalTransition }	Анимация перехода
type	string | undefined	'text'	Тип нативного поля ввода
validateOn	ValidateOn | undefined	—	Изменяет тип события, при котором запускается валидация
valueComparator	ValueComparator | undefined	—	Функция сравнения значений элементов для определения выбранного состояния
width	string | 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]	Изменение поискового запроса.
update:selectedAll	[value: boolean]	Изменение состояния «выбраны все» (только для multiple + isSelectAll).

Слоты

Имя	Тип	Описание
append	CdsInputSlot	Добавляет элемент после поля ввода
append-inner	CdsInputDefaultSlot	Слот, добавляемый в конце инпута ввода
append-item	any	Контент после списка элементов в меню.
chip	{ item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; }	Кастомный рендеринг чипа выбранного значения (актуально вместе с chips).
clear	CdsInputDefaultSlot & { props: Record<string, any>; }	Слот для пользовательского иконки очистки (отображается, когда свойство clearable имеет значение «true»).
description	{ description: string | undefined; props: Record<string, any>; }	Слот по умолчанию для компонента CdsDescription
details	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
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
loader	LoaderSlotProps	Слот для пользовательского загрузчика (отображается, если свойство loading имеет значение true).
menu-footer	{ search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; }	Контент подвала меню. Получает текущий поисковый запрос и отфильтрованные элементы.
menu-header	{ search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; }	Контент шапки меню. Получает текущий поисковый запрос и отфильтрованные элементы.
message	CdsMessageSlot	Слот для настройки содержания сообщения
messages	CdsInputSlot	Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений
no-data	any	Контент, отображаемый в меню, когда список элементов пуст.
prepend	CdsInputSlot	Добавляет элемент до поля ввода
prepend-inner	CdsInputDefaultSlot	Слот, добавляемый в начало инпута ввода
prepend-item	any	Контент перед списком элементов в меню.
selection	{ item: any; internalItem: ListItem<any>; index: number; }	Кастомный рендеринг выбранного значения в поле ввода.
subheader	{ props: Record<string, unknown>; index: number; }	Кастомный рендеринг подзаголовка группы в списке меню.

Exposed

Имя	Тип	Описание
controlRef	HTMLElement | undefined	Ref-ссылка на контролл поля ввода
fieldIconColor	string | undefined	Цвет иконки
filteredItems	ListItem<any>[]	Элементы, отфильтрованные по текущему поисковому запросу.
isDirty	boolean	Является ли поле ввода "грязным"
isDisabled	boolean	Является ли поле ввода заблокированным
isFocused	boolean	Находится ли компонент в фокусе.
isPure	boolean	Не изменялся ли поисковый запрос с момента последнего выбора. Является ли поле ввода "чистым"
isReadonly	boolean	Является ли поле ввода только для чтения
isValid	boolean | null	Является ли поле ввода валидным
isValidating	boolean	Является ли поле ввода в процессе валидации
reset	() => Promise<void>	Функция сброса поля ввода в исходное состояние
resetValidation	() => Promise<void>	Функция сброса валидации поля ввода
search	string	Текущее значение поискового запроса.
selectAll	() => void	Переключить выбор всех доступных элементов (только для multiple + isSelectAll).
selectionIndex	number	Индекс выбранного значения, выделенного стрелками при навигации.
validate	(silent?: boolean) => Promise<string[]>	Функция валидации поля ввода