For two or three options take CdsRadioGroup — the options are visible right away. If the list is long and the user searches by typing, use CdsAutocomplete, and if values outside the list are allowed — 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 values, the clear button and the menu indicator; the inner and outer icon zones are the same as in CdsTextInput.

Storybook

Variations

List items

The list is set by the items prop — an array of strings or of objects with the same interface as in CdsList. While no value is selected, the field shows the placeholder.

Sandbox Storybook

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

const items = ['Первый', 'Второй', 'Третий', 'Четвёртый'];

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

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

Your own data fields

When the objects come from the server as they are, use item-title and item-value to say which fields the title and the value are taken from. return-object puts the whole object into v-model instead of just the value.

Sandbox Storybook

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

const select = ref({ lang: 'Русский', code: 'ru' });
const languages = ref([
  { lang: 'English', code: 'en' },
  { lang: 'Русский', code: 'ru' },
  { lang: 'Deutsch', code: 'de' },
  { lang: 'Français', code: 'fr' },
  { lang: 'Italiano', code: 'it' },
  { lang: 'Español', code: 'es' },
  { lang: 'Português', code: 'pt' },
  { lang: 'Nederlands', code: 'nl' },
  { lang: 'Polski', code: 'pl' },
  { lang: 'Svenska', code: 'sv' },
  { lang: 'Dansk', code: 'da' },
  { lang: 'Türkçe', code: 'tr' },
  { lang: '日本語', code: 'ja' },
  { lang: '中文', code: 'zh' },
  { lang: '한국어', code: 'ko' },
  { lang: 'العربية', code: 'ar' },
  { lang: 'עברית', code: 'he' }
]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsSelect
      v-model="select"
      :items="languages"
      item-title="lang"
      item-value="code"
      return-object
      label="Выберите язык"
      placeholder="Выбрать язык"
      :messages="select.lang + ' (' + select.code + ')'"
    />
  </div>
</template>

Grouping

Split a long list into meaningful blocks: an item with type: 'subheader' adds a subheader, one with type: 'divider' — a divider. Such items cannot be selected.

Sandbox Storybook

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

const items = [
  { type: 'subheader', title: 'Европа' },
  'Австрия',
  'Германия',
  'Франция',
  { type: 'divider' },
  { type: 'subheader', title: 'Азия' },
  'Китай',
  'Южная Корея',
  'Япония'
];

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

<template>
  <div class="w-[350px] m-auto">
    <CdsSelect v-model="selected" :items="items" label="Страна производства" placeholder="Выберите страну" />
  </div>
</template>

Multiple selection

The multiple prop allows selecting several values: the items get checkboxes and the field lists the selection separated by commas. ellipsis keeps the listing on a single line and cuts the rest off with an ellipsis.

Sandbox Storybook

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

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

const selected = ref([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsSelect v-model="selected" multiple :items="items" label="Множественный выбор" placeholder="Выбрать страну" />

    <CdsSelect
      v-model="selected"
      multiple
      ellipsis
      :items="items"
      label="Множественный выбор в строку"
      placeholder="Выбрать страну"
    />
  </div>
</template>

Selecting all the values

The is-select-all prop adds a "select all" entry as the first item of the list (works together with multiple). The true value uses the default caption, a string sets your own.

Sandbox Storybook

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

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

const selected = ref([]);
const selectedCustom = ref([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsSelect
      v-model="selected"
      multiple
      is-select-all
      :items="items"
      label="Множественный выбор с «Выбрать все»"
      placeholder="Выбрать страну"
    />

    <CdsSelect
      v-model="selectedCustom"
      multiple
      is-select-all="Отметить все страны"
      :items="items"
      label="Своя надпись «Выбрать все»"
      placeholder="Выбрать страну"
    />
  </div>
</template>

Chips

The chips prop shows the selected values as CdsTag tags, closable-chips adds a cross to them — a value is removed right in the field, without opening the menu.

Sandbox Storybook

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

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

const selected = ref(['Германия', 'Испания']);
const selectedClosable = ref(['Австрия', 'Италия', 'Франция']);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsSelect v-model="selected" multiple chips :items="items" label="Чипы" placeholder="Выбрать страну" />

    <CdsSelect
      v-model="selectedClosable"
      multiple
      chips
      closable-chips
      :items="items"
      label="Удаляемые чипы"
      placeholder="Выбрать страну"
    />
  </div>
</template>

Native list

The native-select prop replaces the custom menu with a native <select>: on mobile devices the system list is more familiar. Filtering, virtual scrolling and the menu slots do not work in this mode.

Sandbox Storybook

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

const items = ['Первый', 'Второй', 'Третий', 'Четвёртый'];

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

<template>
  <div class="w-[350px] m-auto">
    <CdsSelect
      v-model="selected"
      native-select
      :items="items"
      label="Выберите значение"
      placeholder="Выбрать значение"
    />
  </div>
</template>

Tuning the list

The list-props prop passes any props through to the inner CdsList — in the example bgColor paints the background of the menu, and slim removes the inner paddings of the menu so that the list fills it entirely. item-color sets the color of the selected items (color is taken by default). In the same way menu-props configures the inner CdsMenu, and menu-height limits the height of the menu.

Sandbox Storybook

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

const items = ['Яблоко', 'Апельсин', 'Банан', 'Груша'];

const selected = ref(['Яблоко']);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsSelect
      v-model="selected"
      multiple
      :items="items"
      :list-props="{ bgColor: 'other-cyan-fill', slim: true }"
      item-color="status-warning-fill"
      label="Выберите фрукты"
      placeholder="Выбрать фрукт"
    />
  </div>
</template>

Slots

The select gives up every part of the menu and the field for replacement. The slots of the field itself are the same as in CdsTextInput.

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 list is empty
subheader / divider	Group subheader and divider
menu-header / menu-footer	Menu header and footer; receive search and filteredItems

The item slot overrides the rendering of an item completely. Be sure to pass props into CdsListItem — the selection handler lives in them. In the example every country shows its flag and capital.

Sandbox Storybook

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

const countries = ref([
  { title: 'Австрия', flag: '🇦🇹', capital: 'Вена' },
  { title: 'Бельгия', flag: '🇧🇪', capital: 'Брюссель' },
  { title: 'Германия', flag: '🇩🇪', capital: 'Берлин' },
  { title: 'Греция', flag: '🇬🇷', capital: 'Афины' },
  { title: 'Испания', flag: '🇪🇸', capital: 'Мадрид' },
  { title: 'Италия', flag: '🇮🇹', capital: 'Рим' },
  { title: 'Нидерланды', flag: '🇳🇱', capital: 'Амстердам' },
  { title: 'Польша', flag: '🇵🇱', capital: 'Варшава' },
  { title: 'Португалия', flag: '🇵🇹', capital: 'Лиссабон' },
  { title: 'Финляндия', flag: '🇫🇮', capital: 'Хельсинки' },
  { title: 'Франция', flag: '🇫🇷', capital: 'Париж' },
  { title: 'Швеция', flag: '🇸🇪', capital: 'Стокгольм' }
]);
</script>

<template>
  <CdsSelect class="w-[350px] m-auto" :items="countries" label="Страны" placeholder="Выбрать страну">
    <template #item="{ item, props }">
      <CdsListItem v-bind="props" :title="item.title">
        <template #prepend>
          <span class="mr-3 text-2xl">{{ item.flag }}</span>
        </template>
        <template #description>
          Столица: <strong>{{ item.capital }}</strong>
        </template>
      </CdsListItem>
    </template>
  </CdsSelect>
</template>

The selection slot is your own display of what is selected in the field: the first two countries are shown as tags, the rest are folded into a counter.

Sandbox Storybook

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

const items = ref([
  'Австрия',
  'Бельгия',
  'Германия',
  'Греция',
  'Испания',
  'Италия',
  'Нидерланды',
  'Польша',
  'Португалия',
  'Франция',
  'Швеция'
]);
const selected = ref(['Португалия', 'Испания', 'Франция']);
</script>

<template>
  <CdsSelect
    v-model="selected"
    class="w-[350px] m-auto"
    multiple
    :items="items"
    label="Выберите страны"
    placeholder="Выбрать страну"
  >
    <template #selection="{ item, index }">
      <CdsTag v-if="index < 2" :text="item" size="sm" />

      <span v-if="index === 2" class="self-center text-sm text-gray-500"> (+{{ selected.length - 2 }} ещё) </span>
    </template>
  </CdsSelect>
</template>

The prepend-item and append-item slots add your own entries to the start and the end of the list. In the example the start holds "Select all countries" with a checkbox, and the end — "Load more" with a simulated fetch through loading.

Sandbox Storybook

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

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

const loading = ref(false);
const countries = ref(allCountries.slice(0, 3));
const selected = ref<string[]>([]);

const allSelected = computed(() => countries.value.length > 0 && selected.value.length === countries.value.length);
const someSelected = computed(() => selected.value.length > 0);
const hasMore = computed(() => countries.value.length < allCountries.length);

function selectingAll() {
  selected.value = allSelected.value ? [] : countries.value.slice();
}

async function addMore() {
  if (!hasMore.value) return;

  try {
    loading.value = true;
    await new Promise((resolve) => setTimeout(resolve, 1000));

    countries.value = [...countries.value, allCountries[countries.value.length]];
  } finally {
    loading.value = false;
  }
}
</script>

<template>
  <CdsSelect
    v-model="selected"
    class="w-[350px] m-auto"
    multiple
    :loading="loading"
    :items="countries"
    label="Страны"
    placeholder="Выбрать страну"
  >
    <template #prepend-item>
      <CdsListItem title="Выбрать все страны" link @click="selectingAll">
        <template #prepend>
          <CdsCheckbox
            :model-value="allSelected"
            :indeterminate="someSelected && !allSelected"
            tabindex="-1"
            hide-messages
          />
        </template>
      </CdsListItem>

      <CdsListItemDivider />
    </template>

    <template #append-item>
      <CdsListItemDivider />

      <CdsListItem v-if="hasMore" title="Добавить еще" prepend-icon="add" :disabled="loading" link @click="addMore" />
    </template>
  </CdsSelect>
</template>

The menu-header and menu-footer slots add content to the header and the footer of the menu — a search field and a confirmation button, for example. Both slots receive search (written into v-model:search, it filters the list) and filteredItems.

Sandbox Storybook

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

const items = ref([
  { id: 1, value: 'Австрия' },
  { id: 2, value: 'Бельгия' },
  { id: 3, value: 'Германия' },
  { id: 4, value: 'Греция' },
  { id: 5, value: 'Испания' },
  { id: 6, value: 'Италия' },
  { id: 7, value: 'Нидерланды' },
  { id: 8, value: 'Франция' },
  { id: 9, value: 'Португалия' }
]);
const model = ref([]);
const menu = ref(false);
</script>

<template>
  <CdsSelect
    v-model="model"
    v-model:menu="menu"
    class="w-[350px] m-auto"
    :items="items"
    item-title="value"
    item-value="id"
    multiple
    menu-height="280"
    label="Выберите страны"
    placeholder="Выбрать страну"
  >
    <template #menu-header="{ search, filteredItems }">
      <div class="p-2">
        <CdsTextInput
          v-model="search.value"
          :error="!!search.value && !filteredItems.length"
          placeholder="Поиск..."
          prepend-inner-icon="search"
          clearable
          hide-messages
        />
      </div>

      <CdsListItemDivider />
    </template>

    <template #menu-footer="{ search, filteredItems }">
      <CdsListItemDivider />

      <div class="flex items-center p-2 pl-4">
        <span v-if="search.value" class="text-sm text-brand-secondary-content">
          Найдено {{ filteredItems.length }} из {{ items.length }}
        </span>

        <CdsButton class="ml-auto" text="Принять" @click="menu = false" />
      </div>
    </template>
  </CdsSelect>
</template>

Guidelines

Storybook

Scenarios

Submitting a form

The select takes part in CdsForm validation on a par with text fields: rules will not let the form through without a chosen subject. Give optional fields a default value — that way the form is filled in faster.

Sandbox Storybook

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

const topics = ['Вопрос по заказу', 'Проблема с оплатой', 'Возврат товара', 'Другое'];
const priorities = ['Низкий', 'Средний', 'Высокий'];

const valid = ref(false);
const topic = ref(null);
const priority = 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">
    <CdsSelect v-model="topic" :items="topics" :rules="rules" label="Тема обращения" placeholder="Выберите тему" />

    <CdsSelect v-model="priority" :items="priorities" label="Приоритет" />

    <CdsButton type="submit" :loading="loading" text="Отправить" />

    <p v-if="sent" class="text-sm text-center">Обращение отправлено</p>
  </CdsForm>
</template>

Dependent lists

The list of cities depends on the chosen country: while there is no country the second select is turned off through disabled, and while the options are loading it shows loading. When the country changes the chosen city is reset — otherwise a non-existent pair would stay in the form.

Sandbox Storybook

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

const citiesByCountry: Record<string, string[]> = {
  Германия: ['Берлин', 'Гамбург', 'Мюнхен', 'Франкфурт'],
  Испания: ['Барселона', 'Валенсия', 'Мадрид', 'Севилья'],
  Франция: ['Лион', 'Марсель', 'Ницца', 'Париж']
};
const countries = Object.keys(citiesByCountry);

const country = ref<string | null>(null);
const city = ref<string | null>(null);
const cities = ref<string[]>([]);
const loading = ref(false);

watch(country, async (value) => {
  city.value = null;
  cities.value = [];
  if (!value) return;

  try {
    loading.value = true;
    await new Promise((resolve) => setTimeout(resolve, 800));
    cities.value = citiesByCountry[value];
  } finally {
    loading.value = false;
  }
});
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsSelect v-model="country" :items="countries" label="Страна" placeholder="Выберите страну" />

    <CdsSelect
      v-model="city"
      :items="cities"
      :loading="loading"
      :disabled="!country"
      label="Город"
      :placeholder="country ? 'Выберите город' : 'Сначала выберите страну'"
    />
  </div>
</template>

Picking assignees

The combination of multiple, chips and closable-chips shows the chosen people as tags and removes them by the cross right in the field. The item slot adds an avatar and a role — that way it is easier to find the right person in a long list.

Sandbox Storybook

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

const people = [
  { name: 'Анна Смирнова', role: 'Дизайнер', image: 'https://i.pravatar.cc/80?img=47' },
  { name: 'Дмитрий Орлов', role: 'Разработчик', image: 'https://i.pravatar.cc/80?img=12' },
  { name: 'Елена Васильева', role: 'Аналитик', image: 'https://i.pravatar.cc/80?img=44' },
  { name: 'Игорь Крылов', role: 'Разработчик', image: 'https://i.pravatar.cc/80?img=32' },
  { name: 'Мария Соколова', role: 'Тестировщик', image: 'https://i.pravatar.cc/80?img=26' },
  { name: 'Павел Зайцев', role: 'Менеджер проекта', image: 'https://i.pravatar.cc/80?img=59' }
];

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

<template>
  <div class="w-[350px] m-auto">
    <CdsSelect
      v-model="selected"
      multiple
      chips
      closable-chips
      :items="people"
      item-title="name"
      item-value="name"
      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.role }}</template>
        </CdsListItem>
      </template>
    </CdsSelect>
  </div>
</template>

Sorting the results

A compact select controls the order of a list: hide-messages removes the bottom block, aria-label replaces the hidden label for screen readers. The choice is applied at once — an "Apply" button is not needed.

Sandbox Storybook

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

const sortOptions = ['По алфавиту', 'Сначала дешевле', 'Сначала дороже'];
const sort = ref('По алфавиту');

const products = [
  { title: 'Кабель силовой', price: 1200 },
  { title: 'Автомат защиты', price: 350 },
  { title: 'Розетка накладная', price: 90 },
  { title: 'Щит распределительный', price: 4800 },
  { title: 'Светильник потолочный', price: 2100 }
];

const sorted = computed(() => {
  const items = [...products];

  if (sort.value === 'Сначала дешевле') return items.sort((a, b) => a.price - b.price);
  if (sort.value === 'Сначала дороже') return items.sort((a, b) => b.price - a.price);

  return items.sort((a, b) => a.title.localeCompare(b.title));
});
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsSelect v-model="sort" class="w-56 self-end" :items="sortOptions" aria-label="Сортировка" hide-messages />

    <CdsList>
      <CdsListItem v-for="product of sorted" :key="product.title" :title="product.title">
        <template #append>{{ product.price }} ₽</template>
      </CdsListItem>
    </CdsList>
  </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	—	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
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
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	—	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
nativeSelect	boolean | undefined	—	Renders a native HTML select instead of the custom dropdown menu (CdsMenu)
noAutoScroll	boolean | undefined	—	Turns off the automatic scrolling of the menu to the selected item on opening.
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	[ue: 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 input is pure
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