# Central Design System (CDS 4) — components

> Version: 4.0.0-alpha.13
> Documentation for all `@central-design-system/components` components: purpose, examples, and the full API contract.
> Generated automatically (`bun run generate:meta` → `bun run generate:llms`). Do not edit manually.

---

## Setup

```ts
import { createApp } from 'vue';
import '@central-design-system/components/styles';
import { createCds, components, directives } from '@central-design-system/components';
import App from './App.vue';

const cds = createCds({ components, directives });
createApp(App).use(cds).mount('#app');
```

Usage: `<CdsButton appearance="primary">Click me</CdsButton>`.

This is full registration: the `components` namespace import and the `styles`
aggregate keep the entire library in the bundle. It suits places where the set of
components is not known upfront (admin panels, sandboxes, documentation). In product
applications register components individually — `createCds({ components: { CdsButton } })`
plus the base style layer `@central-design-system/components/styles/common.css`;
see the "Tree-shaking" guide for details.

## Conventions

- **Uniform props.** `size`, `color` / `bgColor`, `appearance`, `disabled`, `loading`,
  `width` / `height` behave the same across all components (shared composable factories).
- **Tokens, not raw values.** Colors are set via the `color` prop, not arbitrary CSS.
- **Atomic Design.** Complex UI is assembled from atoms (e.g. a form:
  `CdsField` + `CdsLabel` + `CdsDescription` + `CdsMessages` + `CdsInput`).
- The full CDS 3 → CDS 4 migration guide lives in `MIGRATION.md`.

---

# CdsApp

_Category: Other_

_Tests: API 3/3 · 7 unit · lines 100% (v4.0.0-alpha.13)_

## API

### CdsApp

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `storybook` | `boolean \| "fluid" \| undefined` | `false` | no | Режим отображения внутри Storybook: убирает полноэкранную обёртку, `'fluid'` дополнительно снимает ограничение ширины |
| `theme` | `string \| undefined` | — | no | Component theme |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default slot |

---

# CdsAutocomplete

_Category: Controls · since 4.0.0_

_Tests: API 127/127 · 106 unit · 11 e2e · 12 known bugs · lines 82.5% (v4.0.0-alpha.13) · a11y: 3 axe recommendations (v4.0.0-alpha.11)_

An autocomplete is a field for picking from a long list: the user types a query, the list is filtered on the fly and the matches are highlighted. The field is built on CdsTextInput, and the menu and the list are the same as in CdsSelect, so the label, the messages, validation and the menu behave identically.

**See also:** 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.

## 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.

**Example — `Default.vue`:**

```vue
<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.

**Example — `Filtering.vue`:**

```vue
<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.

**Example — `AutoSelectFirst.vue`:**

```vue
<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.

**Example — `MultipleChips.vue`:**

```vue
<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.

**Example — `NoData.vue`:**

```vue
<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

| ✅ Do | ❌ Don't |
| --- | --- |
| An autocomplete pays off on a long list — typing a couple of letters is faster than scrolling. | Two or three options do not need a search: take CdsSelect or radio buttons. |
| If values outside the list are allowed, take CdsCombobox — what is typed is kept as is. | The autocomplete accepts list items only: text typed without a selection is lost. |
| An empty result explains what happened and suggests the next step. | A hidden menu (hide-no-data) looks like a breakage: the user does not understand why the list disappeared. |

## 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.

**Example — `ServerSearch.vue`:**

```vue
<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.

**Example — `Recipients.vue`:**

```vue
<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.

**Example — `FormSubmit.vue`:**

```vue
<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.

**Example — `LargeList.vue`:**

```vue
<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

### CdsAutocomplete

**Props**

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

---

# CdsAvatar

_Category: Content · since 4.0.0 · status: new_

_Tests: API 17/17 · 25 unit · 2 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 8 axe recommendations (v4.0.0-alpha.11)_

An avatar shows a person, a team or a company: a photo, initials or an icon inside a round container. Use it in member lists, comments and profile headers — anywhere the reader needs to recognize "who is this" at a glance.

**See also:** The built-in badge shows a status or a counter right on the avatar; for a marker on arbitrary content take CdsBadge, and for a text label inside a line — CdsTag.

## Anatomy

An avatar is a container with one of three kinds of content and an optional
badge in the top corner.

## Variations

### Content

The content comes from one of three props: `image` — a photo, `icon` — an
icon, `text` — initials. If you pass several of them, `image` wins, then
`icon`.

**Example — `Content.vue`:**

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

<template>
  <div class="flex justify-center gap-3">
    <CdsAvatar image="https://i.pravatar.cc/120?img=12" />
    <CdsAvatar icon="user" color="brand-secondary" />
    <CdsAvatar text="ВМ" color="brand-primary" />
  </div>
</template>
```

### Sizes

The `size` prop takes a token from `xs` to `xl` or a number of pixels. The
default size is `md`.

**Example — `Sizes.vue`:**

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

const sizes = CdsAvatar.constants.sizes;
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <div class="flex items-center justify-center gap-2">
      <CdsAvatar v-for="size in sizes" :key="size" :size="size" text="ВМ" color="brand-primary" />
      <CdsAvatar :size="72" text="ВМ" color="brand-primary" />
    </div>

    <div class="flex items-center justify-center gap-2">
      <CdsAvatar v-for="size in sizes" :key="size" :size="size" image="https://i.pravatar.cc/120?img=12" />
      <CdsAvatar :size="72" image="https://i.pravatar.cc/120?img=12" />
    </div>

    <div class="flex items-center justify-center gap-2">
      <CdsAvatar v-for="size in sizes" :key="size" :size="size" icon="user" color="brand-secondary" />
      <CdsAvatar :size="72" icon="user" color="brand-secondary" />
    </div>
  </div>
</template>
```

### Colors

The `color` prop paints the background of an avatar with initials or an icon:
a theme token or any CSS color will do.

**Example — `Colors.vue`:**

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

const items = [
  { color: 'brand-primary', text: 'BP' },
  { color: 'brand-secondary', text: 'BS' },
  { color: '#0f9d58', text: 'GR' },
  { color: '#db4437', text: 'RD' },
  { color: '#673ab7', text: 'PR' }
];
</script>

<template>
  <div class="flex justify-center gap-2">
    <CdsAvatar v-for="item in items" :key="item.text" size="md" :color="item.color" :text="item.text" />
  </div>
</template>
```

### Badge

The `badge` prop set to `true` shows a dot in the corner of the avatar. An
object is passed through as props of CdsBadge: this
is how you change the color of the dot, show a counter (`dot: false` plus
`content`) or move the badge away from the edge (`floating`). The `badge` slot
replaces the content of the badge with anything you like — an icon, for
example.

**Example — `Badge.vue`:**

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

<template>
  <div class="flex justify-center gap-3">
    <CdsAvatar size="lg" badge image="https://i.pravatar.cc/120?img=12" />
    <CdsAvatar size="lg" text="АД" color="brand-primary" :badge="{ color: 'status-success-surface' }" />
    <CdsAvatar size="lg" icon="user-group" color="brand-secondary" :badge="{ dot: false, content: 3 }" />
    <CdsAvatar size="lg" text="ОК" color="brand-secondary" :badge="{ dot: false, content: 12, floating: true }" />
    <CdsAvatar size="lg" image="https://i.pravatar.cc/120?img=32" :badge="{ color: 'status-success-surface' }">
      <template #badge>
        <CdsIcon icon="check" />
      </template>
    </CdsAvatar>
  </div>
</template>
```

### Spacing

The `start` and `end` props add a margin on the side of the neighboring
content: `start` — for an avatar at the beginning of a line, `end` — at the
end. This way the avatar fits into text without wrappers that carry outer
margins.

**Example — `Spacing.vue`:**

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

<template>
  <div class="flex flex-col gap-2">
    <div class="flex items-center justify-center">
      <CdsAvatar start size="sm" text="АД" color="brand-primary" />
      <span>Анна Дмитриева оставила комментарий</span>
    </div>

    <div class="flex items-center justify-center">
      <span>Задачу проверяет</span>
      <CdsAvatar end size="sm" image="https://i.pravatar.cc/80?img=32" />
    </div>
  </div>
</template>
```

### Slots

| Slot      | Description                                                |
| --------- | ---------------------------------------------------------- |
| `default` | Avatar content. Replaces `image`, `icon` and `text`        |
| `badge`   | Badge content. Shown instead of the dot when `badge` is on |

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Initials are one or two letters: the first letters of the first and last name. | Long text does not fit into the round container and gets cut off. |
| Inside one list keep avatars the same size — the row reads as a whole. | Different sizes read as different importance of the members. |
| A colored dot shows the status — it is noticeable and does not fight the content. | A text badge covers the avatar; for a caption there is the line next to it. |

## Scenarios

### Member list

In a list of people the avatar is a fast visual anchor. The `start` prop gives
the margin before the text, photos and initials alternate depending on what the
user has, and the badge dot shows who is online right now.

**Example — `MembersList.vue`:**

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

const members = [
  { name: 'Анна Дмитриева', role: 'Менеджер проекта', image: 'https://i.pravatar.cc/80?img=47', online: true },
  { name: 'Павел Соколов', role: 'Аналитик', text: 'ПС', color: 'brand-primary', online: false },
  { name: 'Мария Ильина', role: 'Дизайнер', image: 'https://i.pravatar.cc/80?img=32', online: true },
  { name: 'Служба поддержки', role: 'Общий канал', icon: 'user-group', color: 'brand-secondary', online: false }
];
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-3">
    <div v-for="member in members" :key="member.name" class="flex items-center">
      <CdsAvatar
        start
        :image="member.image"
        :icon="member.icon"
        :text="member.text"
        :color="member.color"
        :badge="member.online && { color: 'status-success-surface' }"
      />

      <div class="flex flex-col">
        <span>{{ member.name }}</span>
        <span class="text-200 text-content-secondary">{{ member.role }}</span>
      </div>
    </div>
  </div>
</template>
```

### Group of members

When there are many members and little space, avatars are stacked with a slight
overlap — a border in the background color separates the neighbors from each
other. The last avatar with `text="+3"` tells how many people did not fit.

**Example — `AvatarStack.vue`:**

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

const images = [
  'https://i.pravatar.cc/80?img=12',
  'https://i.pravatar.cc/80?img=47',
  'https://i.pravatar.cc/80?img=32',
  'https://i.pravatar.cc/80?img=56'
];
</script>

<template>
  <div class="flex items-center justify-center gap-3">
    <div class="avatar-stack flex items-center">
      <CdsAvatar v-for="image in images" :key="image" :image="image" />
      <CdsAvatar text="+3" color="brand-secondary" />
    </div>

    <span class="text-content-secondary">7 участников</span>
  </div>
</template>

<style scoped>
.avatar-stack .cds-avatar {
  border: 2px solid var(--cds-color-surface-primary);
}

.avatar-stack .cds-avatar:not(:first-child) {
  margin-inline-start: -8px;
}
</style>
```

### Uploading a profile photo

While there is no photo yet, the avatar shows the initials from `text` — the
page is not left with an empty circle. As soon as `image` gets a link, the photo
replaces the initials; after the photo is removed, the initials come back on
their own.

**Example — `ProfilePhoto.vue`:**

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

const image = ref('');
const loading = ref(false);

const upload = async () => {
  loading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 1200));

  image.value = 'https://i.pravatar.cc/160?img=47';
  loading.value = false;
};

const remove = () => {
  image.value = '';
};
</script>

<template>
  <div class="flex items-center justify-center gap-3">
    <CdsAvatar size="xl" :image="image" text="АД" color="brand-primary" />

    <CdsButton v-if="!image" prepend-icon="upload" text="Загрузить фото" :loading="loading" @click="upload" />
    <CdsButton v-else variant="soft" color="neutral" text="Удалить фото" @click="remove" />
  </div>
</template>
```

## API

### CdsAvatar

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `badge` | `boolean \| CdsBadgeProps \| undefined` | `false` | no | Avatar badge. `true` shows a dot, an object is passed through as `CdsBadge` props. |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `end` | `boolean \| undefined` | — | no | Adds a margin on the left — for an avatar at the end of a line of content. |
| `icon` | `IconValue \| undefined` | — | no | Icon shown in the avatar when no image is set. |
| `image` | `string \| undefined` | — | no | Source of the avatar image. Takes priority over `icon` and `text`. |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `start` | `boolean \| undefined` | — | no | Adds a margin on the right — for an avatar at the beginning of a line of content. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `badge` | `any` | Content of the avatar badge. |
| `default` | `any` | Avatar content. Overrides `image`, `icon` and `text`. |

---

# CdsBadge

_Category: Feedback · since 4.0.0_

_Tests: API 26/26 · 38 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 7 axe recommendations (v4.0.0-alpha.11)_

A badge is a small marker in the corner of an element or next to it: a counter of unread messages, a "there is something new" dot, a short label. A badge is not interactive — it draws attention to the element it is attached to instead of acting on its own.

**See also:** For a textual object status ("Done", "In progress") take CdsStatus, and CdsAvatar has a built-in `badge` prop for the common indicators on an avatar.

## Anatomy

The badge attaches to the element from the `default` slot and is positioned
relative to it. The content is a number or text from `content`, an icon from
`icon`, or the markup from the `badge` slot.

## Variations

### Content

The `content` prop sets what the badge shows — most often a counter of events.
By default the badge sits in the top right corner of the element from the slot.

**Example — `Default.vue`:**

```vue
<script setup lang="ts">
import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsBadge content="10">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>
```

The `max` prop caps the counter: anything above it collapses into "99+".
Without `max` the value is printed in full.

**Example — `WithMaxValue.vue`:**

```vue
<script setup lang="ts">
import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center gap-4">
    <CdsBadge content="150">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="150" :max="99">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>
```

Besides a number, `content` accepts a short text — a "new section" mark in a
menu, for example. Here the badge is placed into the line by the `inline` prop —
more on it in the positioning section.

**Example — `StringContent.vue`:**

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

<template>
  <CdsCard class="m-auto w-[200px]">
    <CdsList>
      <CdsListItem value="0">
        <template #title>Главная</template>
      </CdsListItem>
      <CdsListItem value="1">
        <template #title>Входящие</template>
        <template #append>
          <CdsBadge content="new" inline />
        </template>
      </CdsListItem>
      <CdsListItem value="2">
        <template #title>Исходящие</template>
      </CdsListItem>
    </CdsList>
  </CdsCard>
</template>
```

The `icon` prop shows an icon instead of text.

**Example — `WithIcon.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsBadge icon="check" inline />
  </div>
</template>
```

### Dot

The `dot` prop shrinks the badge to a dot and hides its content — only the
"there is something new" signal is left. The diameter is changed via `dot-size`.

**Example — `DotBadge.vue`:**

```vue
<script setup lang="ts">
import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsBadge dot>
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>
```

### Colors

The `color` prop accepts any color alias of the design system, `text-color`
changes the color of the content. By default the badge is red — the color of
indication.

**Example — `CustomColors.vue`:**

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

const colors = CdsBadge.constants.colors;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsBadge v-for="color in colors" :key="color" :color="color" :content="color" inline />
  </div>
</template>
```

### Positioning

By default the badge is positioned absolutely relative to the element from the
slot. The `location` prop picks the corner.

**Example — `Locations.vue`:**

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

<template>
  <div class="flex justify-center gap-4">
    <CdsBadge content="1" location="top end">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="2" location="bottom end">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="3" location="top start">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
    <CdsBadge content="4" location="bottom start">
      <CdsButton variant="soft" color="neutral" icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>
```

The `floating` prop moves the badge 8 pixels away from the content, so it
overlaps the element less. For fine-tuning there are `offset-x` and `offset-y`.

**Example — `FloatingBadge.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsBadge content="3" floating>
      <CdsButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>
  </div>
</template>
```

The `inline` prop puts the badge into the flow next to the content — as in the
menu example above. `location`, `floating` and `offset-*` are ignored then.

### Visibility

The `model-value` prop shows and hides the badge. The change of state is
animated, and the animation is configured through `transition`.

**Example — `ToggleVisibility.vue`:**

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

const visible = ref(false);
const toggle = () => {
  visible.value = !visible.value;
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsBadge content="5" :model-value="visible" :inline="false">
      <CdsButton variant="soft" color="brand" @click="toggle"> {{ visible ? 'Скрыть' : 'Показать' }} бейдж </CdsButton>
    </CdsBadge>
  </div>
</template>
```

### Slots

| Slot      | Description                                  |
| --------- | -------------------------------------------- |
| `default` | The element the badge is attached to         |
| `badge`   | Badge content. Replaces `content` and `icon` |

**Example — `CustomBadgeSlot.vue`:**

```vue
<script setup lang="ts">
import { CdsBadge, CdsFunctionalButton } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsBadge>
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />

      <template #badge> Alert </template>
    </CdsBadge>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The max prop collapses large numbers, so the badge stays compact. | Точное «1528» не помогает принять решение и растягивает бейдж. |
| A badge appears only where an update waits for the user to react. | A badge on every icon turns the signal into noise — nothing gets attention. |
| The badge text is one short word. | A long phrase turns the indicator into a label and breaks the layout. |

## Scenarios

### Notification center

A counter on the notifications icon: `max` keeps the badge compact for any
number of events, and `model-value` hides it once nothing is unread — an empty
"0" does not hang on the icon.

**Example — `NotificationCenter.vue`:**

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

const unread = ref(3);
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsBadge :content="unread" :model-value="unread > 0" :max="99">
      <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
    </CdsBadge>

    <div class="flex flex-wrap justify-center gap-2">
      <CdsButton variant="soft" color="brand" text="Новое уведомление" @click="unread++" />
      <CdsButton variant="soft" color="brand" text="+100" @click="unread += 100" />
      <CdsButton variant="soft" color="neutral" text="Прочитать все" :disabled="unread === 0" @click="unread = 0" />
    </div>
  </div>
</template>
```

### Menu with updates

Counters in menu items hint where to look. A badge with `inline` goes into the
`append` slot of a list item, and once the section is opened `model-value`
removes it. Open "Входящие" — the counter disappears.

**Example — `MenuUpdates.vue`:**

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

const sections = ref([
  { title: 'Входящие', unread: 12 },
  { title: 'Задачи', unread: 3 },
  { title: 'Архив', unread: 0 }
]);
</script>

<template>
  <CdsCard class="m-auto w-[240px]">
    <CdsList>
      <CdsListItem v-for="section in sections" :key="section.title" :value="section.title" @click="section.unread = 0">
        <template #title>{{ section.title }}</template>
        <template #append>
          <CdsBadge :content="section.unread" :model-value="section.unread > 0" inline />
        </template>
      </CdsListItem>
    </CdsList>
  </CdsCard>
</template>
```

### Contacts online

A dot indicator shows the state without words: `color="green"` — the contact is
online, `neutral` — not. `inline` puts the dot into the list row, and the
`label` prop announces the state to screen readers.

**Example — `ContactsOnline.vue`:**

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

const contacts = [
  { name: 'Анна Савельева', online: true },
  { name: 'Пётр Максимов', online: true },
  { name: 'Мария Ким', online: false }
];
</script>

<template>
  <CdsCard class="m-auto w-[240px]">
    <CdsList>
      <CdsListItem v-for="contact in contacts" :key="contact.name" :value="contact.name">
        <template #prepend>
          <CdsBadge
            dot
            inline
            :color="contact.online ? 'green' : 'neutral'"
            :label="contact.online ? 'В сети' : 'Не в сети'"
          />
        </template>
        <template #title>{{ contact.name }}</template>
      </CdsListItem>
    </CdsList>
  </CdsCard>
</template>
```

## API

### CdsBadge

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Component color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `dot` | `boolean \| undefined` | — | no | Shrinks the component and hides its content, rendering it as a dot |
| `dotSize` | `string \| number \| undefined` | — | no | Dot size |
| `floating` | `boolean \| undefined` | — | no | Moves the component further away from the content — an 8 pixel offset. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `icon` | `IconValue \| undefined` | — | no | Icon shown inside the component. Ignored when the `dot` prop is set. |
| `inline` | `boolean \| undefined` | — | no | Renders as an inline block instead of using absolute positioning. The location, floating and offset props are ignored. |
| `label` | `string \| undefined` | `'$cds.badge'` | no | Aria-label for the component. Falls back to the default value when not set. |
| `location` | `Anchor \| null \| undefined` | `'top end'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `max` | `string \| number \| undefined` | — | no | Sets the maximum allowed value when content holds a number. If the number exceeds the maximum, a "+" suffix is added. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | `true` | no | Controls whether the component is shown or hidden. |
| `offsetX` | `string \| number \| undefined` | — | no | Offset along the X axis |
| `offsetY` | `string \| number \| undefined` | — | no | Offset along the Y axis |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'fade-transition'` | no | Transition animation |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `badge` | `any` | Slot for the content placed inside the badge. |
| `default` | `any` | Default slot |

---

# CdsBreadcrumbs

_Category: Navigation · since 4.0.0_

_Tests: API 35/35 · 55 unit · 8 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 8 axe recommendations (v4.0.0-alpha.11)_

Breadcrumbs show the path to the current page in the hierarchy of sections and take you back to any level above in one click. The list is built from the `items` array or by hand — from `CdsBreadcrumbsItem` and `CdsBreadcrumbsDivider`.

**See also:** To switch between sections of the same level, use CdsTabs; for a link styled as text inside a paragraph, use CdsLink; and to move through the steps of a process, use CdsSteps.

## Anatomy

Breadcrumbs are a `ul` list where links to the levels of the hierarchy alternate
with dividers. The last item marks the current page and is not clickable, and an
icon can precede the list.

## Variations

### Items

The `items` array builds the breadcrumbs automatically: a string turns into
text, an object turns into a link with `href` or `to`. The component marks the
last item as the current page itself: it disables the link and paints it in a
neutral color.

**Example — `Default.vue`:**

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

const items = [
  { title: 'Главная', href: '#' },
  { title: 'Каталог', href: '#' },
  { title: 'Оргтехника', href: '#' },
  { title: 'Принтеры' }
];
</script>

<template>
  <div class="flex justify-center">
    <CdsBreadcrumbs :items="items" />
  </div>
</template>
```

### Divider

By default the items are separated by `/`. The `divider` prop replaces the
character, and the `divider` slot replaces the whole markup — with a chevron
icon, for example.

**Example — `Divider.vue`:**

```vue
<script setup lang="ts">
import { CdsBreadcrumbs, CdsIcon } from '@central-design-system/components';

const items = [{ title: 'Главная', href: '#' }, { title: 'Документы', href: '#' }, { title: 'Отчёт за июль' }];
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsBreadcrumbs :items="items" divider="→" />

    <CdsBreadcrumbs :items="items">
      <template #divider>
        <CdsIcon icon="chevron-right" :size="16" />
      </template>
    </CdsBreadcrumbs>
  </div>
</template>
```

### Icon

The `icon` prop renders an icon before the list — a sign of the root section,
for example. The `prepend` slot replaces it with arbitrary content.

**Example — `Icon.vue`:**

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

const items = [{ title: 'Главная', href: '#' }, { title: 'Настройки', href: '#' }, { title: 'Профиль' }];
</script>

<template>
  <div class="flex justify-center">
    <CdsBreadcrumbs :items="items" icon="dashboard" />
  </div>
</template>
```

### Slots

Slots override parts of the list without giving up the automatic assembly from
`items`. The `title`, `divider` and `item` slots receive `item` and `index`, so
the content can be changed for every item separately.

| Slot      | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `prepend` | Content before the list. Replaces the icon from `icon`           |
| `title`   | Item text — a shared template for all items                      |
| `divider` | Divider content. Replaces the character from `divider`           |
| `item`    | The whole item — your own markup instead of `CdsBreadcrumbsItem` |
| `default` | Content after the items from `items`; used for manual assembly   |

**Example — `Slots.vue`:**

```vue
<script setup lang="ts">
import { CdsBreadcrumbs, CdsIcon } from '@central-design-system/components';

const items = [{ title: 'Главная', href: '#' }, { title: 'Проекты', href: '#' }, { title: 'Редизайн сайта' }];
</script>

<template>
  <div class="flex justify-center">
    <CdsBreadcrumbs :items="items">
      <template #title="{ item, index }">
        <CdsIcon v-if="index === 0" icon="dashboard" :size="16" start />
        {{ item.title }}
      </template>
    </CdsBreadcrumbs>
  </div>
</template>
```

### Manual assembly

When the path is not described by a flat array — you need your own handlers or
non-standard items — build the list in the `default` slot from
`CdsBreadcrumbsItem` and `CdsBreadcrumbsDivider`. Mark the current page with
`disabled`, and limit a long title with `max-width` — the text is truncated with
an ellipsis.

**Example — `Manual.vue`:**

```vue
<script setup lang="ts">
import { CdsBreadcrumbs, CdsBreadcrumbsDivider, CdsBreadcrumbsItem } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsBreadcrumbs>
      <CdsBreadcrumbsItem href="#">Главная</CdsBreadcrumbsItem>
      <CdsBreadcrumbsDivider />
      <CdsBreadcrumbsItem href="#" max-width="140">Документы отдела продаж</CdsBreadcrumbsItem>
      <CdsBreadcrumbsDivider />
      <CdsBreadcrumbsItem disabled>Отчёт за июль</CdsBreadcrumbsItem>
    </CdsBreadcrumbs>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The last item is the current page: no link, neutral color. | The current page is styled as a link — clicking it leads nowhere and confuses the reader. |
| Short level names — the path reads at a glance. | Full page titles stretch the path and wrap onto several lines. |
| With a single level of nesting, a link back to the parent is enough. | Breadcrumbs of two items do not help you navigate and just take up space. |

## Scenarios

### Section navigation

Breadcrumbs lead the user through the catalog tree: links in the list open
deeper sections, a click on a crumb returns one level up. In an application with
vue-router, pass `to` to the items instead of handlers — the navigation and the
active state of the link work on their own.

**Example — `Catalog.vue`:**

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

interface Section {
  title: string;
  children?: Section[];
}

const catalog: Section = {
  title: 'Каталог',
  children: [
    {
      title: 'Офисная техника',
      children: [{ title: 'Принтеры' }, { title: 'Мониторы' }]
    },
    {
      title: 'Мебель',
      children: [{ title: 'Столы' }, { title: 'Кресла' }]
    },
    { title: 'Канцтовары' }
  ]
};

const path = ref<Section[]>([catalog]);

const current = computed(() => path.value[path.value.length - 1]);

const open = (section: Section) => path.value.push(section);
const goTo = (index: number) => (path.value = path.value.slice(0, index + 1));
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-3 m-auto">
    <CdsBreadcrumbs>
      <template v-for="(section, index) in path" :key="section.title">
        <CdsBreadcrumbsDivider v-if="index > 0" />
        <CdsBreadcrumbsItem v-if="index < path.length - 1" href="#" @click.prevent="goTo(index)">
          {{ section.title }}
        </CdsBreadcrumbsItem>
        <CdsBreadcrumbsItem v-else disabled>{{ section.title }}</CdsBreadcrumbsItem>
      </template>
    </CdsBreadcrumbs>

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="child in current.children" :key="child.title">
        <CdsLink href="#" :text="child.title" @click.prevent="open(child)" />
      </li>
      <li v-if="!current.children">В разделе «{{ current.title }}» пока пусто — вернитесь по крошкам выше.</li>
    </ul>
  </div>
</template>
```

### Long path

Collapse a deep hierarchy down to the first level, an ellipsis and the last two
steps — the path stays on a single line. A click on the ellipsis expands the
full list.

**Example — `LongPath.vue`:**

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

const path = ['Главная', 'Документы', 'Договоры', '2026', 'Поставщики', 'Договор № 114'];

const expanded = ref(false);

const visible = computed(() => (expanded.value ? path : [path[0], '…', ...path.slice(-2)]));
</script>

<template>
  <div class="flex justify-center">
    <CdsBreadcrumbs>
      <template v-for="(title, index) in visible" :key="title">
        <CdsBreadcrumbsDivider v-if="index > 0" />
        <CdsBreadcrumbsItem v-if="title === '…'" href="#" title="…" @click.prevent="expanded = true" />
        <CdsBreadcrumbsItem v-else-if="index < visible.length - 1" href="#" :title="title" @click.prevent />
        <CdsBreadcrumbsItem v-else disabled :title="title" />
      </template>
    </CdsBreadcrumbs>
  </div>
</template>
```

## API

### CdsBreadcrumbs

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeClass` | `string \| undefined` | — | no | Class applied to the component when it is in the active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `divider` | `string \| undefined` | `'/'` | no | Divider between the child components |
| `icon` | `IconValue \| undefined` | — | no | Icon displayed next to the component |
| `items` | `readonly BreadcrumbItem[] \| undefined` | `[]` | no | Array of strings or objects used to build the child components automatically |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'ul'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default content |
| `divider` | `{ item: BreadcrumbItem; index: number; }` | Divider content between the items; can be overridden for each item |
| `item` | `{ item: InternalBreadcrumbItem; index: number; }` | Item content; can be overridden for each item |
| `prepend` | `any` | Content at the start |
| `title` | `{ item: InternalBreadcrumbItem; index: number; }` | Content inside each item; can be overridden for each item |

### CdsBreadcrumbsDivider

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `divider` | `string \| number \| undefined` | — | no | Divider |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default content |

### CdsBreadcrumbsItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the component; usually marks the current page in the navigation |
| `activeClass` | `string \| undefined` | — | no | Class applied to the component when it is in the active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'li'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `title` | `string \| undefined` | — | no | Item title displayed in the component |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default content |

---

# CdsButton

_Category: Content · since 4.0.0_

_Tests: API 37/38 · 59 unit · 2 e2e · 2 known bugs · lines 98% (v4.0.0-alpha.13) · a11y: 11 axe recommendations (v4.0.0-alpha.11)_

A button is the primary way to trigger an action: submit a form, open a modal, confirm a choice. Its variant (`variant`) and color (`color`) signal the role it plays: a filled `solid` button is the main action on the screen, `soft`, `outline` and `ghost` are the supporting ones.

**See also:** For a link styled as text inside a paragraph, use CdsLink; to pick one option out of several, use CdsButtonToggle.

## Anatomy

A button consists of a container and three content areas. Icons come from the
`prepend-icon` / `append-icon` props or from the slots of the same name; while
`loading` is on, the content is replaced by the indicator from the `loader` slot.

## Variations

### Variant

The `variant` prop sets how the button is drawn. The default is `solid`.

| Variant   | Looks like                        | When                                     |
| --------- | --------------------------------- | ---------------------------------------- |
| `solid`   | filled with the color             | the main action on the screen            |
| `soft`    | a translucent tint of the color   | a supporting action                      |
| `outline` | a border, transparent background  | a supporting action on a busy background |
| `surface` | a border on a surface backdrop    | an action over an image or a chart       |
| `ghost`   | neither background nor border     | an action inside a panel, table or toast |

**Example — `Variants.vue`:**

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

const { variants } = CdsButton.constants;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsButton v-for="variant of variants" :key="variant" :text="variant" :variant="variant" />
  </div>
</template>
```

### Color

The `color` prop sets the color in any variant. The default is `brand`. It
accepts:

- a role: `brand` — the brand color, `accent` — the accent button (the same as
  `brand` in the design system, a theme can repaint it), `neutral` — a neutral
  button, `danger` — an irreversible action, `inverse` — for dark backgrounds;
- a palette alias: `red`, `green`, `cyan`, … `black`, `white`;
- a theme token name: `status-success-surface`, `other-lime-fill`;
- any CSS color: `#7c3aed`, `oklch(…)`.

The state film builds hover, press and disabled for any color, so no per-color
tokens are needed.

**Example — `Colors.vue`:**

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

const roles = ['brand', 'accent', 'neutral', 'danger'] as const;
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <div class="flex flex-wrap justify-center gap-4">
      <CdsButton v-for="color of roles" :key="color" :text="color" :color="color" />
    </div>

    <div class="flex flex-wrap justify-center gap-4">
      <CdsButton v-for="color of roles" :key="color" :text="color" variant="soft" :color="color" />
    </div>

    <div class="rounded-200 bg-surface-inverse flex flex-wrap justify-center gap-4 p-4">
      <CdsButton text="inverse" color="inverse" />
      <CdsButton text="inverse" variant="ghost" color="inverse" />
    </div>

    <div class="flex flex-wrap justify-center gap-4">
      <CdsButton text="green" color="green" />
      <CdsButton text="status-success-surface" color="status-success-surface" />
      <CdsButton text="#7c3aed" variant="outline" color="#7c3aed" />
    </div>
  </div>
</template>
```

#### The deprecated `appearance` prop

`appearance` still works and resolves into a `variant` + `color` pair, logging
`[CDS UPGRADE]` to the development console once per value. Explicit `variant`
and `color` take precedence over `appearance`.

| `appearance`  | `variant` | `color`   |
| ------------- | --------- | --------- |
| `primary`     | `solid`   | `brand`   |
| `secondary`   | `soft`    | `brand`   |
| `tertiary`    | `soft`    | `neutral` |
| `inverse`     | `solid`   | `inverse` |
| `transparent` | `ghost`   | `brand`   |

### Sizes

The `size` prop changes the height and the paddings of the button. The default
size is `md`.

**Example — `Sizes.vue`:**

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

const { sizes } = CdsButton.constants;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsButton v-for="size of sizes" :key="size" :text="'Button ' + size" :size="size" />
  </div>
</template>
```

### Icons

The `prepend-icon` and `append-icon` props add an icon before and after the text
from `text`.

**Example — `IconsAndContent.vue`:**

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

const looks = [
  { text: 'solid', variant: 'solid', color: 'brand' },
  { text: 'soft', variant: 'soft', color: 'brand' },
  { text: 'outline', variant: 'outline', color: 'brand' },
  { text: 'neutral', variant: 'soft', color: 'neutral' }
] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsButton
      v-for="look of looks"
      :key="look.text"
      prepend-icon="add"
      append-icon="settings"
      :text="look.text"
      :variant="look.variant"
      :color="look.color"
    />
  </div>
</template>
```

The `icon` prop turns the button into an icon button: the text is hidden and a
square button with a single icon remains.

**Example — `IconOnly.vue`:**

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

const looks = [
  { text: 'solid', variant: 'solid', color: 'brand' },
  { text: 'soft', variant: 'soft', color: 'brand' },
  { text: 'outline', variant: 'outline', color: 'brand' },
  { text: 'neutral', variant: 'soft', color: 'neutral' }
] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsButton
      v-for="look of looks"
      :key="look.text"
      icon="copy"
      :text="look.text"
      :variant="look.variant"
      :color="look.color"
    />
  </div>
</template>
```

### Layout

The `block` prop stretches the button to the full width of its parent container.

**Example — `Block.vue`:**

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

<template>
  <div class="flex flex-col m-auto items-start gap-4 w-[400px]">
    <CdsButton block text="Block button" />
    <CdsButton block prepend-icon="add" append-icon="settings" text="Block button with icons" />
    <CdsButton text="Обычная кнопка" />
  </div>
</template>
```

The `stacked` prop places the icon above the text. Such a button is twice as
tall as a regular one of the same size, and its minimum width equals its height.

**Example — `Stacked.vue`:**

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

const { sizes } = CdsButton.constants;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsButton
      v-for="size of sizes"
      :key="size"
      stacked
      variant="soft"
      color="neutral"
      prepend-icon="settings"
      :text="'Button ' + size"
      :size="size"
    />
  </div>
</template>
```

The `spaced` prop pushes the `prepend` and `append` slots to the edges of the
button. The value decides on which side of the content the free space appears:
`start` moves the content towards `append`, `end` moves it towards `prepend`,
`both` keeps it centered. The effect shows up only when the button is wider than
its content, so `spaced` usually goes together with `block` or an explicit width.

**Example — `Spaced.vue`:**

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

<template>
  <div class="flex flex-col m-auto gap-4 w-[320px]">
    <CdsButton
      block
      variant="soft"
      color="neutral"
      prepend-icon="add"
      append-icon="settings"
      spaced="start"
      text="spaced=start"
    />
    <CdsButton
      block
      variant="soft"
      color="neutral"
      prepend-icon="add"
      append-icon="settings"
      spaced="end"
      text="spaced=end"
    />
    <CdsButton
      block
      variant="soft"
      color="neutral"
      prepend-icon="add"
      append-icon="settings"
      spaced="both"
      text="spaced=both"
    />
    <CdsButton block variant="soft" color="neutral" prepend-icon="add" append-icon="settings" text="без spaced" />
  </div>
</template>
```

### Slots

Slots replace the content coming from props when you need full control over the
markup.

| Slot      | Description                                                    |
| --------- | -------------------------------------------------------------- |
| `prepend` | Content before the text. Replaces the icon from `prepend-icon` |
| `default` | Content inside the button. Replaces the text from `text`       |
| `append`  | Content after the text. Replaces the icon from `append-icon`   |
| `loader`  | Loading indicator. Shown instead of the content when `loading` |

**Example — `Slots.vue`:**

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

const loading = ref(false);

const onClick = async () => {
  loading.value = true;

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

<template>
  <div class="flex justify-center">
    <CdsButton variant="soft" color="neutral" :loading="loading" @click="onClick">
      <template #prepend>
        <CdsIcon icon="settings" color="green" />
      </template>

      <span class="text-purple-500 font-bold">Click me</span>

      <template #append>
        <CdsIcon icon="copy" color="red" />
      </template>

      <template #loader>
        <CdsProgressCircle indeterminate color="yellow-light-500" />
      </template>
    </CdsButton>
  </div>
</template>
```

### Link button

Pass `href` (or `to` with a `RouteLocationRaw` object from vue-router) and the
button renders as an `a` tag with all the link attributes, keeping the look and
the props of a button.

**Example — `Link.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsButton href="https://www.google.com" target="_blank" text="External Link" />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| One main action per screen is solid; everything else stays less prominent. | Several solid buttons compete for attention, and the main action gets lost. |
| The label names the action and its outcome. | По «Да» и «ОК» не понятно, что именно произойдёт. |
| Use an icon button only for widely understood actions: edit, copy, delete. | A rare operation is impossible to guess from an icon alone — give the button a label. |
| Use the danger color for an irreversible action such as deleting or revoking access, next to a neutral cancel. | A red button used just for emphasis teaches people to ignore the warning. |

## Scenarios

### Submitting a form

The filled button triggers the main action of the form. The `loading` prop
shows the request in progress and guards against a double submit, while the
neighboring `soft` button in the `neutral` color gives a way to back out.

**Example — `FormActions.vue`:**

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

const email = ref('');
const loading = ref(false);

const submit = async () => {
  loading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 1500));

  loading.value = false;
};
</script>

<template>
  <form class="flex w-full max-w-md flex-col gap-4" @submit.prevent="submit">
    <CdsTextInput v-model="email" label="Рабочая почта" placeholder="name@company.ru" hint="Пришлём ссылку для входа" />

    <div class="flex gap-3">
      <CdsButton type="submit" text="Отправить приглашение" :loading="loading" />
      <CdsButton variant="soft" color="neutral" text="Отмена" :disabled="loading" />
    </div>
  </form>
</template>
```

### Action bar

Repeating actions on a record — edit, duplicate, delete — fit nicely into a
compact bar of icon buttons. The `icon` prop drops the text and `size="sm"`
saves space. Do not forget `aria-label`: without text it stays the only name of
the action.

**Example — `Toolbar.vue`:**

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

<template>
  <div class="flex w-full max-w-md items-center justify-between gap-4">
    <span>Шаблон отчёта за квартал</span>

    <div class="flex gap-2">
      <CdsButton variant="soft" color="neutral" size="sm" icon="edit" aria-label="Редактировать" />
      <CdsButton variant="soft" color="neutral" size="sm" icon="copy" aria-label="Дублировать" />
      <CdsButton variant="soft" color="neutral" size="sm" icon="delete" aria-label="Удалить" />
    </div>
  </div>
</template>
```

### Step navigation

In wizards and multi-step forms the filled button moves forward and the `soft`
one moves back. Chevron icons in `prepend-icon` and `append-icon`
reinforce the direction, and `disabled` blocks moving past the first and the
last step.

**Example — `StepNavigation.vue`:**

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

const step = ref(2);
const totalSteps = 4;
</script>

<template>
  <div class="flex w-full max-w-md items-center justify-between m-auto gap-4">
    <CdsButton
      variant="soft"
      color="brand"
      prepend-icon="chevron-left"
      text="Назад"
      :disabled="step === 1"
      @click="step--"
    />

    <span>Шаг {{ step }} из {{ totalSteps }}</span>

    <CdsButton append-icon="chevron-right" text="Далее" :disabled="step === totalSteps" @click="step++" />
  </div>
</template>
```

## API

### CdsButton

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Controls the active state of the component |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appearance` _(deprecated)_ | `"inverse" \| "primary" \| "secondary" \| "tertiary" \| "transparent" \| undefined` | — | no | Visual appearance of the component. Deprecated: use `variant` and `color` |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `block` | `boolean \| undefined` | — | no | Stretches the button to the full width of its container |
| `color` | `(string & {}) \| "neutral" \| "brand" \| "accent" \| "danger" \| "inverse" \| undefined` | `'brand'` | no | Component color: a role, a palette alias, a theme token or a CSS color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `icon` | `boolean \| IconValue \| undefined` | — | no | Icon to display; the component renders as an icon-only button |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `spaced` | `"both" \| "start" \| "end" \| undefined` | — | no | Pushes the prepend and append slots apart to the edges of the button. |
| `stacked` | `boolean \| undefined` | — | no | Stacks the icon above the text instead of placing them side by side |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'button'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `value` | `any` | — | no | Value of the component within the group |
| `variant` | `"solid" \| "soft" \| "outline" \| "surface" \| "ghost" \| undefined` | `'solid'` | no | Component variant: `solid`, `soft`, `outline`, `surface`, `ghost` |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `group:selected` | `[value: { value: boolean; }]` | Fires when the button is selected inside a group. `value` is a boolean that tells whether the button is now selected (true) or not (false). |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `any` | Content after the text |
| `default` | `any` | Content inside the button |
| `loader` | `any` | Loading indicator |
| `prepend` | `any` | Content before the text |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `group` | `GroupItemProvide \| null` | Returns the current group context when the button is used inside a group component (for example, CdsButtonGroup). |

---

# CdsButtonGroup

_Category: Content · since 4.0.0 · status: new_

_Tests: API 9/10 · 14 unit · lines 100% (v4.0.0-alpha.13) · a11y: 0 axe recommendations (v4.0.0-alpha.11)_

A button group joins several CdsButton into one block: the buttons sit flush against each other, only the outer corners stay rounded, and shared props are set once on the group. This is how you present sets of related actions — a toolbar over a record or zoom controls.

**See also:** If the user does not trigger an action but picks one of several options, use CdsButtonToggle — it keeps the selected state.

## Variations

The group passes the `variant`, `color`, `base-color` and `size` props down to every
button inside — you do not need to repeat them on each button. A prop set on
the button itself takes precedence over the group value.

### Variant and color

`variant` and `color` set the look of every button in the group — from a filled
`solid` for the main set of actions to `color="inverse"` for dark backgrounds.
The deprecated `appearance` still works and resolves into the same pair as on
CdsButton.

**Example — `Appearances.vue`:**

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

const looks = [
  { variant: 'solid', color: 'brand' },
  { variant: 'soft', color: 'brand' },
  { variant: 'soft', color: 'neutral' }
] as const;
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsButtonGroup
      v-for="look of looks"
      :key="look.variant + look.color"
      :variant="look.variant"
      :color="look.color"
      divided
    >
      <CdsButton text="Копировать" />
      <CdsButton text="Переместить" />
      <CdsButton text="Удалить" />
    </CdsButtonGroup>

    <div class="rounded-200 bg-surface-inverse p-4">
      <CdsButtonGroup variant="solid" color="inverse" divided>
        <CdsButton text="Копировать" />
        <CdsButton text="Переместить" />
        <CdsButton text="Удалить" />
      </CdsButtonGroup>
    </div>
  </div>
</template>
```

### Sizes

`size` changes the height and padding of all buttons at once, so a group in a
filter bar and a group in a table header stay consistent.

**Example — `Sizes.vue`:**

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

const { sizes } = CdsButtonGroup.constants;
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsButtonGroup v-for="size of sizes" :key="size" :size="size" variant="soft" color="brand" divided>
      <CdsButton :text="'Назад ' + size" prepend-icon="arrow-left" />
      <CdsButton :text="'Вперёд ' + size" append-icon="arrow-right" />
    </CdsButtonGroup>
  </div>
</template>
```

### Color

`color` paints the button background with a palette alias. Use status colors
when the whole group leads to one outcome — accept or reject.

**Example — `Colors.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsButtonGroup color="status-success-fill" divided>
      <CdsButton text="Принять" prepend-icon="check" />
      <CdsButton text="Принять все" />
    </CdsButtonGroup>

    <CdsButtonGroup color="status-danger-fill" divided>
      <CdsButton text="Отклонить" prepend-icon="remove" />
      <CdsButton text="Отклонить все" />
    </CdsButtonGroup>
  </div>
</template>
```

### Dividers and direction

Without `divided` the buttons sit flush against each other; with it a line
appears between them, so neighboring actions do not blend together.
`direction="vertical"` turns the group into a column — for zoom controls on a
map, for example.

**Example — `Variations.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsButtonGroup variant="soft" color="brand">
      <CdsButton text="Скачать" prepend-icon="download" />
      <CdsButton text="Печать" prepend-icon="print" />
    </CdsButtonGroup>

    <CdsButtonGroup variant="soft" color="neutral" divided>
      <CdsButton text="Копировать" prepend-icon="copy" />
      <CdsButton text="Переместить" prepend-icon="paste" />
      <CdsButton text="Удалить" prepend-icon="delete" />
    </CdsButtonGroup>

    <CdsButtonGroup variant="soft" color="brand" direction="vertical" divided>
      <CdsButton icon="add" aria-label="Приблизить" />
      <CdsButton icon="minus" aria-label="Отдалить" />
    </CdsButtonGroup>
  </div>
</template>
```

## API

### CdsButtonGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` _(deprecated)_ | `"inverse" \| "primary" \| "secondary" \| "tertiary" \| "transparent" \| undefined` | — | no | Visual appearance of the component. Deprecated: use `variant` and `color` |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `color` | `(string & {}) \| "neutral" \| "brand" \| "accent" \| "danger" \| "inverse" \| undefined` | `'brand'` | no | Component color: a role, a palette alias, a theme token or a CSS color |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `divided` | `boolean \| undefined` | — | no | Adds dividers between the buttons of the group. |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `variant` | `"solid" \| "soft" \| "outline" \| "surface" \| "ghost" \| undefined` | `'solid'` | no | Component variant: `solid`, `soft`, `outline`, `surface`, `ghost` |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Buttons of the group. |

---

# CdsButtonToggle

_Category: Content · since 4.0.0 · status: new_

_Tests: API 19/24 · 24 unit · lines 100% (v4.0.0-alpha.13) · a11y: 2 axe recommendations (v4.0.0-alpha.11)_

A toggle group turns CdsButton into a switch: the pressed button stays selected, and the choice is available through `v-model`. Use it for modes and filters that are visible right away — the layout of a list, the period of a report, formatting options.

**See also:** If the buttons trigger actions instead of storing a choice, take CdsButtonGroup. To pick from a long list use CdsSelect, and inside forms — CdsRadioGroup.

## Variations

### Selection

By default a single button is selected, and clicking it again clears the
choice. `v-model` receives the `value` of the button, or its index when no
value is set.

**Example — `Default.vue`:**

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

const model = ref();
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral">
      <CdsButton text="Один" />
      <CdsButton text="Два" />
      <CdsButton text="Три" />
    </CdsButtonToggle>
    <span class="text-content-secondary">Выбрано: {{ model ?? '—' }}</span>
  </div>
</template>
```

### Multiple selection

The `multiple` prop allows selecting several buttons — `v-model` becomes an
array of values.

**Example — `Multiple.vue`:**

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

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" multiple>
      <CdsButton text="Жирный" />
      <CdsButton text="Курсив" />
      <CdsButton text="Подчёркнутый" />
    </CdsButtonToggle>
    <span class="text-content-secondary">Выбрано: {{ model.length ? model : '—' }}</span>
  </div>
</template>
```

The `max` prop limits the number of selected buttons: once the limit is
reached, clicks on the remaining buttons add nothing to the selection.

**Example — `Max.vue`:**

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

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" multiple :max="2">
      <CdsButton text="Утро" />
      <CdsButton text="День" />
      <CdsButton text="Вечер" />
      <CdsButton text="Ночь" />
    </CdsButtonToggle>
    <span class="text-content-secondary">Выбрано: {{ model.length }} из 2</span>
  </div>
</template>
```

### Mandatory selection

The `mandatory` prop keeps the last choice from being cleared — the group
always stays in some state. With the `'force'` value the first available button
is selected automatically, even when `v-model` is empty.

**Example — `Mandatory.vue`:**

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

const model = ref('left');
</script>

<template>
  <div class="flex justify-center">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" mandatory>
      <CdsButton text="Слева" value="left" />
      <CdsButton text="По центру" value="center" />
      <CdsButton text="Справа" value="right" />
    </CdsButtonToggle>
  </div>
</template>
```

### Color of the active button

The `active-color` prop repaints the selected buttons — the choice stands out
on panels crowded with controls.

**Example — `ActiveColor.vue`:**

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

const model = ref(0);
</script>

<template>
  <div class="flex justify-center">
    <CdsButtonToggle v-model="model" variant="soft" color="neutral" active-color="green">
      <CdsButton text="День" />
      <CdsButton text="Неделя" />
      <CdsButton text="Месяц" />
    </CdsButtonToggle>
  </div>
</template>
```

### Group props

CdsButtonToggle is built on CdsButtonGroup and
accepts all of its props: `variant` and `size` apply to every button at once,
and the default variant is `soft`. `active-color` or `color` set the color of
the selected button (`brand` by default), `base-color` the unselected ones
(`neutral` by default); `divided` adds dividers, and `direction="vertical"` turns the
group into a column.

**Example — `Divided.vue`:**

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

const horizontal = ref();
const vertical = ref();
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsButtonToggle v-model="horizontal" variant="soft" color="neutral" divided>
      <CdsButton text="Один" />
      <CdsButton text="Два" />
      <CdsButton text="Три" />
    </CdsButtonToggle>

    <CdsButtonToggle v-model="vertical" variant="soft" color="neutral" direction="vertical" divided>
      <CdsButton text="Один" />
      <CdsButton text="Два" />
      <CdsButton text="Три" />
    </CdsButtonToggle>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A toggle group keeps the choice: the mode or the filter stays pressed. | Actions run once and do not stay selected — those are plain buttons or a CdsButtonGroup. |
| The screen is always in some mode — mandatory keeps the last choice from being cleared. | Without mandatory the choice can be cleared, and the mode of the screen becomes unclear. |
| Labels are short and alike — the options read as one row of equals. | Long mismatched labels and a mix of text with icons break the row. |

## Scenarios

### View mode

The classic toggle group — switching between a list and a grid. Icon buttons
with `aria-label` save space, `mandatory` guarantees that the list is always
shown in one of the modes, and the neutral default look with `size="sm"`
keeps the control from stealing attention from the content.

**Example — `ViewMode.vue`:**

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

const view = ref('list');

const items = ['Ноутбук', 'Монитор', 'Клавиатура', 'Мышь'];
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col gap-2">
    <div class="flex items-center justify-between">
      <span class="text-content-primary">Товары</span>

      <CdsButtonToggle v-model="view" mandatory variant="soft" color="neutral" size="sm">
        <CdsButton icon="list-bullet" value="list" aria-label="Список" />
        <CdsButton icon="view-rows" value="cards" aria-label="Плитка" />
      </CdsButtonToggle>
    </div>

    <ul v-if="view === 'list'" class="flex flex-col gap-1">
      <li v-for="item in items" :key="item" class="rounded-200 bg-surface-secondary px-2 py-1">{{ item }}</li>
    </ul>

    <div v-else class="grid grid-cols-2 gap-1">
      <div v-for="item in items" :key="item" class="rounded-200 bg-surface-secondary p-4 text-center">
        {{ item }}
      </div>
    </div>
  </div>
</template>
```

### Formatting toolbar

Text styles are independent of each other, so the group works with `multiple`:
each button turns its own style on and off, and `v-model` collects the selected
values into an array.

**Example — `TextFormatting.vue`:**

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

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="format" variant="soft" color="neutral" multiple divided>
      <CdsButton icon="bold" value="bold" aria-label="Жирный" />
      <CdsButton icon="italic" value="italic" aria-label="Курсив" />
      <CdsButton icon="underline" value="underline" aria-label="Подчёркнутый" />
    </CdsButtonToggle>

    <p
      :class="{
        'font-bold': format.includes('bold'),
        italic: format.includes('italic'),
        underline: format.includes('underline')
      }"
    >
      Съешьте ещё этих мягких французских булок
    </p>
  </div>
</template>
```

### Period filter

Give the buttons a `value` — and `v-model` returns a meaningful value to query
the data with. `mandatory` keeps the user from ending up without a period: the
numbers always belong to the selected range.

**Example — `PeriodFilter.vue`:**

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

const period = ref<'day' | 'week' | 'month'>('week');

const stats = {
  day: { orders: 12, sum: '48 000 ₽' },
  week: { orders: 84, sum: '316 000 ₽' },
  month: { orders: 367, sum: '1,4 млн ₽' }
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsButtonToggle v-model="period" variant="soft" color="neutral" mandatory>
      <CdsButton text="День" value="day" />
      <CdsButton text="Неделя" value="week" />
      <CdsButton text="Месяц" value="month" />
    </CdsButtonToggle>

    <div class="flex w-[240px] flex-col items-center rounded-200 bg-surface-secondary p-4">
      <span class="text-900">{{ stats[period].orders }}</span>
      <span class="text-content-secondary">заказов на {{ stats[period].sum }}</span>
    </div>
  </div>
</template>
```

## API

### CdsButtonToggle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appearance` _(deprecated)_ | `"inverse" \| "primary" \| "secondary" \| "tertiary" \| "transparent" \| undefined` | — | no | Visual appearance of the component. Deprecated: use `variant` and `color` |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `color` | `(string & {}) \| "neutral" \| "brand" \| "accent" \| "danger" \| "inverse" \| undefined` | `'brand'` | no | Component color: a role, a palette alias, a theme token or a CSS color |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `divided` | `boolean \| undefined` | — | no | Adds dividers between the buttons of the group. |
| `mandatory` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `variant` | `"solid" \| "soft" \| "outline" \| "surface" \| "ghost" \| undefined` | `'soft'` | no | Buttons variant: `solid`, `soft`, `outline`, `surface`, `ghost` |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: unknown]` | Fires when the selected value changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `CdsButtonToggleSlotProps` | Buttons of the toggle group. The slot props expose the state of the group (selection, navigation). |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isSelected` | `(id: string) => boolean` | Checks whether the button with this id is selected |
| `next` | `() => void` | Selects the next button |
| `prev` | `() => void` | Selects the previous button |
| `select` | `(id: string, value: boolean) => void` | Selects a button by its id |
| `selected` | `readonly string[]` | Ids of the selected buttons |

---

# CdsCard

_Category: Content · since 4.0.0_

_Tests: API 98/98 · 139 unit · 8 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 7 axe recommendations (v4.0.0-alpha.11)_

A card gathers related content — a title, text, an image, actions — into one bordered block. Use it when an object (a product, a plan, a document) should read as a whole: a card can act as a link and as a selectable item in a group.

**See also:** For uniform lists of rows use CdsList, for collapsible sections use CdsExpandablePanel, and when you only need a surface without any structure, use CdsSurface.

## Anatomy

A card is assembled from ready-made blocks. The first diagram shows the frame:
header, divider, text and the actions bar. The second one shows how the
`CdsCardItem` header works: the `prepend` and `append` areas at the edges, the
title and the subtitle in the middle. Every block is available as a prop, as a
slot and as a separate component.

## Variations

### Content

There are three ways to fill a card: the `title`, `subtitle` and `text` props
for typical cases; the slots of the same name when you need your own markup
instead of a string; the `CdsCardItem`, `CdsCardTitle`, `CdsCardSubtitle` and
`CdsCardText` components when you need full control over the structure. The
`divider` prop adds a divider between the header and the text.

**Example — `Default.vue`:**

```vue
<script setup lang="ts">
import {
  CdsCard,
  CdsCardDivider,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardText,
  CdsCardTitle,
  CdsIcon
} from '@central-design-system/components';
</script>

<template>
  <div class="cds-row">
    <div class="cds-col">
      <CdsCard
        title="Заголовок карточки"
        subtitle="Подзаголовок карточки"
        text="Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!"
        append-icon="add"
        divider
      />
      <div class="flex justify-center my-2">Использование Props</div>
    </div>

    <div class="cds-col">
      <CdsCard divider>
        <template #title>Заголовок карточки</template>
        <template #subtitle>Подзаголовок карточки</template>
        <template #text>
          Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
          voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde
          voluptatem!
        </template>
        <template #append>
          <CdsIcon icon="add" />
        </template>
      </CdsCard>
      <div class="flex justify-center my-2">Использование Slots</div>
    </div>

    <div class="cds-col">
      <CdsCard>
        <CdsCardItem>
          <CdsCardTitle>Заголовок карточки</CdsCardTitle>
          <CdsCardSubtitle>Подзаголовок карточки</CdsCardSubtitle>
          <template #append>
            <CdsIcon icon="add" />
          </template>
        </CdsCardItem>

        <CdsCardDivider />

        <CdsCardText>
          Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
          voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde
          voluptatem!
        </CdsCardText>
      </CdsCard>
      <div class="flex justify-center my-2">Использование Компонентов</div>
    </div>
  </div>
</template>
```

| Slot                          | Description                                                         |
| :---------------------------- | :------------------------------------------------------------------ |
| `title` / `subtitle` / `text` | Replace the props of the same name                                  |
| `prepend` / `append`          | Content at the edges of the header; replace `*-icon` and `*-avatar` |
| `item`                        | Extra header content below the title                                |
| `default`                     | Arbitrary card content                                              |
| `image`                       | Background image; replaces `image`                                  |
| `actions`                     | Actions bar — rendered inside `CdsCardActions`                      |
| `loader`                      | Your own loading indicator while `loading` is on                    |

### Header

The `prepend-icon` and `append-icon` props put an icon at the edges of the
header, `prepend-avatar` and `append-avatar` put an avatar by image URL. By
default the prepend and append areas are pinned to the top of the header;
`item-align="center"` centers them against the title and the subtitle (on
`CdsCardItem` this prop is called `align`).

**Example — `HeaderMedia.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsCard
      width="320"
      prepend-avatar="/images/temp/thumbnail.jpg"
      title="Анна Смирнова"
      subtitle="Менеджер проекта"
      append-icon="more-vertical"
      item-align="center"
    />

    <CdsCard
      width="320"
      prepend-icon="file"
      title="Договор поставки"
      subtitle="Обновлён вчера"
      append-icon="download"
      item-align="center"
    />
  </div>
</template>
```

### Appearance

A clickable card — one with a link, a click handler, inside a group or with the
`link` prop — highlights its border on hover by itself, you do not need to turn
anything on. `borderless` removes the border — for cards on a surface or inside
other containers.

**Example — `Appearance.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsCard width="240" title="Обычная" text="Рамка по умолчанию отделяет карточку от фона." />
    <CdsCard width="240" link title="Кликабельная" text="Наведите курсор — рамка подсветится." />
    <CdsCard width="240" borderless title="Borderless" text="Без рамки — для карточек на подложке." />
  </div>
</template>
```

### Link

Pass `href` (or `to` with a vue-router route) and the card is rendered as an `a`
tag and becomes clickable as a whole, keeping its appearance.

**Example — `Link.vue`:**

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

<template>
  <CdsCard
    class="m-auto"
    title="CDS Sandbox"
    subtitle="Перейти на песочницу CDS"
    href="https://magersoft.github.io/cds-sandbox"
    target="_blank"
    append-icon="external-link"
    width="300"
  />
</template>
```

### Images

An image at the top is a CdsImage component placed
first inside the card. You can overlay content on top of it by putting the
header into the image slot.

**Example — `Image.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardDivider,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardText,
  CdsCardTitle,
  CdsImage
} from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap justify-center gap-6">
    <CdsCard width="400">
      <CdsImage src="/images/temp/girl.webp" cover class="items-end" />

      <CdsCardItem>
        <CdsCardTitle>Заголовок карточки</CdsCardTitle>
        <CdsCardSubtitle>Подзаголовок карточки</CdsCardSubtitle>
      </CdsCardItem>

      <CdsCardDivider />

      <CdsCardText>
        Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus!
        Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!
      </CdsCardText>

      <CdsCardActions class="justify-end">
        <CdsButton>Действие</CdsButton>
      </CdsCardActions>
    </CdsCard>

    <CdsCard width="400">
      <CdsImage src="/images/temp/dark-city.webp" cover class="items-end">
        <CdsCardItem>
          <CdsCardTitle class="text-content-on-dark">Заголовок карточки</CdsCardTitle>
          <CdsCardSubtitle class="text-content-on-dark opacity-80">Подзаголовок карточки</CdsCardSubtitle>
        </CdsCardItem>
      </CdsImage>

      <CdsCardText>
        Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus!
        Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!
      </CdsCardText>

      <CdsCardActions class="justify-end">
        <CdsButton>Действие</CdsButton>
      </CdsCardActions>
    </CdsCard>
  </div>
</template>
```

The `image` prop stretches the image as the background of the whole card. Take
care of the contrast: set the text color through `color` and pick a dark image
or a gradient.

**Example — `BackgroundImage.vue`:**

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

<template>
  <CdsCard
    class="m-auto"
    title="Заголовок"
    subtitle="Подзаголовок карточки"
    color="content-on-dark"
    text="Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum unde voluptatem!"
    image="/images/temp/dark-city.webp"
    width="400"
  >
    <CdsCardActions class="justify-end">
      <CdsButton variant="solid" color="inverse">Действие</CdsButton>
    </CdsCardActions>
  </CdsCard>
</template>
```

### Group with selection

Wrap the cards in `CdsCardGroup` and give each of them a `value` — the group
turns into a selection control with `v-model`, and the selected card gets a
highlighted border. `required` forbids clearing the selection.

**Example — `Group.vue`:**

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

const selected = ref(1);
const items = [1, 2, 3];
</script>

<template>
  <CdsCardGroup v-model="selected" required class="flex-wrap justify-center gap-4">
    <CdsCard
      v-for="item in items"
      :key="item"
      title="Заголовок карточки"
      subtitle="Подзаголовок карточки"
      text="Используется в качестве элемента, где вся область карточки — это интерактивное состояние."
      :append-icon="selected === item ? 'success-fill' : undefined"
      :value="item"
      width="250"
    />
  </CdsCardGroup>
</template>
```

The `multiple` prop enables multiple selection — `v-model` then holds an array
of values.

**Example — `Multiselectable.vue`:**

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

const selected = ref([2]);
const items = [1, 2, 3];
</script>

<template>
  <CdsCardGroup v-model="selected" multiple class="flex-wrap justify-center gap-4">
    <CdsCard
      v-for="item in items"
      :key="item"
      title="Заголовок карточки"
      subtitle="Подзаголовок карточки"
      text="Используется в качестве элемента, где вся область карточки — это интерактивное состояние."
      :append-icon="selected.includes(item) ? 'success-fill' : undefined"
      :value="item"
      width="250"
    />
  </CdsCardGroup>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A clickable card means one action: its whole area leads to the same result. | Buttons inside a clickable card compete with the click on the card itself. |
| The actions bar holds one main action as primary; the rest are less prominent. | Several primary buttons in one card compete for attention. |
| The subtitle adds a new fact to the title — a place, a date, a price. | A subtitle that repeats the title in other words tells the reader nothing. |

## Scenarios

### Choosing a plan

A group of cards replaces radio buttons when every option needs room for a price
and a description. The `check-fill` icon in `append-icon` repeats the selection
in the header, and the button below stays disabled until an option is picked.

**Example — `TariffPlans.vue`:**

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

const selected = ref<string>();

const plans = [
  { id: 'start', title: 'Старт', price: 'Бесплатно', description: '5 проектов и базовая аналитика.' },
  { id: 'team', title: 'Команда', price: '990 ₽ / мес', description: 'Совместная работа и роли доступа.' },
  {
    id: 'business',
    title: 'Бизнес',
    price: '2 900 ₽ / мес',
    description: 'Без ограничений и с приоритетной поддержкой.'
  }
];
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsCardGroup v-model="selected" class="flex-wrap justify-center gap-4">
      <CdsCard
        v-for="plan in plans"
        :key="plan.id"
        :value="plan.id"
        :title="plan.title"
        :subtitle="plan.price"
        :text="plan.description"
        :append-icon="selected === plan.id ? 'success-fill' : undefined"
        width="240"
      />
    </CdsCardGroup>

    <CdsButton :disabled="!selected" text="Продолжить" />
  </div>
</template>
```

### Product cards

A storefront is assembled from ready-made blocks:
CdsImage with the photo, a rating made of icons in
`CdsCardText`, CdsTag tags with the specs and a pair of
actions in `CdsCardActions` — the main "add to cart" button and a secondary icon
button for favorites that toggles the bookmark and tints it with a utility
class. The `loading` and `disabled` props show the loading bar and protect the
card from repeated clicks while the request runs — press «В корзину».

**Example — `ProductCards.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardDivider,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardText,
  CdsCardTitle,
  CdsIcon,
  CdsImage,
  CdsTag
} from '@central-design-system/components';
import { ref } from 'vue';

const loadingId = ref<string | null>(null);

const products = [
  {
    id: 'headphones',
    title: 'Наушники Aura ANC',
    category: 'Аудио',
    image: 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?auto=format&fit=crop&w=600&q=80',
    rating: 4.8,
    stars: 5,
    reviews: 214,
    price: '12 990 ₽',
    description: 'Беспроводные наушники с активным шумоподавлением и зарядом на 30 часов.',
    tags: [
      {
        name: 'Хит',
        color: 'green'
      },
      {
        name: 'Доставка завтра',
        color: 'purple'
      }
    ]
  },
  {
    id: 'watch',
    title: 'Часы Meridian 40',
    category: 'Аксессуары',
    image: 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?auto=format&fit=crop&w=600&q=80',
    rating: 4.6,
    stars: 5,
    reviews: 98,
    price: '24 490 ₽',
    description: 'Классический корпус 40 мм, сапфировое стекло и ремешок из натуральной кожи.',
    tags: [
      {
        name: 'Новинка',
        color: 'cyan'
      }
    ]
  },
  {
    id: 'sneakers',
    title: 'Кроссовки Vertex Run',
    category: 'Обувь',
    image: 'https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=600&q=80',
    rating: 4.9,
    stars: 5,
    reviews: 531,
    price: '8 790 ₽',
    description: 'Лёгкая беговая пара с амортизирующей подошвой для ежедневных тренировок.',
    tags: [
      {
        name: '−20%',
        color: 'green'
      },
      {
        name: 'Остался 42 размер',
        color: 'red'
      }
    ]
  }
];

const addToCart = (id: string) => {
  loadingId.value = id;

  setTimeout(() => (loadingId.value = null), 2000);
};

const favorites = ref<string[]>([]);

const toggleFavorite = (id: string) => {
  favorites.value = favorites.value.includes(id)
    ? favorites.value.filter((item) => item !== id)
    : [...favorites.value, id];
};
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsCard
      v-for="product in products"
      :key="product.id"
      width="280"
      :loading="loadingId === product.id"
      :disabled="loadingId === product.id"
    >
      <CdsImage :src="product.image" height="200" cover />

      <CdsCardItem>
        <CdsCardTitle>{{ product.title }}</CdsCardTitle>
        <CdsCardSubtitle>{{ product.category }}</CdsCardSubtitle>
      </CdsCardItem>

      <CdsCardText>
        <div class="flex items-center gap-1">
          <CdsIcon
            v-for="star in product.stars"
            :key="star"
            :icon="star <= Math.floor(product.rating) ? 'star-fill' : 'star'"
            size="sm"
            class="text-other-lemon-content"
          />
          <span class="text-sm text-content-secondary">{{ product.rating }} ({{ product.reviews }})</span>
        </div>

        <div class="my-2 text-lg font-bold">{{ product.price }}</div>

        <div>{{ product.description }}</div>
      </CdsCardText>

      <CdsCardDivider />

      <div class="flex flex-wrap gap-1 px-4 pt-2">
        <CdsTag v-for="tag in product.tags" :key="tag.name" :text="tag.name" :color="tag.color" size="sm" />
      </div>

      <CdsCardActions class="gap-2">
        <CdsButton class="flex-1" text="В корзину" @click="addToCart(product.id)" />
        <CdsButton
          variant="soft"
          color="neutral"
          :icon="favorites.includes(product.id) ? 'bookmark-fill' : 'bookmark'"
          :class="{ 'text-other-pink-content': favorites.includes(product.id) }"
          :aria-label="favorites.includes(product.id) ? 'Убрать из избранного' : 'Добавить в избранное'"
          @click="toggleFavorite(product.id)"
        />
      </CdsCardActions>
    </CdsCard>
  </div>
</template>
```

### Expandable details

Hide secondary content behind an expander: a block with `v-if` is wrapped in
`CdsTransitionExpand` for a smooth animation. Anything can trigger the
expansion — a chevron icon or a button in the actions bar.

**Example — `Expanded.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardDivider,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardText,
  CdsCardTitle,
  CdsFunctionalButton,
  CdsTransitionExpand
} from '@central-design-system/components';
import { ref } from 'vue';

const expanded = ref(false);
const showFull = ref(false);
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsCard width="400">
      <CdsCardItem>
        <CdsCardTitle>Расширяемая карточка</CdsCardTitle>
        <CdsCardSubtitle>Просто нажмите на иконку стрелочки</CdsCardSubtitle>
      </CdsCardItem>

      <CdsCardActions class="justify-between">
        <CdsButton variant="soft" color="neutral">Действие</CdsButton>
        <CdsFunctionalButton :icon="expanded ? 'chevron-up' : 'chevron-down'" @click="expanded = !expanded" />
      </CdsCardActions>

      <CdsTransitionExpand>
        <div v-if="expanded">
          <CdsCardDivider />
          <CdsCardText>
            Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
            voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum
            unde voluptatem!
          </CdsCardText>
        </div>
      </CdsTransitionExpand>
    </CdsCard>

    <CdsCard width="400">
      <CdsCardItem>
        <CdsCardTitle>Расширяемая карточка</CdsCardTitle>
        <CdsCardSubtitle>Просто нажмите на кнопку</CdsCardSubtitle>
      </CdsCardItem>

      <CdsTransitionExpand>
        <div v-if="showFull">
          <CdsCardText>
            Lorem ipsum dolor sit amet consectetur adipisicing elit. Commodi, ratione debitis quis est labore
            voluptatibus! Eaque cupiditate minima, at placeat totam, magni doloremque veniam neque porro libero rerum
            unde voluptatem!
          </CdsCardText>
        </div>
      </CdsTransitionExpand>

      <CdsCardDivider />

      <CdsCardActions class="justify-between">
        <CdsButton variant="soft" color="neutral" @click="showFull = !showFull">
          {{ showFull ? 'Скрыть' : 'Показать' }}
        </CdsButton>
      </CdsCardActions>
    </CdsCard>
  </div>
</template>
```

### Gallery

Cards nest into each other: the outer one is an album with a header and a
counter, the inner ones are photo tiles in a mosaic built on a CSS grid with a
fixed row height; `col-span` / `row-span` make individual shots larger. The
`absolute` mode of CdsImage stretches the photo
across the whole tile, `borderless` removes the borders, and a gradient darkens
the last tile under the counter of the remaining photos.

**Example — `Grid.vue`:**

```vue
<script setup lang="ts">
import {
  CdsCard,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardTitle,
  CdsFunctionalButton,
  CdsImage
} from '@central-design-system/components';

const photos = [
  { src: '/images/temp/ny.webp', span: 'col-span-2 row-span-2' },
  { src: '/images/temp/space.webp', span: 'col-span-2' },
  { src: '/images/temp/cat.webp', span: '' },
  { src: '/images/temp/dark-city.webp', span: '' },
  { src: '/images/temp/girl.webp', span: '' },
  { src: '/images/temp/city.webp', span: 'col-span-2' },
  { src: '/images/temp/airbnb.webp', span: '', rest: 18 }
];
</script>

<template>
  <CdsCard width="800" class="m-auto">
    <CdsCardItem align="center">
      <CdsCardTitle>Путешествия</CdsCardTitle>
      <CdsCardSubtitle>25 фото · обновлён вчера</CdsCardSubtitle>
      <template #append>
        <div class="flex gap-1">
          <CdsFunctionalButton icon="upload" aria-label="Загрузить фото" />
          <CdsFunctionalButton icon="more-vertical" aria-label="Действия с альбомом" />
        </div>
      </template>
    </CdsCardItem>

    <div class="grid grid-cols-4 auto-rows-[160px] gap-2 px-4 pb-4">
      <CdsCard
        v-for="photo in photos"
        :key="photo.src"
        link
        borderless
        :class="['flex items-center justify-center', photo.span]"
      >
        <CdsImage
          :src="photo.src"
          absolute
          cover
          :gradient="photo.rest ? 'to bottom, rgba(0,0,0,.55), rgba(0,0,0,.55)' : undefined"
        />
        <span v-if="photo.rest" class="text-2xl font-bold text-content-on-dark">+{{ photo.rest }} фото</span>
      </CdsCard>
    </div>
  </CdsCard>
</template>
```

## API

### CdsCard

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendAvatar` | `string \| undefined` | — | no | Avatar shown after (to the right of) the content in the card header. |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon shown after (to the right of) the content in the card header. |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `borderless` | `boolean \| undefined` | — | no | Removes the border of the card |
| `color` | `string \| undefined` | — | no | Component color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `divider` | `boolean \| undefined` | — | no | Adds a divider between the header and the content |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `image` | `string \| undefined` | — | no | URL of the background image of the card. |
| `itemAlign` | `"start" \| "end" \| "center" \| undefined` | — | no | Alignment of the `prepend` / `append` areas against the header content. Passed to `CdsCardItem` as `align`. |
| `link` | `boolean \| undefined` | — | no | Gives the card the styles and the behavior of a link. |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `location` | `Anchor \| null \| undefined` | — | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
| `prependAvatar` | `string \| undefined` | — | no | Avatar shown before (to the left of) the content in the card header. |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon shown before (to the left of) the content in the card header. |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `subtitle` | `string \| number \| boolean \| undefined` | — | no | Card subtitle. Rendered inside `CdsCardItem` below the title. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| number \| boolean \| undefined` | — | no | Card title. Rendered inside `CdsCardItem` above the subtitle. |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `value` | `any` | — | no | Value of the component within the group |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `any` | Actions bar of the card |
| `append` | `any` | Content after the main content (in place of the append icon or avatar) |
| `default` | `any` | Default content inside the card |
| `image` | `any` | Background image of the card |
| `item` | `any` | Custom rendering of the card item (CdsCardItem) |
| `loader` | `LoaderSlotProps` | Slot for a custom loading indicator, shown while the `loading` prop is true. |
| `prepend` | `any` | Content before the main content (in place of the prepend icon or avatar) |
| `subtitle` | `any` | Subtitle content |
| `text` | `any` | Main text content of the card |
| `title` | `any` | Title content |

### CdsCardActions

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `align` | `"start" \| "end" \| "center" \| undefined` | `'start'` | no | Horizontal alignment of the action buttons |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Card actions, usually buttons |

### CdsCardDivider

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Color of the divider. |
| `contentOffset` | `string \| number \| (string \| number)[] \| undefined` | — | no | Increases the spacing between the content and the lines. When passed as an array, the second value shifts the slot content down (or right when vertical = true). |
| `gradient` | `boolean \| undefined` | — | no | Adds a fade-out effect on both ends. |
| `inset` | `boolean \| undefined` | — | no | Adds an indent to horizontal dividers and reduces the maximum height of vertical ones. |
| `length` | `string \| number \| undefined` | — | no | Length of the divider. Defaults to pixels. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the divider. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `thickness` | `string \| number \| undefined` | — | no | Thickness of the divider. Defaults to pixels. |
| `variant` | `"solid" \| "dotted" \| "dashed" \| "double" \| undefined` | `'solid'` | no | Visual variant of the divider |
| `vertical` | `boolean \| undefined` | — | no | Renders the divider vertically |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the card divider |

### CdsCardGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `mandatory` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `selectedClass` | `string \| undefined` | `'cds-card--selected'` | no | CSS class applied in the selected state |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `GroupProvide` | Cards of the group. The slot props expose the group state (selection, navigation). |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isSelected` | `(id: string) => boolean` | Checks whether a card with the given id is selected |
| `next` | `() => void` | Selects the next card |
| `prev` | `() => void` | Selects the previous card |
| `select` | `(id: string, value: boolean) => void` | Selects a card by its id |
| `selected` | `readonly string[]` | Identifiers of the selected cards |

### CdsCardItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `align` | `"start" \| "end" \| "center" \| undefined` | — | no | Alignment of the `prepend` / `append` areas against the content. |
| `appendAvatar` | `string \| undefined` | — | no | Avatar shown after (to the right of) the content. |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon shown after (to the right of) the content. |
| `prependAvatar` | `string \| undefined` | — | no | Avatar shown before (to the left of) the content. |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon shown before (to the left of) the content. |
| `subtitle` | `string \| number \| boolean \| undefined` | — | no | Subtitle of the card item. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `title` | `string \| number \| boolean \| undefined` | — | no | Title of the card item. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `any` | Content after the main content (in place of the append icon or avatar) |
| `default` | `any` | Default content inside the body of the card item |
| `prepend` | `any` | Content before the main content (in place of the prepend icon or avatar) |
| `subtitle` | `any` | Subtitle content |
| `title` | `any` | Title content |

### CdsCardSubtitle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the subtitle text. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the card subtitle |

### CdsCardText

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the card text. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Text content of the card |

### CdsCardTitle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the card title |

---

# CdsCarousel

_Category: Content · since 4.0.0 · status: new_

_Tests: none yet — behavior is not covered by automated tests_

A carousel shows images or arbitrary content slide by slide: promo banners, photo galleries, onboarding steps. Arrows and delimiter dots give you navigation, autoplay flips the slides on its own, and the progress bar shows the current position.

**See also:** To switch content without delimiters and autoplay, take CdsSlideView — the carousel is built on top of it; for a single image take CdsImage.

## Anatomy

A carousel is made of slides, navigation arrows, delimiter dots and an optional
progress bar. Arrows and dots loop around: the first slide follows the last one.

## Variations

### Images

`CdsCarouselItem` combines a slide and CdsImage —
pass it any image prop: `src`, `alt`, `cover`, `gradient`. The `height` prop
sets the height of the carousel (500 by default).

**Example — `Default.vue`:**

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

const slide = ref(0);

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/ny.webp', alt: 'Улицы Нью-Йорка' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel v-model="slide" height="360" class="m-auto max-w-[640px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
  </CdsCarousel>
</template>
```

### Custom content

A slide does not have to be an image: put any markup into the slot of
`CdsCarouselItem` and it stretches over the whole frame.

**Example — `CustomContent.vue`:**

```vue
<script setup lang="ts">
import { CdsCarousel, CdsCarouselItem } from '@central-design-system/components';

const slides = [
  { text: 'Первый слайд', class: 'bg-brand-primary' },
  { text: 'Второй слайд', class: 'bg-status-progress-fill' },
  { text: 'Третий слайд', class: 'bg-surface-inverse' }
];
</script>

<template>
  <CdsCarousel height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="slide in slides" :key="slide.text">
      <div class="flex h-full items-center justify-center text-500 text-content-on-dark" :class="slide.class">
        {{ slide.text }}
      </div>
    </CdsCarouselItem>
  </CdsCarousel>
</template>
```

### Autoplay

The `cycle` prop flips the slides automatically, `interval` sets the pause in
milliseconds (6000 by default). The timer restarts after a manual switch, so the
reader always has time to finish looking at a slide.

**Example — `Cycle.vue`:**

```vue
<script setup lang="ts">
import { CdsCarousel, CdsCarouselItem } from '@central-design-system/components';

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel cycle :interval="3000" height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
  </CdsCarousel>
</template>
```

### Progress

The `progress` prop adds a position bar at the bottom of the carousel. A string
value sets its color — any of the tokens that
CdsProgressBar accepts.

**Example — `Progress.vue`:**

```vue
<script setup lang="ts">
import { CdsCarousel, CdsCarouselItem } from '@central-design-system/components';

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsCarousel progress hide-delimiters height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">progress</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsCarousel progress="brand-primary" hide-delimiters height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">progress="brand-primary"</span>
    </div>
  </div>
</template>
```

### Delimiters

Props control the navigation dots: `hide-delimiters` removes them completely,
`hide-delimiter-background` removes only the backdrop, `vertical-delimiters`
(`left` / `right`) puts the dots vertically along the edge, and `delimiter-icon`
changes the dot icon.

**Example — `Delimiters.vue`:**

```vue
<script setup lang="ts">
import { CdsCarousel, CdsCarouselItem } from '@central-design-system/components';

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsCarousel hide-delimiter-background height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">hide-delimiter-background</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsCarousel vertical-delimiters="right" hide-delimiter-background height="180" class="w-[280px]">
        <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
      </CdsCarousel>
      <span class="text-100 text-content-secondary">vertical-delimiters="right"</span>
    </div>
  </div>
</template>
```

The `item` slot replaces a dot with your own element: it receives the ready-made
delimiter props (click handler, `aria-label`, active class) and the group item
itself — all that is left is to bind them with `v-bind`.

**Example — `CustomDelimiters.vue`:**

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

const slide = ref(0);

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel v-model="slide" height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />

    <template #item="{ props: itemProps, item }">
      <CdsButton
        v-bind="itemProps"
        size="sm"
        variant="solid"
        :color="slide === item.value ? 'brand' : 'inverse'"
        :text="String(Number(item.value) + 1)"
      />
    </template>
  </CdsCarousel>
</template>
```

### Arrows

The arrow props are inherited from CdsSlideView:
`show-arrows="hover"` shows them on hover only, `:show-arrows="false"` removes
them completely, `prev-icon` / `next-icon` change the icons, and the `prev` /
`next` slots replace the buttons themselves.

**Example — `Arrows.vue`:**

```vue
<script setup lang="ts">
import { CdsCarousel, CdsCarouselItem } from '@central-design-system/components';

const slides = [
  { src: '/images/temp/city.webp', alt: 'Вечерний город' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Звёздное небо' }
];
</script>

<template>
  <CdsCarousel show-arrows="hover" height="220" class="m-auto max-w-[520px]">
    <CdsCarouselItem v-for="item in slides" :key="item.src" :src="item.src" :alt="item.alt" cover />
  </CdsCarousel>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Images with cover fill the whole slide — the carousel looks solid. | Without cover the image leaves empty margins, and the frame height jumps from slide to slide. |
| Up to 5–7 slides: the dots stay readable and you can tell how many are left. | A dozen and a half slides blur into a strip of dots — nobody scrolls through to the important content. |
| Text over an image sits on a gradient — it reads on any frame. | Text without a backdrop gets lost on a busy image. |

## Scenarios

### Promo banners

The classic banner rotation: `cycle` with a 5 second `interval` flips the slides
on its own, `progress` shows when the next one comes. The text and the button
live in the slide slot, and the `gradient` from CdsImage darkens the top of the
frame beneath them — so they stay readable on any image.

**Example — `PromoBanners.vue`:**

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

const banners = [
  {
    src: '/images/temp/city.webp',
    alt: 'Вечерний город',
    title: 'Городские туры выходного дня',
    text: 'Скидка 20% на все маршруты до конца месяца'
  },
  {
    src: '/images/temp/villa.webp',
    alt: 'Вилла с бассейном',
    title: 'Виллы у моря',
    text: 'Раннее бронирование лета — уже открыто'
  },
  {
    src: '/images/temp/desert.webp',
    alt: 'Столовые горы на закате',
    title: 'Экспедиции в пустыню',
    text: 'Небольшие группы, опытные гиды'
  }
];
</script>

<template>
  <CdsCarousel cycle :interval="5000" progress height="280" class="m-auto max-w-[640px]">
    <CdsCarouselItem
      v-for="banner in banners"
      :key="banner.src"
      :src="banner.src"
      :alt="banner.alt"
      gradient="to bottom, rgba(0, 0, 0, 0.7), transparent 60%"
      cover
    >
      <div class="flex w-full items-start justify-between gap-2 p-4">
        <div>
          <p class="text-500 font-bold text-content-on-dark">{{ banner.title }}</p>
          <p class="text-200 text-content-on-dark">{{ banner.text }}</p>
        </div>
        <CdsButton text="Подробнее" size="sm" />
      </div>
    </CdsCarouselItem>
  </CdsCarousel>
</template>
```

### Gallery with thumbnails

The dots are replaced by thumbnails: `hide-delimiters` removes the built-in
delimiters, and a click on a thumbnail changes `v-model`. The counter next to it
reads the same `v-model` — the carousel, the thumbnails and the counter always
stay in sync.

**Example — `ProductGallery.vue`:**

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

const slide = ref(0);

const photos = [
  { src: '/images/temp/villa.webp', alt: 'Вилла с бассейном' },
  { src: '/images/temp/airbnb.webp', alt: 'Гостиная с камином' },
  { src: '/images/temp/ny.webp', alt: 'Вид на город из окна' },
  { src: '/images/temp/wallpaper.webp', alt: 'Озеро рядом с виллой' }
];
</script>

<template>
  <div class="m-auto flex w-[480px] flex-col gap-2">
    <CdsCarousel v-model="slide" hide-delimiters height="280">
      <CdsCarouselItem v-for="photo in photos" :key="photo.src" :src="photo.src" :alt="photo.alt" cover />
    </CdsCarousel>

    <div class="flex items-center justify-between">
      <div class="flex gap-1">
        <button
          v-for="(photo, index) in photos"
          :key="photo.src"
          type="button"
          class="cursor-pointer overflow-hidden rounded-100 border-2 border-solid p-0"
          :class="slide === index ? 'border-brand-primary' : 'border-transparent'"
          :aria-label="photo.alt"
          @click="slide = index"
        >
          <CdsImage :src="photo.src" :alt="''" width="56" height="42" cover />
        </button>
      </div>
      <span class="text-200 text-content-secondary">{{ slide + 1 }} / {{ photos.length }}</span>
    </div>
  </div>
</template>
```

### Vertical feed

A stories feed in the spirit of social networks: `direction="vertical"` flips
the frames top to bottom, `vertical-arrows="left"` and
`vertical-delimiters="right"` pull the arrows and the dots apart to the side
edges and free up the frame. The author card and the counter sit in an absolute
layer above the carousel: `pointer-events-none` lets clicks through to the
arrows, and a transition keyed by `v-model` swaps the card together with the
slide.

**Example — `VerticalFeed.vue`:**

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

const slide = ref(0);

const stories = [
  {
    src: '/images/temp/space.webp',
    alt: 'Звёздное небо',
    author: 'Марина Соколова',
    followers: '31 тыс. подписчиков',
    avatar: 'https://i.pravatar.cc/80?img=47'
  },
  {
    src: '/images/temp/desert.webp',
    alt: 'Столовые горы на закате',
    author: 'Григорий Ковалёв',
    followers: '412 подписчиков',
    avatar: 'https://i.pravatar.cc/80?img=59'
  },
  {
    src: '/images/temp/city.webp',
    alt: 'Вечерний город',
    author: 'Эмма Королёва',
    followers: '521 подписчик',
    avatar: 'https://i.pravatar.cc/80?img=44'
  },
  {
    src: '/images/temp/cat.webp',
    alt: 'Рыжий кот',
    author: 'Антон Макаров',
    followers: '6 тыс. подписчиков',
    avatar: 'https://i.pravatar.cc/80?img=68'
  }
];

const current = computed(() => stories[slide.value]);
</script>

<template>
  <div class="relative m-auto max-w-[560px] overflow-hidden rounded-200">
    <CdsCarousel
      v-model="slide"
      direction="vertical"
      vertical-arrows="left"
      vertical-delimiters="right"
      hide-delimiter-background
      progress
      height="360"
    >
      <CdsCarouselItem v-for="story in stories" :key="story.src" :src="story.src" :alt="story.alt" cover />
    </CdsCarousel>

    <div class="pointer-events-none absolute inset-0 z-10 flex flex-col items-center justify-between py-4">
      <Transition name="jump-transition-right" mode="out-in" appear>
        <div :key="slide" class="flex items-center gap-2 rounded-full bg-surface-primary p-1 pr-4">
          <CdsAvatar :image="current.avatar" />
          <div>
            <p class="text-200 font-bold text-content-primary">{{ current.author }}</p>
            <p class="text-100 text-content-secondary">{{ current.followers }}</p>
          </div>
        </div>
      </Transition>

      <CdsTag :text="`${slide + 1} / ${stories.length}`" size="sm" />
    </div>
  </div>
</template>
```

### Onboarding

Product introduction steps: the arrows are off (`:show-arrows="false"`), the
movement is driven by the "Back" and "Next" buttons through `v-model`. On the
last step "Next" turns into a call to action.

**Example — `Onboarding.vue`:**

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

const slide = ref(0);

const steps = [
  { icon: 'search', title: 'Ищите быстрее', text: 'Единый поиск по проектам, файлам и обсуждениям.' },
  {
    icon: 'notification',
    title: 'Ничего не пропускайте',
    text: 'Уведомления о важных событиях — там, где вам удобно.'
  },
  { icon: 'trophy', title: 'Отмечайте прогресс', text: 'Дашборд покажет, как продвигается работа команды.' }
];

const isLast = computed(() => slide.value === steps.length - 1);
</script>

<template>
  <div class="m-auto flex w-[420px] flex-col gap-2">
    <CdsCarousel v-model="slide" :show-arrows="false" hide-delimiter-background height="220">
      <CdsCarouselItem v-for="step in steps" :key="step.title">
        <div class="flex h-full flex-col items-center justify-center gap-2 bg-surface-secondary px-8 text-center">
          <CdsIcon :icon="step.icon" :size="32" />
          <p class="text-400 font-bold text-content-primary">{{ step.title }}</p>
          <p class="text-200 text-content-secondary">{{ step.text }}</p>
        </div>
      </CdsCarouselItem>
    </CdsCarousel>

    <div class="flex justify-between">
      <CdsButton variant="soft" color="neutral" text="Назад" :disabled="slide === 0" @click="slide -= 1" />
      <CdsButton v-if="!isLast" text="Далее" @click="slide += 1" />
      <CdsButton v-else text="Начать работу" @click="slide = 0" />
    </div>
  </div>
</template>
```

## API

### CdsCarousel

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Color of the active delimiter and of the progress bar |
| `continuous` | `boolean \| undefined` | `true` | no | Loops the navigation: from the last slide you move to the first one and back |
| `crossfade` | `boolean \| undefined` | — | no | Slides change with a smooth crossfade instead of a shift |
| `cycle` | `boolean \| undefined` | — | no | Flips the slides automatically after the given interval |
| `delimiterIcon` | `IconValue \| undefined` | `'dot'` | no | Icon of the delimiter (navigation dot) |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `height` | `string \| number \| undefined` | `500` | no | Height of the carousel |
| `hideDelimiterBackground` | `boolean \| undefined` | — | no | Hides the backdrop under the delimiters |
| `hideDelimiters` | `boolean \| undefined` | — | no | Hides the delimiters (navigation dots) |
| `interval` | `string \| number \| undefined` | `6000` | no | Autoplay interval in milliseconds (when `cycle` is on) |
| `mandatory` | `boolean \| "force" \| undefined` | `'force'` | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `nextIcon` | `IconValue \| undefined` | `'chevron-right'` | no | Icon of the button that moves to the next slide |
| `prevIcon` | `IconValue \| undefined` | `'chevron-left'` | no | Icon of the button that moves to the previous slide |
| `progress` | `string \| boolean \| undefined` | — | no | Shows the progress bar of the current slide. A string sets the color of the bar |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `reverse` | `boolean \| undefined` | — | no | Inverts the direction of the transition animation between slides |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `showArrows` | `string \| boolean \| undefined` | `true` | no | Shows the navigation arrows. `'hover'` — only while the pointer is over the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `touch` | `boolean \| TouchHandlers \| undefined` | — | no | Controls swipe navigation: `false` turns the gestures off, an object sets your own touch handlers |
| `transitionDuration` | `number \| undefined` | — | no | Duration of the transition animation between slides, in milliseconds |
| `verticalArrows` | `boolean \| "left" \| "right" \| undefined` | — | no | Places the navigation arrows vertically: `'left'` or `'right'` — the side, `true` — the default side |
| `verticalDelimiters` | `boolean \| "left" \| "right" \| undefined` | — | no | Vertical placement of the delimiters: `left`, `right` or `true` (left) |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[]` | Fires when the active slide changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ group: GroupProvide; }` | Slides. The slot props carry the group state for controlling the active slide |
| `item` | `{ props: CarouselDelimiterProps; item: { id: string; value: unknown; disabled: boolean \| undefined; }; }` | Custom delimiter (navigation dot) for each slide. |
| `next` | `{ props: ControlProps; }` | Button that moves to the next slide. The slot props are ready to bind to your own button |
| `prev` | `{ props: ControlProps; }` | Button that moves to the previous slide. The slot props are ready to bind to your own button |

### CdsCarouselItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the image with `position: absolute`, filling its parent. |
| `alt` | `string \| undefined` | — | no | Alternative text of the image (the `alt` attribute). |
| `aspectRatio` | `string \| number \| undefined` | — | no | Aspect ratio of the content. For example `1.7778` (16/9) or `'4/3'`. |
| `color` | `string \| undefined` | — | no | Background color of the placeholder shown while loading. |
| `contentClass` | `any` | — | no | CSS class applied to the content wrapper. |
| `cover` | `boolean \| undefined` | — | no | Scales the image so that it covers the whole container (`object-fit: cover`). |
| `crossorigin` | `"" \| "anonymous" \| "use-credentials" \| undefined` | — | no | Value of the `crossorigin` attribute. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `draggable` | `boolean \| "true" \| "false" \| undefined` | — | no | Controls whether the image can be dragged (the `draggable` attribute). |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `gradient` | `string \| undefined` | — | no | CSS gradient laid over the image. For example `'to top, rgba(0,0,0,.4), transparent'`. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `imageClass` | `any` | — | no | CSS class applied to the inner `<img>` element. |
| `inline` | `boolean \| undefined` | — | no | Renders the component as an inline block (`inline-flex`) instead of a block one. |
| `lazySrc` | `string \| undefined` | — | no | Source of the low-quality placeholder image shown until the main one loads. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `options` | `IntersectionObserverInit \| undefined` | `{}` | no | `IntersectionObserver` options for lazy loading. |
| `position` | `string \| undefined` | — | no | Value of `object-position` that places the image inside the container. |
| `referrerpolicy` | `"origin" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url" \| undefined` | — | no | Value of the `referrerpolicy` attribute. |
| `reverseTransition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the reverse direction. A transition component name, or `false` to turn the animation off |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `sizes` | `string \| undefined` | — | no | Value of the `sizes` attribute for responsive images. |
| `src` | `string \| CdsImageSrcObject \| undefined` | `''` | no | Image source. A string or an object with `src`/`srcset`/`lazySrc`/`aspect`. |
| `srcset` | `string \| undefined` | — | no | Set of image sources for different resolutions (the `srcset` attribute). |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the forward direction. A transition component name, or `false` to turn the animation off |
| `value` | `any` | — | no | Value of the component within the group |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content shown over the image. |
| `error` | `any` | Content shown when the image fails to load. |
| `placeholder` | `any` | Content shown while the image is loading. |
| `sources` | `any` | Extra `<source>` elements for the `<picture>` tag. |

---

# CdsCheckbox

_Category: Controls · since 4.0.0_

_Tests: API 65/65 · 63 unit · 5 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 3 axe recommendations (v4.0.0-alpha.11)_

A checkbox turns an independent option on and off: consent to terms, an entry in a filter list, a profile setting. Every checkbox in a group is selected on its own, which makes it right for multiple choice.

**See also:** To pick one option out of several use CdsRadio, for settings that apply immediately — CdsToggle. If you need the control alone, without a label and messages — in a table cell, for example — take CdsCheckboxButton.

## Anatomy

A checkbox is made of the control with the state icon, the label with its
description and the messages block under them. A click on the label toggles the
checkbox exactly like a click on the control.

## Variations

### Label and description

The `label` prop names the option, `description` adds an explanation under the
label. The slots of the same name accept arbitrary markup — a link to the terms,
for example (see the "Consent in a form" scenario).

**Example — `LabelAndDescription.vue`:**

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

const completed = ref(true);
const autoRenew = ref(false);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox v-model="completed" label="Показывать завершённые задачи" hide-details />
    <CdsCheckbox
      v-model="autoRenew"
      label="Автоматическое продление"
      description="Подписка продлится в день окончания текущего периода"
      hide-details
    />
  </div>
</template>
```

### States

`disabled` blocks the checkbox and lowers the contrast, `readonly` forbids
changes but does not change the appearance.

**Example — `States.vue`:**

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox label="Disabled" disabled hide-details />
    <CdsCheckbox :model-value="true" label="Disabled, выбран" disabled hide-details />
    <CdsCheckbox :model-value="true" label="Readonly" readonly hide-details />
  </div>
</template>
```

### Indeterminate state

The `indeterminate` prop shows an intermediate state — usually on a parent
checkbox when only some of the nested entries are selected. This is a visual
flag: it does not change the model value, and the icon is set by
`indeterminate-icon`. A live example is in the "Select all" scenario.

**Example — `Indeterminate.vue`:**

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox indeterminate label="Выбрана часть вложенных пунктов" hide-details />
    <CdsCheckbox :model-value="true" label="Выбран" hide-details />
    <CdsCheckbox label="Не выбран" hide-details />
  </div>
</template>
```

### Sizes

The `size` prop accepts values from `xs` to `xl`, `md` by default. The label and
the description scale together with the control.

**Example — `Sizes.vue`:**

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox :model-value="true" size="xs" label="Размер xs" hide-details />
    <CdsCheckbox :model-value="true" size="sm" label="Размер sm" hide-details />
    <CdsCheckbox :model-value="true" size="md" label="Размер md" hide-details />
    <CdsCheckbox :model-value="true" size="lg" label="Размер lg" hide-details />
    <CdsCheckbox :model-value="true" size="xl" label="Размер xl" hide-details />
  </div>
</template>
```

### Colors

The `color` prop sets the color of a selected checkbox, `base-color` — the color
of an unselected one.

**Example — `Colors.vue`:**

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

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox :model-value="true" color="green" label="Зелёный при выборе (color)" hide-details />
    <CdsCheckbox :model-value="true" color="purple" label="Фиолетовый при выборе (color)" hide-details />
    <CdsCheckbox base-color="purple" label="Фиолетовый до выбора (base-color)" hide-details />
  </div>
</template>
```

### Messages and errors

`messages` shows a supporting text under the checkbox, `error-messages` — a ready
error message (the one coming from the server, for example) together with the
error state. Validation rules through `rules` are in the "Consent in a form"
scenario.

**Example — `Messages.vue`:**

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

const notifications = ref(true);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox v-model="notifications" label="Уведомления о торгах" messages="Можно отключить в любой момент" />
    <CdsCheckbox label="Передача данных партнёрам" error-messages="Для участия в торгах разрешите передачу данных" />
  </div>
</template>
```

### Your own values

By default the model keeps `true` or `false`. The `true-value` and `false-value`
props replace them with your own values — handy when the API expects strings or
codes.

**Example — `TrueFalseValue.vue`:**

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

const subscription = ref('subscribed');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCheckbox
      v-model="subscription"
      true-value="subscribed"
      false-value="unsubscribed"
      label="Получать рассылку"
      hide-details
    />

    <p>Значение модели: {{ subscription }}</p>
  </div>
</template>
```

### A group of checkboxes

To build a group, pass the same array in `v-model` to all the checkboxes and give
them unique `value`s — the selected values are collected into the array.
`hide-details` removes the bottom block and the rows sit right next to each
other; the common heading and description of the group are set by
CdsLabel and
CdsDescription.

**Example — `Group.vue`:**

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

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

<template>
  <div class="w-[350px] m-auto">
    <CdsLabel class="text-sm mb-1">Способы связи</CdsLabel>
    <CdsDescription class="text-xs mb-2">Как связаться с вами по заявке</CdsDescription>
    <div class="flex flex-col gap-2">
      <CdsCheckbox v-model="selected" label="Электронная почта" hide-details value="email" />
      <CdsCheckbox v-model="selected" label="Телефон" hide-details value="phone" />
      <CdsCheckbox v-model="selected" label="Telegram" hide-details value="telegram" />
    </div>

    <p>Выбрано: {{ selected }}</p>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Checkboxes are for independent options: each one can be turned on and off separately. | Checkboxes do not fit mutually exclusive options — use radio buttons. |
| The label is phrased positively: a checked checkbox means the option is on. | A negation in the label makes the user guess what an unchecked box means. |
| A short label names the option, the details go into the description. | In a long label the point of the option drowns in details. |

## Scenarios

### Select all

The parent checkbox controls the group: a computed model checks and unchecks all
the entries at once, and `indeterminate` turns on while only some of them are
selected.

**Example — `SelectAll.vue`:**

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

const options = ['Договоры', 'Счета', 'Акты сверки'];
const selected = ref(['Договоры']);

const allSelected = computed({
  get: () => selected.value.length === options.length,
  set: (value) => {
    selected.value = value ? [...options] : [];
  }
});

const partiallySelected = computed(() => selected.value.length > 0 && selected.value.length < options.length);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsCheckbox v-model="allSelected" :indeterminate="partiallySelected" label="Выбрать всё" hide-details />
    <div class="flex flex-col gap-1 mt-1 pl-4">
      <CdsCheckbox
        v-for="option in options"
        :key="option"
        v-model="selected"
        :value="option"
        :label="option"
        hide-details
      />
    </div>
  </div>
</template>
```

### Consent in a form

A required consent is a rule in `rules` that returns the error text while the
checkbox is unchecked. The `label` slot adds a link to the terms into the label,
and the button starts the check through the `validate()` of the
CdsForm.

**Example — `ConsentForm.vue`:**

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

const consent = ref(false);
const sending = ref(false);
const formRef = ref<InstanceType<typeof CdsForm>>();

const rules = [(value: boolean) => !!value || 'Для регистрации примите условия сервиса'];

async function submit() {
  const form = unref(formRef);
  if (!form) return;

  const { valid } = await form.validate();
  if (!valid) return;

  sending.value = true;
  setTimeout(() => {
    sending.value = false;
  }, 1500);
}
</script>

<template>
  <CdsForm ref="formRef" class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsCheckbox v-model="consent" :rules="rules">
      <template #label> Принимаю <CdsLink href="#">условия сервиса</CdsLink> </template>
    </CdsCheckbox>

    <CdsButton text="Зарегистрироваться" :loading="sending" @click="submit" />
  </CdsForm>
</template>
```

### Filtering a list

A group of checkboxes with an array in `v-model` filters the list on the fly: a
computed keeps the documents of the selected types, and an empty selection means
"show everything".

**Example — `FilterList.vue`:**

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

const documents = [
  { name: 'Договор поставки № 14', type: 'Договор' },
  { name: 'Счёт № 209', type: 'Счёт' },
  { name: 'Акт сверки за июнь', type: 'Акт' },
  { name: 'Договор аренды № 7', type: 'Договор' },
  { name: 'Счёт № 218', type: 'Счёт' }
];

const types = ['Договор', 'Счёт', 'Акт'];
const selectedTypes = ref<string[]>([]);

const filtered = computed(() =>
  selectedTypes.value.length ? documents.filter((document) => selectedTypes.value.includes(document.type)) : documents
);
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <div class="flex flex-wrap gap-3">
      <CdsCheckbox v-for="type in types" :key="type" v-model="selectedTypes" :value="type" :label="type" hide-details />
    </div>

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="document in filtered" :key="document.name">{{ document.name }}</li>
    </ul>
  </div>
</template>
```

## API

### CdsCheckbox

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `falseIcon` | `IconValue \| undefined` | `'checkbox-off'` | no | Icon of the unselected state |
| `falseValue` | `any` | — | no | Value for the false state. |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `indeterminate` | `boolean \| undefined` | — | no | Indeterminate state of the checkbox. |
| `indeterminateIcon` | `IconValue \| undefined` | `'checkbox-indeterminate-fill'` | no | Icon shown in the indeterminate state. |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `trueIcon` | `IconValue \| undefined` | `'checkbox-on-fill'` | no | Icon of the selected state |
| `trueValue` | `any` | — | no | Value for the true state. |
| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `value` | `any` | — | no | Value used when the component is selected inside a group. When it is not set, a unique identifier is used. |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:focused` | `[focused: boolean]` | Fires when the focus state of the component changes. |
| `update:modelValue` | `[value: any]` | Fires when the model of the component changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `default` | `{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }` | Default slot |
| `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 |
| `input` | `SelectionControlSlot` | Slot for the default input element. |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsCheckboxButton

_Category: Controls · since 4.0.0 · status: new_

_Tests: API 33/33 · 17 unit · 5 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

The checkbox control without a label and a messages block — the atom CdsCheckbox is built on. Use it where the caption is not needed or lives outside: in a table cell, a list row, a card.

**See also:** For a standalone option with a label, a description and validation use CdsCheckbox — states, colors and groups work the same way here and are described in detail on its page.

## Basic example

The control is driven through `v-model`, `indeterminate` shows the intermediate
state, `disabled` blocks the choice. There is no visible label, so add an
`aria-label` — that way the control stays clear for screen readers.

**Example — `Basic.vue`:**

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

const checked = ref(true);
</script>

<template>
  <div class="flex justify-center items-center gap-2">
    <CdsCheckboxButton v-model="checked" aria-label="Выбрать элемент" />
    <CdsCheckboxButton indeterminate aria-label="Выбрана часть элементов" />
    <CdsCheckboxButton :model-value="true" disabled aria-label="Выбор недоступен" />
  </div>
</template>
```

## API

### CdsCheckboxButton

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `falseIcon` | `IconValue \| undefined` | `'checkbox-off'` | no | Icon of the unselected state |
| `falseValue` | `any` | — | no | Value for the false state. |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `indeterminate` | `boolean \| undefined` | — | no | Indeterminate state of the checkbox. |
| `indeterminateIcon` | `IconValue \| undefined` | `'checkbox-indeterminate-fill'` | no | Icon shown in the indeterminate state. |
| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `trueIcon` | `IconValue \| undefined` | `'checkbox-on-fill'` | no | Icon of the selected state |
| `trueValue` | `any` | — | no | Value for the true state. |
| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
| `value` | `any` | — | no | Value used when the component is selected inside a group. When it is not set, a unique identifier is used. |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:indeterminate` | `[value: boolean]` | Fired when the indeterminate state of the checkbox changed |
| `update:modelValue` | `[value: boolean]` | Fired when the checkbox was toggled. Passes the new state |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }` | Default slot |
| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
| `input` | `SelectionControlSlot` | Slot for the default input element. |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |

---

# CdsCombobox

_Category: Controls · since 4.0.0_

_Tests: API 130/130 · 118 unit · 8 e2e · 13 known bugs · lines 86.4% (v4.0.0-alpha.13) · a11y: 3 axe recommendations (v4.0.0-alpha.11)_

A combobox is a field with a dropdown list and free input: the value can be picked from the offered ones or typed in — the text itself becomes the value. The field is built on CdsTextInput, and the menu and the list are the same as in CdsSelect, so the label, the messages, validation and the menu behave identically.

**See also:** 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.

## 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.

**Example — `Default.vue`:**

```vue
<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).

**Example — `MultipleChips.vue`:**

```vue
<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.

**Example — `Delimiters.vue`:**

```vue
<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

| ✅ Do | ❌ Don't |
| --- | --- |
| A combobox fits when custom values are allowed: labels, keywords, units of measurement. | A strict reference book does not tolerate free input: typos create duplicates. Take CdsAutocomplete. |
| Tell the user that the field accepts custom values and how to add them. | A “Pick from the list” placeholder hides the main skill of a combobox — free input. |
| Chips with a cross show the collected values and let any of them be removed in one click. | Without chips the values merge into one string, and only the last one can be removed — with the Backspace key. |

## 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.

**Example — `Recipients.vue`:**

```vue
<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.

**Example — `Dictionary.vue`:**

```vue
<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.

**Example — `FormSubmit.vue`:**

```vue
<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

### CdsCombobox

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the field |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `alwaysFilter` | `boolean \| undefined` | — | no | Filters the list even when the search query has not changed since the last selection. |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
| `autocomplete` | `string \| undefined` | `'off'` | no | 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` | — | no | Enables autofocus |
| `autoSelectFirst` | `boolean \| "exact" \| undefined` | — | no | 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` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `chips` | `boolean \| undefined` | — | no | Shows the selected values as removable chips (CdsTag). |
| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
| `clearOnSelect` | `boolean \| undefined` | `true` | no | Clears the search query after an item is selected (relevant for `multiple`). |
| `closableChips` | `boolean \| undefined` | — | no | Adds a remove button to the chips (relevant together with `chips`). |
| `closeText` | `string \| undefined` | `'$cds.close'` | no | Text for screen readers describing the close action of the menu. |
| `color` | `string \| undefined` | — | no | Component color |
| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
| `customFilter` | `FilterFunction \| undefined` | — | no | Your own value filtering function. Receives the value, the search query and the item, returns a match or `-1` |
| `customKeyFilter` | `FilterKeyFunctions \| undefined` | — | no | Separate filtering functions for specific item keys — an object of the form `{ key: function }` |
| `delimiters` | `readonly string[] \| undefined` | — | no | Delimiter characters: typing or pasting a string containing them splits it into several values (for `multiple` only). |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the menu content upfront, without waiting for the first opening. |
| `ellipsis` | `boolean \| undefined` | — | no | In multiple mode keeps the selected values on a single line with an ellipsis |
| `error` | `boolean \| undefined` | — | no | Error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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']` | no | Item keys the search runs over. By default filtering goes by the item title |
| `filterMode` | `FilterMode \| undefined` | `'intersection'` | no | How the results of `customKeyFilter` and of the general filtering are combined: by intersection, by union or by replacement |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hideNoData` | `boolean \| undefined` | `true` | no | Hides the menu and the "no data" placeholder when the item list is empty. |
| `hideSelected` | `boolean \| undefined` | — | no | Hides the already selected items from the menu list. |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `isSelectAll` | `string \| boolean \| undefined` | `false` | no | 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` | no | Object field that holds the child items, or a function that returns them |
| `itemColor` | `string \| undefined` | — | no | Color of the selected items in the menu list. `color` is used by default. |
| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
| `itemType` | `SelectItemKey` | `'type'` | no | Object field that defines the item type (`item`, `divider`, `subheader`), or a function that returns it |
| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `listProps` | `CdsListProps \| undefined` | — | no | Props passed through to the inner CdsList component. |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `menu` | `boolean \| undefined` | — | no | Controls the open state of the dropdown menu (v-model:menu). |
| `menuHeight` | `string \| number \| undefined` | `178` | no | Maximum height of the dropdown menu. |
| `menuIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon indicating that the menu can be expanded. |
| `menuProps` | `CdsMenuProps \| undefined` | — | no | Props passed through to the inner CdsMenu component. |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | v-model modifiers passed by Vue to process the field value |
| `modelValue` | `any` | `null` | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several values. The selected items are shown as chips or as a list. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `noDataText` | `string \| undefined` | `'$cds.noDataText'` | no | Text shown in the menu when the item list is empty. |
| `noFilter` | `boolean \| undefined` | — | no | Turns off the built-in filtering — the list is shown as is, the search is handled outside |
| `openOnClear` | `boolean \| undefined` | — | no | Opens the menu after the value is cleared. |
| `openText` | `string \| undefined` | `'$cds.open'` | no | Text for screen readers describing the open action of the menu. |
| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `returnObject` | `boolean \| undefined` | `true` | no | Return an object in the model value instead of an array |
| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
| `role` | `string \| undefined` | `'combobox'` | no | ARIA role for the native input element |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; } \| null \| undefined` | `{ component: CdsModalTransition }` | no | Transition animation |
| `type` | `string \| undefined` | `'text'` | no | Type of the native input |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |
| `width` | `string \| number \| undefined` | — | no | 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 |

---

# CdsCounter

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 6/6 · 12 unit · lines 100% (v4.0.0-alpha.13) · a11y: 0 axe recommendations (v4.0.0-alpha.11)_

The counter shows how many characters are already typed and how many are allowed: `42 / 100`. When the value exceeds the maximum, the counter turns red — the user sees the problem before submitting the form.

**See also:** The ready-made fields already have the counter built in — turn on the `counter` prop of CdsTextInput or CdsTextArea. A standalone `CdsCounter` is needed when you build your own control.

## Variations

### Value and maximum

The `value` prop sets the current number, `max` sets the limit. Without `max`
the counter shows a single number, with `max` it shows a fraction. As soon as
`value` is greater than `max`, the text turns red.

**Example — `Values.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsCounter active value="42" />
    <CdsCounter active value="42" max="100" />
    <CdsCounter active value="120" max="100" />
  </div>
</template>
```

### Appearance

The counter is visible only with `active` — by default it is hidden. Showing and
hiding are animated, and the animation is set by the `transition` prop.

**Example — `Active.vue`:**

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

const active = ref(true);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCounter :active="active" value="42" max="100" />

    <CdsButton size="sm" variant="soft" color="brand" text="Показать / скрыть" @click="active = !active" />
  </div>
</template>
```

### Slot

The `default` slot replaces the text of the counter and receives `value`, `max`
and the ready `counter` string.

**Example — `Slot.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsCounter v-slot="{ value, max }" active value="42" max="100">
      Осталось {{ Number(max) - Number(value) }} символов
    </CdsCounter>
  </div>
</template>
```

## Scenarios

### Character limit of a field

The `details` slot of an input is the place for a counter next to the messages.
Count the length of the value yourself and pass it into `value`: when the text
outgrows the limit, the counter turns red.

**Example — `CharacterLimit.vue`:**

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

const max = 40;
const title = ref('Поставка канцелярских товаров');
</script>

<template>
  <CdsTextInput v-model="title" label="Название закупки" placeholder="Введите название" class="w-[350px] m-auto">
    <template #details>
      <CdsCounter active :value="title.length" :max="max" />
    </template>
  </CdsTextInput>
</template>
```

## API

### CdsCounter

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `max` | `string \| number \| undefined` | — | no | Maximum value |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; } \| null \| undefined` | `{ component: slide-transition-y }` | no | Transition animation |
| `value` | `string \| number \| undefined` | `0` | no | Value of the counter |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `CdsCounterSlot` | Your own look for the counter. The slot props carry the ready counter string, the current and the maximum number of characters |

---

# CdsDateInput

_Category: Controls · since 4.0.0 · status: new_

_Tests: API 123/123 · 105 unit · 5 e2e · 9 known bugs · lines 95.7% (v4.0.0-alpha.13) · a11y: 16 axe recommendations (v4.0.0-alpha.11)_

A date field: a text field with a calendar icon that opens CdsDatePicker in a dropdown menu on click. The date can be picked with the mouse or typed on the keyboard — the value arrives as a string in the `mask` format (`DD.MM.YYYY` by default).

**See also:** If the calendar is needed right on the page, without a field, take CdsDatePicker. For the time alone — CdsTimePicker, to pick from a ready list — CdsSelect.

## Anatomy

The field is built on CdsTextInput, so the label,
the description, the messages, clearing and validation work the same way. The
calendar icon takes the `prepend-inner` zone and opens the menu — just like a
click on the field itself.

## Variations

### Value and format

The date arrives in `v-model` as a string in the `mask` format. By default the
placeholder shows the mask itself, so there is no need to state the format
separately.

**Example — `Default.vue`:**

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

const date = ref('22.02.2022');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput v-model="date" class="w-[250px]" label="Дата" clearable />

    <span class="text-200 text-content-secondary">v-model: {{ date ?? '—' }}</span>
  </div>
</template>
```

`display-format` changes only what the user sees: the model still keeps a string
in `mask`. It accepts a mask (`D MMMM YYYY`) or a function receiving the native
`Date`. If the date has to be stored differently — in ISO, for example — change
`mask`: it defines both the storage and the parsing of the manual input.

**Example — `DisplayFormat.vue`:**

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

const short = ref('22.02.2022');
const long = ref('22.02.2022');
const iso = ref('2022-02-22');

// Функция получает нативную дату и возвращает готовую строку.
const relative = (date: Date) => new Intl.DateTimeFormat('ru', { dateStyle: 'full' }).format(date).replace(' г.', '');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput v-model="short" class="w-[250px]" label="Маска по умолчанию" />

    <CdsDateInput v-model="long" class="w-[250px]" label="displayFormat строкой" display-format="D MMMM YYYY" />

    <CdsDateInput v-model="iso" class="w-[250px]" label="Другая mask" mask="YYYY-MM-DD" />

    <CdsDateInput v-model="short" class="w-[250px]" label="displayFormat функцией" :display-format="relative" />
  </div>
</template>
```

### Date and time

`with-time` adds a CdsTimePicker under the
calendar and appends the time to the mask: `DD.MM.YYYY` turns into
`DD.MM.YYYY HH:mm` (`with-seconds` — into `DD.MM.YYYY HH:mm:ss`). The value stays
a single string, and the calendar and the clock change their own parts of it. The
time picker settings are available right on the field — `now-btn`, `format12h`,
`allowed-hours`, `allowed-minutes` — or as a whole through `time-picker-props`.

With the time on, the menu does not close on a click on a date: the user is still
picking the hours. If you need an explicit finish, add `:hide-actions="false"` —
the buttons will stand under the time picker.

**Example — `WithTime.vue`:**

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

const dateTime = ref('22.02.2022 12:35');
const withSeconds = ref('22.02.2022 12:35:00');
const workHours = ref('22.02.2022 10:00');

// Приём заявок только в рабочие часы.
const allowedHours = Array.from({ length: 9 }, (_, i) => i + 9);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput v-model="dateTime" class="w-[250px]" label="Дата и время" with-time clearable />

    <CdsDateInput
      v-model="withSeconds"
      class="w-[250px]"
      label="С секундами и кнопкой «Сейчас»"
      with-time
      with-seconds
      now-btn
    />

    <CdsDateInput
      v-model="workHours"
      class="w-[250px]"
      label="Только рабочие часы"
      with-time
      :allowed-hours="allowedHours"
      :hide-actions="false"
    />

    <span class="text-200 text-content-secondary">v-model: {{ dateTime }}</span>
  </div>
</template>
```

### Several dates and a range

`multiple` allows marking several dates — the model becomes an array of strings.
`range` switches the calendar to picking a period: the value arrives as a
`{ from, to }` object, and the menu stays open until both bounds are chosen. A set
of dates and a range have no common time, so `with-time` does not work with them.

**Example — `MultipleAndRange.vue`:**

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

const days = ref(['05.02.2022', '12.02.2022']);
const period = ref({ from: '07.02.2022', to: '18.02.2022' });
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput v-model="days" class="w-[250px]" label="Несколько дат" multiple clearable />

    <CdsDateInput v-model="period" class="w-[250px]" label="Период" range clearable />

    <span class="text-200 text-content-secondary">{{ JSON.stringify({ days, period }) }}</span>
  </div>
</template>
```

### Confirmation buttons

By default the chosen date is applied at once and the menu closes. Pass
`:hide-actions="false"` — and the choice becomes a draft: it gets into the model
only after the "OK" button, while "Cancel" restores the previous value. The
component emits `save` and `cancel`.

**Example — `Actions.vue`:**

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

const date = ref('22.02.2022');
const lastEvent = ref('—');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput
      v-model="date"
      class="w-[250px]"
      label="Дата с подтверждением"
      :hide-actions="false"
      @save="lastEvent = `save: ${$event}`"
      @cancel="lastEvent = 'cancel'"
    />

    <span class="text-200 text-content-secondary">Последнее событие: {{ lastEvent }}</span>
  </div>
</template>
```

The `actions` slot replaces the pair of buttons with your own: it receives `save`,
`cancel` and `isPristine` — the flag telling that nothing was changed in the
calendar.

**Example — `CustomActions.vue`:**

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

const date = ref('22.02.2022');
</script>

<template>
  <div class="flex flex-col items-center">
    <CdsDateInput v-model="date" class="w-[250px]" label="Дата" :hide-actions="false">
      <template #actions="{ save, cancel, isPristine }">
        <div class="flex px-4 pb-4 gap-2 justify-end">
          <CdsButton variant="soft" color="neutral" size="sm" text="Закрыть" @click="cancel" />
          <CdsButton size="sm" text="Выбрать дату" :disabled="isPristine" @click="save" />
        </div>
      </template>
    </CdsDateInput>
  </div>
</template>
```

### Manual input

`update-on` sets the moment the typed value is parsed and gets into the model: by
default these are `blur` and `enter`. A string that cannot be parsed by `mask`
(or by a string `display-format`) is ignored — the field restores the previous
value. An empty array forbids keyboard input and leaves the calendar only.

The component does not impose an input mask — add one with a directive, using the
lightweight (2.5 KB) [Maska](https://github.com/beholdr/maska) library, for
example.

**Example — `ManualInput.vue`:**

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

const onBlur = ref('22.02.2022');
const onEnter = ref('22.02.2022');
const pickerOnly = ref('22.02.2022');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput v-model="onBlur" v-maska="'##.##.####'" class="w-[250px]" label="По уходу фокуса" />

    <CdsDateInput
      v-model="onEnter"
      v-maska="'##.##.####'"
      class="w-[250px]"
      label="Только по Enter"
      :update-on="['enter']"
    />

    <CdsDateInput v-model="pickerOnly" class="w-[250px]" label="Только календарь" :update-on="[]" />
  </div>
</template>
```

### Date restrictions

The calendar props are available right on the field: `allowed-dates` leaves only
the needed days available, `min-year-month` and `max-year-month` do not let the
navigation go beyond the range.

**Example — `AllowedDates.vue`:**

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

const date = ref<string | null>(null);

const pad = (value: number) => String(value).padStart(2, '0');
const now = new Date();
const last = new Date(now.getFullYear(), now.getMonth() + 2, 1);
const min = `${now.getFullYear()}/${pad(now.getMonth() + 1)}`;
const max = `${last.getFullYear()}/${pad(last.getMonth() + 1)}`;

// Календарь отдаёт дату строкой YYYY/MM/DD.
const weekdaysOnly = (hash: string) => {
  const [year, month, day] = hash.split('/').map(Number);
  const weekday = new Date(year, month - 1, day).getDay();

  return weekday !== 0 && weekday !== 6;
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput
      v-model="date"
      class="w-[250px]"
      label="Только будни"
      hint="Навигация ограничена тремя месяцами"
      persistent-hint
      :allowed-dates="weekdaysOnly"
      :min-year-month="min"
      :max-year-month="max"
      clearable
    />
  </div>
</template>
```

### States

`disabled` blocks both the field and the calendar, `readonly` forbids changes but
keeps focus and copying, `error-messages` shows an error under the field.

**Example — `States.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput class="w-[250px]" label="Обычное" model-value="22.02.2022" />

    <CdsDateInput class="w-[250px]" label="Заблокировано" model-value="22.02.2022" disabled />

    <CdsDateInput class="w-[250px]" label="Только чтение" model-value="22.02.2022" readonly />

    <CdsDateInput class="w-[250px]" label="Ошибка" model-value="22.02.2022" error-messages="Дата уже занята" />
  </div>
</template>
```

### The calendar and the menu

`picker-props` passes settings to the calendar — a header with the summary of the
choice, for example, and `menu-props` and `location` control the dropdown menu.

**Example — `PickerAndMenu.vue`:**

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

const withHeader = ref('22.02.2022');
const above = ref('22.02.2022');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDateInput
      v-model="withHeader"
      class="w-[250px]"
      label="Шапка и кнопка «Сегодня»"
      :picker-props="{ header: true, todayBtn: true }"
    />

    <CdsDateInput
      v-model="above"
      class="w-[250px]"
      label="Календарь сверху"
      location="top start"
      :menu-props="{ offset: 8 }"
    />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Unavailable dates are turned off through allowed-dates — a past day cannot be picked. | Any day can be picked, and the user learns about the restriction from an error only after submitting the form. |
| One period in one field: the bounds are visible side by side and are edited together. | Two separate fields let the end be set before the start — that has to be checked by hand. |
| The input mask is hinted in the placeholder, and the field accepts both the keyboard and the calendar. | Manual input is turned off for no reason: a date from an email has to be hunted for in the calendar by clicking. |

## Scenarios

### A reporting period

The period lives in one field: `range` gives `{ from, to }`,
`:hide-actions="false"` turns the choice into a draft, and the preset buttons
write into the same model — the calendar picks their value up.

**Example — `ReportPeriod.vue`:**

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

type Period = { from: string; to: string };

const period = ref<Period | null>({ from: '01.02.2022', to: '28.02.2022' });
const applied = ref<Period | null>(period.value);

const pad = (value: number) => String(value).padStart(2, '0');
const format = (date: Date) => `${pad(date.getDate())}.${pad(date.getMonth() + 1)}.${date.getFullYear()}`;

// Быстрый пресет: последние N дней по сегодняшний день.
function setLastDays(days: number) {
  const to = new Date();
  const from = new Date(to.getFullYear(), to.getMonth(), to.getDate() - days + 1);

  period.value = { from: format(from), to: format(to) };
}
</script>

<template>
  <div class="flex flex-col gap-2 w-[250px] m-auto">
    <CdsDateInput v-model="period" label="Отчётный период" range clearable :hide-actions="false" />

    <div class="flex justify-center gap-1">
      <CdsButton variant="soft" color="neutral" size="sm" text="7 дней" @click="setLastDays(7)" />
      <CdsButton variant="soft" color="neutral" size="sm" text="30 дней" @click="setLastDays(30)" />
    </div>

    <CdsButton text="Сформировать отчёт" :disabled="!period" @click="applied = period" />

    <span class="text-200 text-center text-content-secondary">
      {{ applied ? `Отчёт за ${applied.from} — ${applied.to}` : 'Период не выбран' }}
    </span>
  </div>
</template>
```

### A delivery date

The restrictions work together: `allowed-dates` leaves only the weekdays,
`min-year-month` and `max-year-month` — the nearest two months. Manual input is
turned off here on purpose: an unavailable day cannot be typed in, and
`display-format` shows the date in words.

**Example — `DeliveryDate.vue`:**

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

const date = ref<string | null>(null);

const pad = (value: number) => String(value).padStart(2, '0');
const now = new Date();
const first = new Date(now.getFullYear(), now.getMonth(), now.getDate());
const last = new Date(now.getFullYear(), now.getMonth() + 2, 0);

const min = `${first.getFullYear()}/${pad(first.getMonth() + 1)}`;
const max = `${last.getFullYear()}/${pad(last.getMonth() + 1)}`;

// Доставка ездит по будням в ближайшие два месяца.
const allowedDates = (hash: string) => {
  const [year, month, day] = hash.split('/').map(Number);
  const candidate = new Date(year, month - 1, day);
  const weekday = candidate.getDay();

  return weekday !== 0 && weekday !== 6 && candidate >= first && candidate <= last;
};
</script>

<template>
  <div class="flex flex-col gap-2 w-[250px] m-auto">
    <CdsDateInput
      v-model="date"
      label="Дата доставки"
      display-format="D MMMM YYYY"
      :allowed-dates="allowedDates"
      :min-year-month="min"
      :max-year-month="max"
      :update-on="[]"
      clearable
    />

    <span class="text-200 text-center text-content-secondary">
      {{ date ? `Привезём ${date} с 10:00 до 18:00` : 'Выберите дату доставки' }}
    </span>
  </div>
</template>
```

### A date in a form

The field takes part in CdsForm on a par with the
others: `rules` receive the same string value that lies in the model, so a
"not in the past" check is a plain function. Limiting the navigation through
`min-year-month` backs the rule up rather than replaces it.

**Example — `BookingForm.vue`:**

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

const name = ref('');
const date = ref<string | null>(null);

const pad = (value: number) => String(value).padStart(2, '0');
const now = new Date();
const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());

const rules = {
  required: (value: unknown) => !!value || 'Обязательное поле',
  future: (value: string | null) => {
    if (!value) return true;

    const [day, month, year] = value.split('.').map(Number);

    return new Date(year, month - 1, day) >= today || 'Дата не может быть в прошлом';
  }
};

const minYearMonth = `${today.getFullYear()}/${pad(today.getMonth() + 1)}`;
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[250px] m-auto">
    <CdsTextInput
      v-model="name"
      label="Название встречи"
      placeholder="Введите название встречи"
      :rules="[rules.required]"
    />

    <CdsDateInput
      v-model="date"
      label="Дата встречи"
      :rules="[rules.required, rules.future]"
      :min-year-month="minYearMonth"
      clearable
    />
  </CdsForm>
</template>
```

## API

### CdsDateInput

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the field |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `allowedDates` | `TCalendarAllowedDates \| undefined` | — | no | Array of dates available in the calendar. When a function is used, it receives the date in the YYYY/MM/DD format and must return true or false. |
| `allowedHours` | `number[] \| undefined` | — | no | Configures which hours are available for selection. |
| `allowedMinutes` | `number[] \| undefined` | — | no | Configures which minutes are available for selection. |
| `allowedSeconds` | `number[] \| undefined` | — | no | Configures which seconds are available for selection. |
| `allowedTime` | `((hr: number \| null, min: number \| null, sec: number \| null) => boolean) \| undefined` | — | no | Configures which time is available for selection. |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
| `autocomplete` | `string \| undefined` | — | no | 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` | — | no | Enables autofocus |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
| `color` | `string \| undefined` | — | no | Component color |
| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
| `defaultDate` | `string \| undefined` | — | no | Date used by default when the model is empty (in the YYYY/MM/DD format). |
| `defaultYearMonth` | `string \| undefined` | — | no | Displayed year/month in the YYYY/MM format. The current year/month by default when v-model is not set. |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `displayFormat` | `string \| ((date: Date) => string) \| undefined` | — | no | Display format of the date in the field. A mask (`'D MMMM YYYY'`) or a function receiving the native `Date` and returning a string. By default the value is shown as is — in the `mask` format. |
| `emitImmediately` | `boolean \| undefined` | — | no | Emit the update:modelValue event right when the month or the year changes. Not available with multiple and range. |
| `error` | `boolean \| undefined` | — | no | Error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `events` | `TCalendarEvents \| undefined` | — | no | List of events shown in the calendar. Format: YYYY/MM/DD. |
| `eventsColor` | `TCalendarEventsColor \| undefined` | `'default'` | no | Color of the events in the calendar. |
| `firstDayOfWeek` | `string \| number \| undefined` | `1` | no | First day of the week (Monday by default). |
| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
| `format12h` | `boolean \| undefined` | — | no | Shows the time in the 12-hour AM/PM format. |
| `header` | `boolean \| undefined` | — | no | Show the calendar header |
| `hideActions` | `boolean \| undefined` | `true` | no | Hide the confirmation buttons under the calendar — the chosen date is applied immediately. |
| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hideSiblingMonth` | `boolean \| undefined` | — | no | Hide the days of the neighboring months in the calendar. |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `locale` | `string \| TDateLocale \| undefined` | — | no | Locale for the dates. A locale name ('ru' \| 'en') or a `TDateLocale` object. The current locale from `useLocale` is taken by default, otherwise `ru`. |
| `location` | `Anchor \| undefined` | `'bottom start'` | no | Position of the dropdown calendar relative to the field. |
| `mask` | `string \| undefined` | `'DD.MM.YYYY'` | no | Date/time format |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `maxYearMonth` | `string \| undefined` | — | no | Forbid navigating the calendar past the given maximum date in the YYYY/MM format. |
| `menu` | `boolean \| undefined` | — | no | State of the dropdown calendar (v-model:menu). |
| `menuProps` | `CdsMenuProps \| undefined` | — | no | Props passed through to the CdsMenu component of the dropdown calendar. |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `minYearMonth` | `string \| undefined` | — | no | Forbid navigating the calendar before the given minimum date in the YYYY/MM format. |
| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | v-model modifiers passed by Vue to process the field value |
| `modelValue` | `TDateInputValue \| undefined` | `null` | no | Value of the field: a string in the `mask` format, a `{ from, to }` range object or an array of them with `multiple`/`range`. |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several dates. The v-model must be an array. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `noUnset` | `boolean \| undefined` | — | no | Forbid resetting the date in the calendar. |
| `nowBtn` | `boolean \| undefined` | — | no | Shows the "Now" button. |
| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
| `pickerProps` | `CdsDatePickerProps \| undefined` | — | no | Props passed through to the CdsDatePicker component. They win over the props of the field with the same name. |
| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `prependInnerIcon` | `IconValue \| undefined` | `'calendar'` | no | Icon in the inner prepend slot, before the content of the field |
| `range` | `boolean \| undefined` | — | no | Allows selecting a range of dates. The v-model must be an array. |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
| `role` | `string \| undefined` | — | no | ARIA role for the native input element |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `timePickerProps` | `CdsTimePickerProps \| undefined` | — | no | Props passed through to the CdsTimePicker component. They win over the props of the field with the same name. |
| `todayBtn` | `boolean \| undefined` | — | no | Show the "Today" button in the calendar header |
| `type` | `string \| undefined` | `'text'` | no | Type of the native input |
| `updateOn` | `("enter" \| "blur")[] \| undefined` | `['blur', 'enter']` | no | Events that apply the manually entered value. An empty array forbids manual input — the field becomes read-only. |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `view` | `"Calendar" \| "Years" \| "Months" \| undefined` | `'Calendar'` | no | Default calendar view. Possible values: 'Calendar', 'Years', 'Months'. |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `withSeconds` | `boolean \| undefined` | — | no | Adds seconds to the time selection. |
| `withTime` | `boolean \| undefined` | — | no | Adds a time selection (CdsTimePicker) under the calendar and appends the time to the mask. Works for a single date only — ignored with `multiple` and `range`. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `cancel` | `[]` | The selection was cancelled by the cancel button. |
| `navigation` | `[payload: { year: number \| undefined; month: number \| undefined; }]` | Navigation to another month or year in the calendar. |
| `rangeEnd` | `[payload: { from: Partial<IRawDate>; to: Partial<IRawDate>; }]` | End of a date range selection. |
| `rangeStart` | `[value: Partial<IRawDate>]` | Start of a date range selection. |
| `save` | `[value: TDateInputValue]` | The value was confirmed — by a selection in the calendar or by the save button. |
| `update:focused` | `[focused: boolean]` | The focus state of the field changed (v-model:focused). |
| `update:menu` | `[value: boolean]` | The state of the dropdown calendar changed (v-model:menu). |
| `update:modelValue` | `[value: TDateInputValue]` | The value of the field changed (v-model). |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `CdsDateInputActionsSlot` | Confirmation buttons under the calendar (relevant with `hide-actions="false"`). |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
| `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 |
| `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). |
| `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 |
| `picker-description` | `{ year: string \| number \| undefined; }` | Description in the calendar header. |
| `picker-title` | `{ date: string; }` | Title in the calendar header. |
| `prepend` | `CdsInputSlot` | Adds an element before the input |
| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `cancel` | `() => void` | Cancels the selection, restores the previous value and closes the popup. |
| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
| `fieldIconColor` | `string \| undefined` | Icon color |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `save` | `() => void` | Confirms the date chosen in the calendar and closes the popup. |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsDatePicker

_Category: Controls · since 4.0.0_

_Tests: API 35/35 · 79 unit · 2 e2e · 14 known bugs · lines 94.6% (v4.0.0-alpha.13) · a11y: 32 axe recommendations (v4.0.0-alpha.11)_

A calendar for picking a date — a single one, several or a range. It lives right on the page or in a dropdown menu next to a field; the value is a string in the given format (`DD.MM.YYYY` by default), which is convenient to store and to send to the server.

**See also:** If the calendar needs a field, take the ready CdsDateInput — it assembles the very same thing out of a field, a menu and this calendar, adding manual input and time. For picking the time alone there is CdsTimePicker.

## Anatomy

The calendar consists of an optional header with the summary of the choice, the
month and year navigation, the grid of days and the actions zone. The header is
turned on by `header`, the "Today" button — by `today-btn`, and the actions are
added into the default slot.

## Variations

### Value and format

The chosen date arrives in `v-model` as a string in the `mask` format —
`DD.MM.YYYY` by default. A repeated click on the selected day clears the
selection; `no-unset` forbids such a reset, and `hide-sibling-month` hides the
days of the neighboring months.

**Example — `Default.vue`:**

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

const value = ref<string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" />

    <span class="text-200 text-content-secondary">Значение: {{ value ?? '—' }}</span>
  </div>
</template>
```

### Header

`header` turns on the header with the summary of the choice: the title shows the
date or the number of the chosen days, the description — the year. The texts are
replaced by the `title` and `description` props or by the slots of the same name.
`today-btn` adds a button that brings you back to the current day.

**Example — `Header.vue`:**

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

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" header today-btn />
  </div>
</template>
```

### A date range

`range` switches the calendar to picking a period: the first click fixes the
start (the `range-start` event), the second one — the end (`range-end`), and the
value arrives as a `{ from, to }` object. Together with `multiple` several
periods can be picked.

**Example — `Range.vue`:**

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

const value = ref<{ from: string; to: string } | string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" range header />

    <span class="text-200 text-content-secondary">Значение: {{ value ? JSON.stringify(value) : '—' }}</span>
  </div>
</template>
```

### Several dates

`multiple` allows marking individual dates — the model becomes an array of
strings.

**Example — `Multiple.vue`:**

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

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" multiple header />

    <span class="text-200 text-content-secondary">Значение: {{ JSON.stringify(value) }}</span>
  </div>
</template>
```

### Events

`events` marks dates with dots: it accepts an array of dates in the `YYYY/MM/DD`
format or a predicate function. The color of a dot is set by `events-color` — as
a string or as a function of the date, when there are several types of events.

**Example — `Events.vue`:**

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

const value = ref<string | null>(null);
const now = new Date();
const ym = `${now.getFullYear()}/${String(now.getMonth() + 1).padStart(2, '0')}`;
const events = [`${ym}/05`, `${ym}/12`, `${ym}/20`];
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :events="events" events-color="success" />
  </div>
</template>
```

### Available dates

`allowed-dates` limits the choice: an array of dates or a function that receives
a `YYYY/MM/DD` date and returns whether it can be picked. The rest of the days
are turned off.

**Example — `AllowedDates.vue`:**

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

const value = ref<string | null>(null);
// Разрешаем выбирать только будни.
const allowedDates = (date: string) => {
  const [y, m, d] = date.split('/').map(Number);
  const day = new Date(y, m - 1, d).getDay();
  return day !== 0 && day !== 6;
};
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :allowed-dates="allowedDates" />
  </div>
</template>
```

### Navigation bounds

`min-year-month` and `max-year-month` (the `YYYY/MM` format) do not let you go
beyond the range — the arrows at the bound are turned off. Watch the moves
between months through the `navigation` event.

**Example — `LimitedNavigation.vue`:**

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

const value = ref<string | null>(null);
const year = new Date().getFullYear();
const min = `${year}/01`;
const max = `${year}/12`;
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :min-year-month="min" :max-year-month="max" />
  </div>
</template>
```

### Starting view

`view` opens the calendar right at the list of months (`Months`) or years
(`Years`) — handy for dates far from the current one. `default-year-month` sets
the starting month when the model is empty.

**Example — `DefaultView.vue`:**

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

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" view="Months" />
  </div>
</template>
```

### Localization

`locale` accepts a locale name (`ru` | `en`) or your own object of translations;
without the prop the locale of the application is used. `first-day-of-week` sets
the first day of the week — for `en` it is usually Sunday.

**Example — `Localization.vue`:**

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

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
  </div>
</template>
```

### States

`disabled` turns the calendar off and dims it, `readonly` keeps the usual look
but blocks both the selection and the navigation.

**Example — `DisabledReadonly.vue`:**

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

const now = new Date();
const value = ref(`15.${String(now.getMonth() + 1).padStart(2, '0')}.${now.getFullYear()}`);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <div class="w-fit">
      <CdsDatePicker v-model="value" disabled header />
    </div>

    <div class="w-fit">
      <CdsDatePicker v-model="value" readonly header />
    </div>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Unavailable days are turned off through allowed-dates — a wrong choice is impossible. | Every day looks available, and the user learns that weekends do not fit from an error only after the choice. |
| Turn the header on when picking a range — it shows the whole chosen period. | Without the header the result of the choice is captioned nowhere: the user counts the days by the highlight. |
| Only meaningful dates are marked with events — the dots are noticeable and guide the eye. | An event on every day turns the marks into noise: the calendar stops telling anything. |

## Scenarios

### A field with a date

Most often the calendar lives not on the page but in a menu next to a text field.
CdsDateInput exists for that — it is already
assembled out of a field, a menu and the calendar, it parses the manual input and
accepts all the calendar props directly. Build the control yourself only if you
need a non-standard scheme: out of
CdsTextInput, a
CdsMenu with `activator="parent"` and the calendar —
that way all the props and slots of the field and the menu stay available to you.
In that case add the input mask yourself: we recommend the lightweight (2.5 KB)
[Maska](https://github.com/beholdr/maska) library.

**Example — `WithTextInputField.vue`:**

```vue
<script setup lang="ts">
import { CdsDatePicker, CdsMenu, CdsTextInput } from '@central-design-system/components';
import { vMaska } from 'maska/vue';
import { ref } from 'vue';

const date = ref('22.02.2022');
</script>

<template>
  <div class="w-[250px] m-auto">
    <CdsTextInput
      v-model="date"
      v-maska="'##.##.####'"
      label="Дата"
      placeholder="Выберите дату"
      append-inner-icon="calendar"
    >
      <CdsMenu activator="parent" :close-on-content-click="false">
        <CdsDatePicker v-model="date" />
      </CdsMenu>
    </CdsTextInput>
  </div>
</template>
```

### A reporting period

The default slot adds actions under the calendar. Here the chosen range is a
draft: it gets into the report only after the "Apply" button, while "Reset"
returns the calendar to its initial state.

**Example — `ReportPeriod.vue`:**

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

type TRange = { from: string; to: string };

const draft = ref<TRange | string | null>(null);
const period = ref<string | null>(null);

function apply() {
  if (!draft.value) {
    period.value = null;
  } else if (typeof draft.value === 'string') {
    period.value = draft.value;
  } else {
    period.value = `${draft.value.from} — ${draft.value.to}`;
  }
}

function reset() {
  draft.value = null;
  period.value = null;
}
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsDatePicker v-model="draft" range header>
        <div class="flex justify-end gap-2">
          <CdsButton variant="soft" color="neutral" size="sm" text="Сбросить" @click="reset" />
          <CdsButton size="sm" text="Принять" @click="apply" />
        </div>
      </CdsDatePicker>
    </CdsCard>

    <span class="text-200 text-content-secondary">Период отчёта: {{ period ?? 'не выбран' }}</span>
  </div>
</template>
```

### A delivery date

The restrictions work together: `allowed-dates` leaves only the weekdays, and
`min-year-month` and `max-year-month` do not let you go beyond the nearest two
months — the unavailable options do not even have to be explained.

**Example — `DeliveryDate.vue`:**

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

const date = ref<string | null>(null);

const pad = (value: number) => String(value).padStart(2, '0');

// Доставка доступна по будням в ближайшие два месяца.
const now = new Date();
const firstDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
const lastDay = new Date(now.getFullYear(), now.getMonth() + 2, 0);

const min = `${firstDay.getFullYear()}/${pad(firstDay.getMonth() + 1)}`;
const max = `${lastDay.getFullYear()}/${pad(lastDay.getMonth() + 1)}`;

const allowedDates = (hash: string) => {
  const [year, month, day] = hash.split('/').map(Number);
  const candidate = new Date(year, month - 1, day);
  const weekday = candidate.getDay();

  return weekday !== 0 && weekday !== 6 && candidate >= firstDay && candidate <= lastDay;
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsDatePicker v-model="date" :allowed-dates="allowedDates" :min-year-month="min" :max-year-month="max" />
    </CdsCard>

    <span class="text-200 text-content-secondary">
      {{ date ? `Привезём ${date} с 10:00 до 18:00` : 'Выберите дату доставки' }}
    </span>
  </div>
</template>
```

### Date and time

The calendar does not pick the time — put a
CdsTimePicker next to it with a shared model and
the same `DD.MM.YYYY HH:mm` mask: every component changes its own part of the
string. In a field the very same thing is turned on by a single prop —
`with-time` on CdsDateInput.

**Example — `DateAndTime.vue`:**

```vue
<script setup lang="ts">
import { CdsCard, CdsDatePicker, CdsDivider, CdsTimePicker } from '@central-design-system/components';
import { ref } from 'vue';

const now = new Date();
const dateTime = ref(`15.${String(now.getMonth() + 1).padStart(2, '0')}.${now.getFullYear()} 12:35`);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="flex w-fit flex-col">
      <CdsDatePicker v-model="dateTime" mask="DD.MM.YYYY HH:mm" header today-btn />
      <CdsDivider />
      <CdsTimePicker v-model="dateTime" mask="DD.MM.YYYY HH:mm" />
    </CdsCard>

    <span class="text-200 text-content-secondary">Значение: {{ dateTime }}</span>
  </div>
</template>
```

## API

### CdsDatePicker

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `allowedDates` | `TCalendarAllowedDates \| undefined` | — | no | Array of dates available in the calendar. When a function is used, it receives the date in the YYYY/MM/DD format and must return true or false. |
| `defaultYearMonth` | `string \| undefined` | — | no | Displayed year/month in the YYYY/MM format. The current year/month by default when v-model is not set. |
| `description` | `string \| undefined` | — | no | Description of the calendar. Shown in the calendar header. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `emitImmediately` | `boolean \| undefined` | — | no | Emit the update:modelValue event right when the month or the year changes. Not available with multiple and range. |
| `events` | `TCalendarEvents \| undefined` | — | no | List of events shown in the calendar. Format: YYYY/MM/DD. |
| `eventsColor` | `TCalendarEventsColor \| undefined` | `'default'` | no | Color of the events in the calendar. |
| `firstDayOfWeek` | `string \| number \| undefined` | `1` | no | First day of the week (Monday by default). |
| `header` | `boolean \| undefined` | — | no | Show the calendar header |
| `hideSiblingMonth` | `boolean \| undefined` | — | no | Hide the days of the neighboring months in the calendar. |
| `locale` | `string \| TDateLocale \| undefined` | — | no | Locale for the dates. A locale name ('ru' \| 'en') or a `TDateLocale` object. The current locale from `useLocale` is taken by default, otherwise `ru`. |
| `mask` | `string \| undefined` | `'DD.MM.YYYY'` | no | Date/time format |
| `maxYearMonth` | `string \| undefined` | — | no | Forbid navigating the calendar past the given maximum date in the YYYY/MM format. |
| `minYearMonth` | `string \| undefined` | — | no | Forbid navigating the calendar before the given minimum date in the YYYY/MM format. |
| `modelValue` | `string \| TDatetimeValueRange \| (string \| TDatetimeValueRange)[] \| null \| undefined` | `null` | no | Value of the model |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several dates. The v-model must be an array. |
| `noUnset` | `boolean \| undefined` | — | no | Forbid resetting the date in the calendar. |
| `range` | `boolean \| undefined` | — | no | Allows selecting a range of dates. The v-model must be an array. |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| undefined` | — | no | Title of the calendar. Shown in the calendar header. |
| `todayBtn` | `boolean \| undefined` | — | no | Show the "Today" button in the calendar header |
| `view` | `"Calendar" \| "Years" \| "Months" \| undefined` | `'Calendar'` | no | Default calendar view. Possible values: 'Calendar', 'Years', 'Months'. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `navigation` | `[payload: { year: number \| undefined; month: number \| undefined; }]` | Navigation to another month or year (also fires when the model is changed from outside). |
| `rangeEnd` | `[payload: { from: Partial<IRawDate>; to: Partial<IRawDate>; }]` | End of a date range selection. |
| `rangeStart` | `[value: Partial<IRawDate>]` | Start of a date range selection. |
| `update:modelValue` | `[value: string \| TDatetimeValueRange \| (string \| TDatetimeValueRange)[] \| null, reason: string, details: Partial<IRawDate>]` | The value changed (v-model). Passes the value, the reason of the change and the details of the date. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Additional buttons under the calendar. |
| `description` | `{ year: string \| number \| undefined; }` | Description of the title. |
| `title` | `{ date: string; }` | Title of the calendar. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `offsetCalendar` | `(type: "year" \| "month", descending: number) => void` | Moves the calendar one step forward or backward by months or by years. |
| `setCalendarTo` | `(year: number, month: number) => void` | Scrolls the calendar to the given year and month without changing the selected value. |
| `setEditingRange` | `(from: IRawDate, to: IRawDate) => void` | Sets the highlighted date range in `range` mode without confirming the selection. |
| `setToday` | `() => void` | Selects today's date and scrolls the calendar to the current month. |
| `setView` | `(viewMode: "Calendar" \| "Years" \| "Months") => void` | Switches the calendar view: days, months or years. |

---

# CdsDefaultsProvider

_Category: Other_

_Tests: API 6/6 · 13 unit · 2 known bugs · lines 100% (v4.0.0-alpha.13)_

## API

### CdsDefaultsProvider

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `defaults` | `DefaultsOptions` | — | no | Значения пропсов по умолчанию для компонентов внутри — объект вида `{ CdsButton: { size: 'small' } }` |
| `disabled` | `boolean \| undefined` | — | no | Отключает провайдер: вложенные компоненты используют значения из внешнего контекста |
| `reset` | `string \| number \| undefined` | — | no | Сколько уровней вложенных провайдеров сбросить перед применением своих значений |
| `root` | `string \| boolean \| undefined` | — | no | Применяет значения к корневому уровню приложения. Строка — имя корневого набора значений |
| `scoped` | `boolean \| undefined` | — | no | Не наследовать значения внешних провайдеров — использовать только собственный `defaults` |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default slot |

---

# CdsDescription

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 4/4 · 8 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 0 axe recommendations (v4.0.0-alpha.11)_

A description is muted text under the label of a field. It clarifies what to enter and in what format, so the label can stay short.

**See also:** Inputs already have the description built in — the `description` prop of CdsTextInput and the other controls. A standalone `CdsDescription` is needed for groups of fields and for your own controls. For the label of a field take CdsLabel, for the messages under a field take CdsMessages.

## Variations

### Text

The `text` prop sets the content. The `default` slot adds arbitrary markup to it
— a highlighted input format, for example.

**Example — `Text.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDescription text="Укажите ИНН из 10 или 12 цифр" />

    <CdsDescription> Формат — <b>ДД.ММ.ГГГГ</b> </CdsDescription>
  </div>
</template>
```

### Tag

By default the description renders as a `div` tag. The `tag` prop changes the
tag — to `p`, for example, when the description lives inside the text of the
page.

**Example — `Tag.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsDescription tag="p" text="Описание отрендерено тегом p" />
  </div>
</template>
```

## Scenarios

### An explanation for a group of fields

A group of checkboxes has no `description` of its own, so the label and the
explanation are assembled by hand: `CdsLabel` names the group, `CdsDescription`
explains what to pick.

**Example — `FieldsetHint.vue`:**

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

const channels = ref(['email']);
</script>

<template>
  <div class="flex flex-col gap-1 w-[350px] m-auto">
    <CdsLabel text="Уведомления" />
    <CdsDescription text="Выберите, куда присылать сообщения о новых заявках" />

    <CdsCheckbox v-model="channels" value="email" label="Электронная почта" multiple hide-details />
    <CdsCheckbox v-model="channels" value="sms" label="SMS" multiple hide-details />
  </div>
</template>
```

## API

### CdsDescription

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Text of the description |

---

# CdsDivider

_Category: Atoms · since 4.0.0_

_Tests: API 11/11 · 24 unit · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A divider is a thin line between the meaningful parts of an interface: the sections of a form, the rows of a list, the blocks of a card. It does nothing and asks for no attention, it only shows the border where the paddings are no longer enough. A short caption can go into its slot — "or" between two ways of doing something, for example.

**See also:** The blocks of a card are separated by the `divider` prop of CdsCard — it draws the same line without adding markup. If the parts of the screen need to be moved onto different surfaces rather than separated, take CdsSurface.

## Variations

### Appearance

The `variant` prop sets the style of the line: `solid` by default, while
`dashed`, `dotted` and `double` mark the border as temporary or technical.

**Example — `Variants.vue`:**

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

const { variants } = CdsDivider.constants;
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-3">
    <div v-for="variant of variants" :key="variant" class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">{{ variant }}</span>
      <CdsDivider :variant="variant" :thickness="variant === 'double' ? 3 : undefined" />
    </div>
  </div>
</template>
```

### Thickness and length

The `thickness` prop sets the thickness of the line in pixels, `length` sets its
length. Without `length` the divider takes the whole width of its parent (or its
whole height when the divider is vertical).

**Example — `Thickness.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-3">
    <CdsDivider />
    <CdsDivider :thickness="2" />
    <CdsDivider :thickness="4" />
  </div>
</template>
```

**Example — `Length.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col items-center gap-3">
    <CdsDivider length="80" />
    <CdsDivider length="180" />
    <CdsDivider length="100%" />
  </div>
</template>
```

### Color and opacity

The `color` prop accepts a color alias (`green`, `red`, `purple`) or a design
system token, `opacity` accepts a value from 0 to 1. Color is appropriate when
the line carries meaning: the border of an overdue period, a gap in the history
of events.

**Example — `Colors.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-3">
    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">По умолчанию</span>
      <CdsDivider :thickness="2" />
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">color="green"</span>
      <CdsDivider color="green" :thickness="2" />
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">color="brand-primary"</span>
      <CdsDivider color="brand-primary" :thickness="2" />
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">opacity="0.3"</span>
      <CdsDivider :thickness="2" opacity="0.3" />
    </div>
  </div>
</template>
```

### Inset

The `inset` prop shifts a horizontal divider 72 px from the start of the row —
so the line starts under the text rather than under the icon or the avatar. On a
vertical divider `inset` shortens the line from the top and the bottom.

**Example — `Inset.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-4">
    <div class="flex flex-col gap-3">
      <span class="text-100 text-content-secondary">Горизонтальный: отступ слева</span>
      <CdsDivider />
      <CdsDivider inset />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-100 text-content-secondary">Вертикальный: линия короче</span>
      <div class="flex h-[64px] justify-center gap-4">
        <CdsDivider vertical />
        <CdsDivider vertical inset />
      </div>
    </div>
  </div>
</template>
```

### Fading

The `gradient` prop dissolves the line towards its edges. Such a divider is
softer than the regular one and looks good inside dense blocks where a sharp
border would read as a frame.

**Example — `Gradient.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-4">
    <CdsDivider gradient :thickness="2" />

    <div class="flex h-[96px] justify-center">
      <CdsDivider gradient vertical :thickness="2" />
    </div>
  </div>
</template>
```

### Orientation

The `vertical` prop turns the divider. A vertical line stretches to the height
of its neighbors, so its parent needs a height — usually a `display: flex` row.

**Example — `Vertical.vue`:**

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

<template>
  <div class="m-auto flex h-[56px] items-center justify-center gap-4">
    <div class="flex flex-col gap-0.5">
      <span class="text-100 text-content-secondary">Заявок</span>
      <span class="text-500">128</span>
    </div>

    <CdsDivider vertical />

    <div class="flex flex-col gap-0.5">
      <span class="text-100 text-content-secondary">В работе</span>
      <span class="text-500">34</span>
    </div>
  </div>
</template>
```

### Content

The content of the `default` slot stands in the break of the line: the divider
turns into a caption of the border — "or", a date, the name of a section.

**Example — `Content.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-4">
    <CdsDivider>или</CdsDivider>

    <CdsDivider gradient>12 мая</CdsDivider>

    <div class="flex h-[120px] justify-center">
      <CdsDivider vertical>или</CdsDivider>
    </div>
  </div>
</template>
```

The `content-offset` prop increases the distance from the content to the line.
An array of two values additionally shifts the content itself: downwards on a
horizontal divider, to the right on a vertical one.

**Example — `ContentOffset.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">content-offset="32"</span>
      <CdsDivider content-offset="32">или</CdsDivider>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">:content-offset="[32, -10]"</span>
      <CdsDivider :content-offset="[32, -10]">или</CdsDivider>
    </div>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A divider sets the meaningful groups apart: the details separately, the contacts separately. | A line after every row creates noise and does not help reading the list. |
| A caption in a divider is one or two words: it names the border instead of explaining it. | A long phrase breaks the line and pulls the attention onto itself. |
| A thin neutral line: the border is visible and the attention stays on the content. | A thick colored divider reads as an interface element in its own right. |

## Scenarios

### An alternative way to sign in

A divider with the "or" caption sets two equal paths apart and explains that the
second one is not a continuation of the first. `content-offset` gives the
caption some air so it does not blend with the buttons.

**Example — `AuthOptions.vue`:**

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

const email = ref('');
const loading = ref(false);

const sendLink = async () => {
  loading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 1500));

  loading.value = false;
};
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-2">
    <CdsTextInput v-model="email" label="Рабочая почта" placeholder="name@company.ru" hide-details />

    <CdsButton block text="Прислать ссылку для входа" :loading="loading" @click="sendLink" />

    <CdsDivider content-offset="8">или</CdsDivider>

    <CdsButton variant="soft" color="brand" block text="Войти по паролю" />
  </div>
</template>
```

### Rows of a list

Between the rows of a list a divider replaces the frames: the borders are
visible, but the list does not turn into a table. The line goes between the
items rather than after each one — the first and the last row do not have it.

**Example — `DocumentList.vue`:**

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

const query = ref('');

const documents = [
  { title: 'Договор поставки №1024', date: '12 мая' },
  { title: 'Договор аренды №87', date: '30 апреля' },
  { title: 'Акт сверки за I квартал', date: '14 апреля' },
  { title: 'Счёт на оплату №5512', date: '2 апреля' }
];

const filtered = computed(() =>
  documents.filter((document) => document.title.toLowerCase().includes(query.value.trim().toLowerCase()))
);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsTextInput v-model="query" placeholder="Поиск по документам" hide-details />

    <div class="flex flex-col">
      <template v-for="(document, index) of filtered" :key="document.title">
        <CdsDivider v-if="index" />

        <div class="flex items-center justify-between gap-2 py-2">
          <span>{{ document.title }}</span>
          <span class="text-100 text-content-secondary">{{ document.date }}</span>
        </div>
      </template>

      <span v-if="!filtered.length" class="py-2 text-content-secondary">Ничего не найдено</span>
    </div>
  </div>
</template>
```

### Metadata of a record

Vertical dividers break up a row of facts — status, date, author — taking almost
no space. A `display: flex` and a height are enough for the parent row to make
the lines stretch along the text.

**Example — `RecordMeta.vue`:**

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

<template>
  <div class="m-auto flex w-[360px] flex-col gap-1">
    <span class="text-300">Договор поставки №1024</span>

    <div class="text-100 text-content-secondary flex h-[16px] items-center gap-2">
      <span>На согласовании</span>
      <CdsDivider vertical />
      <span>12 мая</span>
      <CdsDivider vertical />
      <span>Иван Петров</span>
    </div>
  </div>
</template>
```

### Sections of a form

A divider with a caption in the slot names a new group of fields. It is calmer
than a heading: the rest of the form reads as a continuation rather than as the
start of another form.

**Example — `FormSections.vue`:**

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

const company = ref('');
const inn = ref('');
const email = ref('');
const phone = ref('');
</script>

<template>
  <CdsForm class="m-auto flex w-[350px] flex-col gap-2" @submit.prevent>
    <CdsTextInput v-model="company" label="Название компании" hide-details />
    <CdsTextInput v-model="inn" label="ИНН" hide-details />

    <div class="my-2">
      <CdsDivider content-offset="8">Контакты</CdsDivider>
    </div>

    <CdsTextInput v-model="email" label="Почта" hide-details />
    <CdsTextInput v-model="phone" label="Телефон" hide-details />
  </CdsForm>
</template>
```

## API

### CdsDivider

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Color of the divider. |
| `contentOffset` | `string \| number \| (string \| number)[] \| undefined` | — | no | Increases the spacing between the content and the lines. When passed as an array, the second value shifts the slot content down (or right when vertical = true). |
| `gradient` | `boolean \| undefined` | — | no | Adds a fade-out effect on both ends. |
| `inset` | `boolean \| undefined` | — | no | Adds an indent to horizontal dividers and reduces the maximum height of vertical ones. |
| `length` | `string \| number \| undefined` | — | no | Length of the divider. Defaults to pixels. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the divider. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `thickness` | `string \| number \| undefined` | — | no | Thickness of the divider. Defaults to pixels. |
| `variant` | `"solid" \| "dotted" \| "dashed" \| "double" \| undefined` | `'solid'` | no | Visual variant of the divider |
| `vertical` | `boolean \| undefined` | — | no | Renders the divider vertically |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Text or content placed in the gap of the divider |

---

# CdsDrawer

_Category: Layouts · since 4.0.0_

_Tests: API 33/33 · 76 unit · 3 e2e · 3 known bugs · lines 93.1% (v4.0.0-alpha.13) · a11y: 14 axe recommendations (v4.0.0-alpha.11)_

The side panel of the application: navigation sections on the left, the context of a record or filters on the right. Inside `CdsLayout` the drawer takes its place in the layout and pushes the content aside, and in temporary mode it slides out over it.

**See also:** For a list of sections inside the drawer take CdsList; for navigating the subsections of a single page take CdsTabs. The drawer is a part of the CdsLayout frame, but unlike the other parts it also works on its own: with the `fixed` prop it sticks to the window without a layout.

## Anatomy

The drawer consists of a scrollable navigation list and two pinned areas:
`prepend` on top — for a logo or a profile, `append` at the bottom — for the
sign-out and utility links. The `border` prop draws borders between the areas.

## Variations

### Permanent drawer

The `permanent` prop keeps the drawer on the screen at all times. Without it the
drawer hides on screens narrower than 1056 px — the content gets the whole
width, and the navigation is opened by a button.

**Example — `Permanent.vue`:**

```vue
<script setup lang="ts">
import { CdsDrawer, CdsLayout, CdsList, CdsListItem, CdsMain, CdsPage } from '@central-design-system/components';
</script>

<template>
  <div class="h-[580px]">
    <CdsLayout container>
      <CdsDrawer permanent border>
        <CdsList>
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
          <CdsListItem title="Договоры" href="#" prepend-icon="file" />
          <CdsListItem title="Отчёты" href="#" prepend-icon="view-rows" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
            Панель стоит в потоке макета: контент начинается сразу за ней и никогда не оказывается под панелью.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Collapsible drawer

A regular drawer follows `v-model` at any screen width. On a wide screen it
sits in the layout, and when closed it gives its place back to the content. On
a narrow screen the same drawer slides out over the content. When the screen
crosses 1056 px, the drawer closes and opens back on its own;
`disable-resize-watcher` turns this sync off. The `width` prop sets the width in
pixels, and the layout shifts the content by exactly that much.

**Example — `Collapsible.vue`:**

```vue
<script setup lang="ts">
import {
  CdsDrawer,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const open = ref<boolean | null>(null);
</script>

<template>
  <div class="h-[580px]">
    <CdsLayout container>
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsFunctionalButton
            icon="menu"
            class="mr-2"
            :aria-label="open ? 'Скрыть навигацию' : 'Показать навигацию'"
            @click="open = !open"
          />
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsDrawer v-model="open" border :width="280">
        <CdsList>
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
          <CdsListItem title="Договоры" href="#" prepend-icon="file" />
          <CdsListItem title="Отчёты" href="#" prepend-icon="view-rows" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
            На широком экране панель стоит в макете и сдвигает контент. Скройте её кнопкой в шапке — контент займёт всю
            ширину. На узком экране та же панель выезжает поверх контента.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Temporary drawer

The `temporary` prop turns the drawer into a sliding one: it takes no place in
the layout, opens through `v-model` and closes on a click on the overlay or on
Esc. The `@opened` and `@closed` events report the change of state.

**Example — `Temporary.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsDrawer,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage
} from '@central-design-system/components';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <div class="h-[580px]">
    <CdsLayout container>
      <CdsDrawer v-model="open" temporary border>
        <CdsList>
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
          <CdsListItem title="Договоры" href="#" prepend-icon="file" />
          <CdsListItem title="Отчёты" href="#" prepend-icon="view-rows" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <CdsButton prepend-icon="menu" @click="open = true">Открыть навигацию</CdsButton>
          <div class="mt-2 rounded-200 bg-surface-secondary p-4 text-content-primary">
            Временная панель выезжает поверх контента и закрывается кликом по затемнению или клавишей Esc.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

On touch screens a sliding drawer can be pulled out with a swipe from the
screen edge and put away with a swipe back. The `touchless` prop turns the
gestures off.

### Without the scrim

The `scrim` prop controls the backdrop under a sliding drawer. `false` removes
it: the content under the drawer stays clickable, but a click outside no longer
closes the drawer, so provide your own button for that. A string instead of
`true` sets the backdrop color; pass it with transparency, for example
`rgb(0 0 0 / 0.3)`, or the content under the drawer is hidden completely.

**Example — `Scrim.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsDrawer,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage
} from '@central-design-system/components';
import { ref } from 'vue';

const open = ref(false);
const clicks = ref(0);
</script>

<template>
  <div class="h-[580px]">
    <CdsLayout container>
      <CdsDrawer v-model="open" temporary right border :scrim="false">
        <CdsList>
          <CdsListItem title="Фильтр: активные" prepend-icon="adjust" />
          <CdsListItem title="Фильтр: архивные" prepend-icon="archive" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="flex flex-wrap gap-2">
            <CdsButton prepend-icon="adjust" @click="open = !open">
              {{ open ? 'Скрыть фильтры' : 'Показать фильтры' }}
            </CdsButton>
            <CdsButton variant="soft" color="brand" @click="clicks++">Кликов по контенту: {{ clicks }}</CdsButton>
          </div>
          <div class="mt-2 rounded-200 bg-surface-secondary p-4 text-content-primary">
            Панель без затемнения: контент под ней не блокируется, поэтому закрывать её нужно своей кнопкой.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Protection from an accidental close

The `persistent` prop keeps a click on the scrim and the Esc key from closing
the drawer: only `v-model` closes it. It suits a drawer with a form, where a
stray click outside would wipe the input.

**Example — `Persistent.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsDrawer,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsTextArea,
  CdsTextInput
} from '@central-design-system/components';
import { ref } from 'vue';

const open = ref(false);
const title = ref('');
const comment = ref('');
</script>

<template>
  <div class="h-[580px]">
    <CdsLayout container>
      <CdsDrawer v-model="open" temporary right persistent border fixed-slots :width="360">
        <template #prepend>
          <span class="text-base font-medium text-content-primary">Новая заявка</span>
        </template>

        <div class="flex flex-col gap-2 px-3">
          <CdsTextInput v-model="title" label="Название" />
          <CdsTextArea v-model="comment" label="Комментарий" />
        </div>

        <template #append>
          <div class="flex justify-end gap-2">
            <CdsButton variant="soft" color="brand" @click="open = false">Отмена</CdsButton>
            <CdsButton variant="solid" color="brand" @click="open = false">Сохранить</CdsButton>
          </div>
        </template>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <CdsButton prepend-icon="add" @click="open = true">Создать заявку</CdsButton>
          <div class="mt-2 rounded-200 bg-surface-secondary p-4 text-content-primary">
            Клик по затемнению и Esc не закрывают панель с формой — только кнопки внутри, поэтому ввод не теряется.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Minified drawer

The `minified` prop shrinks the drawer down to icons and gives the width back to
the content. On hover the drawer expands over the page without pushing it, so
the section labels stay reachable.

**Example — `Minified.vue`:**

```vue
<script setup lang="ts">
import {
  CdsDrawer,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToggle
} from '@central-design-system/components';
import { ref } from 'vue';

const minified = ref(true);
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsToggle v-model="minified" label="Свернуть до иконок" hide-details />

    <div class="h-[480px]">
      <CdsLayout container>
        <CdsDrawer permanent border :minified="minified">
          <CdsList>
            <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
            <CdsListItem title="Договоры" href="#" prepend-icon="file" />
            <CdsListItem title="Отчёты" href="#" prepend-icon="view-rows" />
          </CdsList>
        </CdsDrawer>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Наведите курсор на свёрнутую панель — она развернётся поверх контента, не сдвигая его.
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Position

The `right` prop moves the drawer to the right edge. The application navigation
usually lives on the left, and the context of the current record — history,
comments, filters — on the right. Both drawers can work in the same layout at
once.

**Example — `Position.vue`:**

```vue
<script setup lang="ts">
import { CdsDrawer, CdsLayout, CdsList, CdsListItem, CdsMain, CdsPage } from '@central-design-system/components';
</script>

<template>
  <div class="h-[480px]">
    <CdsLayout container>
      <CdsDrawer permanent border>
        <CdsList>
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
          <CdsListItem title="Договоры" href="#" prepend-icon="file" />
        </CdsList>
      </CdsDrawer>

      <CdsDrawer permanent right border>
        <CdsList>
          <CdsListItem title="История изменений" href="#" prepend-icon="time" />
          <CdsListItem title="Комментарии" href="#" prepend-icon="message" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
            Слева навигация, справа контекст записи — макет резервирует место под обе панели.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Color

The `bg-color` prop paints the background of the drawer with a palette alias,
`color` paints the text and the icons inside. A dark drawer next to light
content emphasizes the border of the working area.

**Example — `Colors.vue`:**

```vue
<script setup lang="ts">
import {
  CdsDrawer,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup
} from '@central-design-system/components';
import { ref } from 'vue';

const bgColor = ref('default');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="bgColor" direction="horizontal" hide-details>
      <CdsRadio value="default" label="Цвет темы" />
      <CdsRadio value="neutral" label="neutral" />
      <CdsRadio value="indigo" label="indigo" />
      <CdsRadio value="teal" label="teal" />
    </CdsRadioGroup>

    <div class="h-[480px]">
      <CdsLayout container>
        <CdsDrawer permanent :bg-color="bgColor === 'default' ? undefined : bgColor">
          <CdsList>
            <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" />
            <CdsListItem title="Договоры" href="#" prepend-icon="file" />
            <CdsListItem title="Отчёты" href="#" prepend-icon="view-rows" />
          </CdsList>
        </CdsDrawer>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Background image

The `image` prop puts an image from a URL under the drawer content, and the
`image` slot takes custom background markup. Color the text on top with the
`color` prop so it stays readable.

**Example — `Image.vue`:**

```vue
<script setup lang="ts">
import { CdsDrawer, CdsLayout, CdsList, CdsListItem, CdsMain, CdsPage } from '@central-design-system/components';
</script>

<template>
  <div class="h-[580px]">
    <CdsLayout container>
      <CdsDrawer permanent image="/images/temp/space.webp" color="content-on-dark">
        <CdsList bg-color="transparent">
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" />
          <CdsListItem title="Договоры" href="#" prepend-icon="file" />
          <CdsListItem title="Отчёты" href="#" prepend-icon="view-rows" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
            Свойство <code>image</code> кладёт картинку под содержимое панели. Для своей разметки фона — градиента или
            видео — есть слот <code>image</code>.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Slots

| Slot      | Description                                        |
| --------- | -------------------------------------------------- |
| `prepend` | Pinned area on top: logo, profile                  |
| `default` | Navigation items                                   |
| `append`  | Pinned area at the bottom: sign-out, utility links |
| `image`   | Background under the drawer content                |

The `fixed-slots` prop keeps `prepend` and `append` in place and gives the
scroll to the list of sections only — long navigation no longer pushes the
sign-out button past the edge.

**Example — `Slots.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsButton,
  CdsDrawer,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[380px]">
    <CdsLayout container>
      <CdsDrawer permanent border fixed-slots>
        <template #prepend>
          <div class="flex items-center gap-2">
            <CdsAvatar icon="company" />
            <span class="font-bold text-content-primary">Портал закупок</span>
          </div>
        </template>

        <CdsList>
          <CdsListItem v-for="n in 12" :key="n" :title="'Раздел ' + n" href="#" prepend-icon="file" />
        </CdsList>

        <template #append>
          <CdsButton variant="soft" color="neutral" block prepend-icon="logout">Выйти</CdsButton>
        </template>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
            Список разделов скроллится, а шапка и кнопка выхода остаются на месте.
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Icons help recognize the sections and stay readable in a minified drawer. | Without icons a minified drawer turns into an empty strip. |
| The drawer holds the sections of the application; the current one is marked with the active state. | A drawer stuffed with actions and filters stops being navigation. |

## Scenarios

### Application navigation

A logo in `prepend`, the sections in a `CdsList` with `active` on the current
one, a sign-out button in `append`. The `lhh lpr fff` layout scheme gives the
top left corner to the drawer, so it starts from the very top and reads as the
backbone of the application.

**Example — `Navigation.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsButton,
  CdsDrawer,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListGroup,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const sections = [
  { key: 'purchases', title: 'Закупки', icon: 'shopping-cart' },
  { key: 'contracts', title: 'Договоры', icon: 'file' },
  { key: 'reports', title: 'Отчёты', icon: 'view-rows' }
];
const active = ref('purchases');
</script>

<template>
  <div class="h-[560px]">
    <CdsLayout container view="lhh lpr fff">
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsToolbarTitle>{{ sections.find((section) => section.key === active)?.title }}</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsDrawer permanent border fixed-slots>
        <template #prepend>
          <div class="flex items-center gap-2">
            <CdsAvatar icon="company" />
            <span class="font-bold text-content-primary">Портал закупок</span>
          </div>
        </template>

        <CdsList>
          <CdsListItem
            v-for="section in sections"
            :key="section.key"
            :title="section.title"
            :prepend-icon="section.icon"
            :active="active === section.key"
            @click="active = section.key"
          />
          <CdsListGroup>
            <template #activator="{ props }">
              <CdsListItem title="Контрагенты" prepend-icon="company" v-bind="props" />
            </template>
            <CdsListItem title="Поставщики" href="#" prepend-icon="user-group" />
            <CdsListItem title="Заказчики" href="#" prepend-icon="user" />
          </CdsListGroup>
        </CdsList>

        <template #append>
          <CdsButton variant="soft" color="neutral" block prepend-icon="logout">Выйти</CdsButton>
        </template>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
            Раздел «{{ sections.find((section) => section.key === active)?.title }}»
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Notification panel

A right drawer with `temporary` opens from an icon in the header, shows the list
and closes on a click on the overlay. It takes no place in the layout, so the
main content is not rebuilt when it opens.

**Example — `Notifications.vue`:**

```vue
<script setup lang="ts">
import {
  CdsBadge,
  CdsButton,
  CdsDrawer,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const open = ref(false);
const items = ref([
  { id: 1, title: 'Закупка №2401 опубликована', time: '5 минут назад' },
  { id: 2, title: 'Новое предложение от ООО «Вектор»', time: '2 часа назад' },
  { id: 3, title: 'Договор №118 подписан', time: 'вчера' }
]);
</script>

<template>
  <div class="h-[520px]">
    <CdsLayout container>
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
          <CdsBadge :content="items.length" :model-value="items.length > 0">
            <CdsFunctionalButton icon="notification" aria-label="Уведомления" @click="open = true" />
          </CdsBadge>
        </CdsToolbar>
      </CdsHeader>

      <CdsDrawer v-model="open" right temporary border fixed-slots>
        <template #prepend>
          <div class="font-bold text-content-primary">Уведомления</div>
        </template>

        <CdsList>
          <CdsListItem v-for="item in items" :key="item.id" :title="item.title" :subtitle="item.time" href="#" />
        </CdsList>

        <template #append>
          <CdsButton variant="soft" color="neutral" block @click="items = []">Отметить все прочитанными</CdsButton>
        </template>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsDrawer

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `border` | `boolean \| undefined` | `false` | no | Adds borders between the sections (prepend/append). |
| `captureFocus` | `boolean \| undefined` | `true` | no | Returns the focus back into the content if it has left it — for example on Tab from the end of the page. A mouse click does not steal the focus. |
| `color` | `string \| undefined` | — | no | Component color |
| `disableResizeWatcher` | `boolean \| undefined` | `false` | no | Does not sync v-model with the screen width. By default a regular drawer closes when the screen narrows and it becomes a sliding one, and opens back on a wide screen. |
| `fixed` | `boolean \| undefined` | `false` | no | Applies `position: fixed`. |
| `fixedSlots` | `boolean \| undefined` | `false` | no | Uses an inner scroll for the content section. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `image` | `string \| undefined` | — | no | Background image of the drawer (URL). The `image` slot is available for custom background markup. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minified` | `boolean \| undefined` | `false` | no | Minified look (icons only) until the mouse hovers over it. |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| null \| undefined` | `null` | no | Shows/hides the drawer (v-model). Without it a regular drawer is open on a wide screen, and a sliding one is closed. |
| `permanent` | `boolean \| undefined` | `false` | no | Always visible, regardless of the screen size. |
| `persistent` | `boolean \| undefined` | `false` | no | A click on the scrim and the Esc key do not close the drawer, only v-model does. For drawers with a form where an accidental close loses the input. |
| `retainFocus` | `boolean \| undefined` | `true` | no | Traps Tab navigation inside the content: from the last focusable element the focus moves to the first one and back. |
| `right` | `boolean \| undefined` | `false` | no | Positions the drawer on the right. |
| `scrim` | `string \| boolean \| undefined` | `true` | no | Backdrop under the drawer while it covers the content. `false` removes it entirely: the content stays clickable and the drawer closes only with Esc or through v-model; a string sets its color. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'aside'` | no | Custom HTML tag or component to render |
| `temporary` | `boolean \| undefined` | `false` | no | Temporary drawer: slides out over the content at any screen width, opens through v-model and closes on the overlay. On a narrow screen any non-permanent drawer behaves this way. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `touchless` | `boolean \| undefined` | `false` | no | Disables gestures: a sliding drawer neither opens with a swipe from the screen edge nor closes with a swipe. |
| `width` | `string \| number \| undefined` | `240` | no | The drawer width, px. It also goes into the layout: the content shifts by exactly this width. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `closed` | `[value: boolean]` | The drawer has closed. |
| `opened` | `[value: boolean]` | The drawer has opened. |
| `update:modelValue` | `[value: boolean]` | The v-model value has changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `any` | Content after the navigation. |
| `default` | `any` | Navigation items (`CdsList`). |
| `image` | `{ image: string \| undefined; }` | Custom drawer background instead of `CdsImage` from the `image` prop; stretches under the content. |
| `prepend` | `any` | Content before the navigation. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `drawerRef` | `HTMLElement \| undefined` | Ref to the root DOM element of the drawer. |

---

# CdsEmptyState

_Category: Feedback · since 4.0.0_

_Tests: API 32/32 · 36 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 9 axe recommendations (v4.0.0-alpha.11)_

An empty state explains why there is no content on the screen and suggests the next step: no search results, an empty list, a loading error. It is assembled from a media area, headings, a description and an action button.

**See also:** For a short message about the result of an operation take CdsToast, and while the data is still loading show CdsSkeletonLoader instead of an empty state.

## Anatomy

An empty state is a vertical stack of zones. Each zone appears only when its
prop or slot is set, so you pick the composition that fits the situation: from a
single heading line to the full set with media and a button.

## Variations

### Content

Every text zone has its own prop: `headline` is the large accent ("404",
"Empty"), `title` states the situation, `text` gives the details and hints what
to do. The width of the text is capped by `text-width` (500 by default), so a
long description does not stretch across the whole screen.

**Example — `Default.vue`:**

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

<template>
  <CdsEmptyState
    icon="list-search"
    headline="Пусто"
    title="Ничего не найдено"
    text="Попробуйте изменить запрос или сбросить фильтры, чтобы увидеть больше результатов"
  />
</template>
```

### Media

The `icon` prop shows an icon, `image` shows an image (it wins over the icon).
The size of the media comes from `size`: 96 for an icon and 200 for an image by
default. The color of the icon is changed by the `color` prop.

**Example — `Media.vue`:**

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

<template>
  <div class="flex gap-4">
    <CdsEmptyState
      icon="list-search"
      title="Ничего не найдено"
      text="Попробуйте изменить запрос или сбросить фильтры"
      class="flex-1"
    />
    <CdsEmptyState
      image="/images/temp/girl.webp"
      title="Ничего не найдено"
      text="Попробуйте изменить запрос или сбросить фильтры"
      class="flex-1"
    />
  </div>
</template>
```

### Illustrations

Legacy illustrations from the `@central-design-system/illustrations` package
(CDS 3): the `illustration` prop accepts the kebab-case name of a globally
registered component (they are registered through the `illustrations` option of
`createCds`). You can render your own illustration through the `illustration`
slot.

**Example — `Illustration.vue`:**

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

<template>
  <CdsEmptyState
    illustration="search-interface"
    title="Ничего не найдено"
    text="Попробуйте изменить запрос или сбросить фильтры"
  />
</template>
```

### Alignment

The `justify` prop pushes the content to the edge of the container: `start`,
`center` (default) or `end`. The dashed frame in the demo shows the bounds of
the container.

**Example — `Justify.vue`:**

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

<template>
  <div class="flex flex-col gap-4">
    <CdsEmptyState
      justify="start"
      icon="list-search"
      title="Выравнивание start"
      text="Контент прижат к левому краю контейнера"
      class="justify-demo"
    />
    <CdsEmptyState
      justify="end"
      icon="list-search"
      title="Выравнивание end"
      text="Контент прижат к правому краю контейнера"
      class="justify-demo"
    />
  </div>
</template>

<style scoped>
.justify-demo {
  border: 1px dashed var(--cds-color-line-primary);
  border-radius: var(--cds-border-radius-200);
}
</style>
```

### Actions

The `action-text` prop adds a button below the content; a click on it arrives as
the `click:action` event. When there is more than one action, render your own
buttons in the `actions` slot — bind `props.onClick` from the slot to the main
button so that the `click:action` event keeps working.

**Example — `Actions.vue`:**

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

<template>
  <div class="flex gap-4">
    <CdsEmptyState
      icon="list-search"
      title="Ничего не найдено"
      text="Попробуйте изменить запрос или сбросить фильтры"
      action-text="Сбросить фильтры"
      class="flex-1"
    />
    <CdsEmptyState
      icon="list-search"
      title="Ничего не найдено"
      text="Попробуйте изменить запрос или сбросить фильтры"
      class="flex-1"
    >
      <template #actions="{ props }">
        <CdsButton variant="soft" color="brand">Назад</CdsButton>
        <CdsButton v-bind="props">Сбросить фильтры</CdsButton>
      </template>
    </CdsEmptyState>
  </div>
</template>
```

### Slots

Slots replace the content coming from props when you need full control over the
markup.

| Slot           | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `media`        | Media area. Replaces the content from `icon` and `image`   |
| `illustration` | Illustration. Replaces the content from `illustration`     |
| `headline`     | Accent heading. Replaces the text from `headline`          |
| `title`        | Heading. Replaces the text from `title`                    |
| `text`         | Description. Replaces the text from `text`                 |
| `description`  | Extra description. Replaces the text from `description`    |
| `default`      | Arbitrary content between the description and the actions  |
| `actions`      | Action buttons; receives `props` with an `onClick` handler |

**Example — `Slots.vue`:**

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

<template>
  <CdsEmptyState>
    <template #media>
      <CdsImage src="/images/temp/girl.webp" />
    </template>
    <template #title> Заголовок пустого состояния </template>
    <template #text>
      Описание пустого состояния, которое может быть длинным и содержать много текста. Также может описывать варианты
      решения проблемы.
    </template>
    <template #actions="{ props }">
      <CdsButton v-bind="props" text="Добавить данные" />
    </template>
  </CdsEmptyState>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The text explains why the screen is empty, and the button offers a way out. | «Нет данных» не объясняет причину и не подсказывает, что делать дальше. |
| One primary action: it is clear what to do first. | Several equally weighted buttons make the user choose instead of act. |

## Scenarios

### Search with no results

When nothing matches the query, an empty state replaces the list. The button
from `action-text` clears the query on `click:action` — the user returns to the
full list in one click. Try typing a query that is not in the list.

**Example — `SearchResults.vue`:**

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

const query = ref('стол');

const items = ['Кресло офисное', 'Шкаф для документов', 'Стеллаж металлический', 'Лампа настольная'];

const filtered = computed(() => items.filter((item) => item.toLowerCase().includes(query.value.trim().toLowerCase())));
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsTextInput v-model="query" placeholder="Поиск по каталогу" prepend-inner-icon="search" clearable />

    <ul v-if="filtered.length" class="m-0 flex list-none flex-col gap-2 p-0">
      <li v-for="item in filtered" :key="item">{{ item }}</li>
    </ul>

    <CdsEmptyState
      v-else
      icon="list-search"
      title="Ничего не найдено"
      text="Попробуйте изменить запрос или очистить поиск"
      action-text="Очистить поиск"
      @click:action="query = ''"
    />
  </div>
</template>
```

### Empty list

The first visit to a section is a reason not to apologize for the emptiness but
to help the user start: `title` names the situation, `text` promises a result,
and the button from `action-text` creates the first record. Once a record is
added, the list replaces the placeholder.

**Example — `EmptyList.vue`:**

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

const documents = ref<string[]>([]);
let counter = 0;

function addDocument() {
  counter += 1;
  documents.value.push(`Договор поставки № ${counter}`);
}

function removeDocument(index: number) {
  documents.value.splice(index, 1);
}
</script>

<template>
  <div class="m-auto w-[350px]">
    <CdsEmptyState
      v-if="!documents.length"
      icon="file"
      title="У вас пока нет документов"
      text="Добавьте первый документ — он появится в этом списке"
      action-text="Добавить документ"
      @click:action="addDocument"
    />

    <div v-else class="flex flex-col gap-2">
      <div v-for="(doc, index) in documents" :key="doc" class="flex items-center justify-between gap-2">
        <span>{{ doc }}</span>
        <CdsButton
          variant="soft"
          color="neutral"
          size="sm"
          icon="delete"
          aria-label="Удалить"
          @click="removeDocument(index)"
        />
      </div>

      <div class="flex justify-center mt-2">
        <CdsButton variant="soft" color="brand" size="sm" prepend-icon="add" text="Добавить ещё" @click="addDocument" />
      </div>
    </div>
  </div>
</template>
```

### Loading error

If the data failed to load, explain the reason and let the user retry right
there. The button in the `actions` slot shows `loading` while the retry is in
flight, and `props.onClick` from the slot keeps the `click:action` event.

**Example — `LoadingError.vue`:**

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

const state = ref<'error' | 'loading' | 'success'>('error');

async function retry() {
  state.value = 'loading';

  await new Promise((resolve) => setTimeout(resolve, 1500));

  state.value = 'success';
}
</script>

<template>
  <div class="m-auto w-[350px]">
    <CdsEmptyState
      v-if="state !== 'success'"
      icon="error"
      title="Не удалось загрузить данные"
      text="Проверьте соединение с интернетом и попробуйте ещё раз"
      @click:action="retry"
    >
      <template #actions="{ props }">
        <CdsButton v-bind="props" :loading="state === 'loading'" text="Повторить" />
      </template>
    </CdsEmptyState>

    <div v-else class="flex flex-col items-center gap-2">
      <span>Данные успешно загружены</span>
      <CdsButton variant="soft" color="neutral" size="sm" text="Сбросить демо" @click="state = 'error'" />
    </div>
  </div>
</template>
```

### 404 page

`headline` prints the large error code, and `href` (or `to` for vue-router) is
passed to the action button — it works as a link and takes the user away from
the dead-end page.

**Example — `NotFound.vue`:**

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

<template>
  <CdsEmptyState
    headline="404"
    title="Страница не найдена"
    text="Возможно, страница переехала или в адресе опечатка. Начните с главной страницы"
    action-text="На главную"
    href="/"
  />
</template>
```

## API

### CdsEmptyState

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `actionText` | `string \| undefined` | — | no | Text of the action button. When set, a button is rendered below the content. |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `description` | `string \| undefined` | — | no | Description |
| `headline` | `string \| undefined` | — | no | Large accent heading above the main heading. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `icon` | `IconValue \| undefined` | — | no | Icon in the media area. |
| `illustration` | `string \| undefined` | — | no | Legacy illustration from the `@central-design-system/illustrations` package (CDS 3): the kebab-case name of a globally registered component, for example `rocket`. Illustrations are registered through the `illustrations` option of `createCds`. |
| `image` | `string \| undefined` | — | no | Source of the image in the media area (takes priority over `icon`). |
| `justify` | `"start" \| "end" \| "center" \| undefined` | `'center'` | no | Horizontal alignment of the content: `start`, `center`, `end`. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textWidth` | `string \| number \| undefined` | `500` | no | Maximum width of the description block. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| undefined` | — | no | Heading. |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:action` | `[event: MouseEvent]` | Click on the action button. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `{ props: { onClick: (event: MouseEvent) => void; }; }` | Actions slot; receives `props` with an `onClick` handler to bind to your own element. |
| `default` | `any` | Arbitrary content between the description and the actions. |
| `description` | `any` | Description slot (instead of the `description` prop). |
| `headline` | `any` | Accent heading slot (instead of the `headline` prop). |
| `illustration` | `any` | Media area slot for an illustration (instead of the `illustration` prop). |
| `media` | `any` | Media area slot (instead of the `image` / `icon` props). |
| `text` | `any` | Description slot (instead of the `text` prop). |
| `title` | `any` | Heading slot (instead of the `title` prop). |

---

# CdsExpandablePanel

_Category: Content · since 4.0.0_

_Tests: none yet — behavior is not covered by automated tests_

An expandable panel hides the details behind a title: you see the list of topics and open only the one you need. Take it for FAQs, optional settings and long descriptions that turn a page into an endless feed.

**See also:** If the sections are equal in weight and the reader switches between them, take CdsTabs. For a hierarchy of nested nodes take CdsTree, and for a block that simply separates content — CdsCard.

## Anatomy

Panels always live inside a `CdsExpandablePanels` group: it keeps track of which
panels are open and shares the common settings. Each panel is a title button
with a state icon plus the content it reveals.

## Variations

### Panel group

`CdsExpandablePanel` does not work without the `CdsExpandablePanels` wrapper —
the group is what handles expansion. A simple panel is built from the `title`
and `text` props, without slots. By default one panel stays open: opening the
next one collapses the previous.

**Example — `Default.vue`:**

```vue
<script setup lang="ts">
import { CdsExpandablePanel, CdsExpandablePanels } from '@central-design-system/components';
</script>

<template>
  <CdsExpandablePanels class="m-auto max-w-[500px]">
    <CdsExpandablePanel
      title="Условия доставки"
      text="Курьер привезёт заказ в течение трёх рабочих дней и позвонит за час до визита."
    />
    <CdsExpandablePanel
      title="Способы оплаты"
      text="Оплатите картой онлайн или запросите счёт — он придёт на почту в течение часа."
    />
    <CdsExpandablePanel
      title="Возврат"
      text="Вернуть товар можно в течение 14 дней после получения, если он не был в использовании."
    />
  </CdsExpandablePanels>
</template>
```

### Appearance

The `appearance` prop sets the background of the panels: `primary` for a regular
page, `secondary` for a colored backdrop, `transparent` when the panel sits
inside an already styled block (a card, a sidebar).

The `gap` prop changes the spacing between panels — it accepts a number or a
string with CSS units.

**Example — `Appearances.vue`:**

```vue
<script setup lang="ts">
import { CdsExpandablePanel, CdsExpandablePanels } from '@central-design-system/components';

const appearances = ['primary', 'secondary', 'transparent'] as const;

const text = 'Курьер привезёт заказ в течение трёх рабочих дней и позвонит за час до визита.';
</script>

<template>
  <div class="m-auto flex max-w-[500px] flex-col gap-4">
    <CdsExpandablePanels v-for="appearance in appearances" :key="appearance" :appearance="appearance">
      <CdsExpandablePanel :title="`Внешний вид ${appearance}`" :text="text" />
      <CdsExpandablePanel title="Способы оплаты" text="Оплатите картой онлайн или запросите счёт." />
    </CdsExpandablePanels>
  </div>
</template>
```

### Layout

The `variant="accordion"` prop removes the spacing and glues the panels into a
single block with shared rounded corners. A list of several questions then reads
as one table instead of a set of cards.

**Example — `Accordion.vue`:**

```vue
<script setup lang="ts">
import { CdsExpandablePanel, CdsExpandablePanels } from '@central-design-system/components';
</script>

<template>
  <CdsExpandablePanels variant="accordion" class="m-auto max-w-[500px]">
    <CdsExpandablePanel
      title="Условия доставки"
      text="Курьер привезёт заказ в течение трёх рабочих дней и позвонит за час до визита."
    />
    <CdsExpandablePanel
      title="Способы оплаты"
      text="Оплатите картой онлайн или запросите счёт — он придёт на почту в течение часа."
    />
    <CdsExpandablePanel
      title="Возврат"
      text="Вернуть товар можно в течение 14 дней после получения, если он не был в использовании."
    />
  </CdsExpandablePanels>
</template>
```

### Expansion

The `multiple` prop allows several panels to stay open at once. Through
`v-model` you read and set what is expanded: the index of the panel (or its
`value`) in the regular mode, and an array in `multiple`. The `mandatory` prop
forbids collapsing the last open panel, and `max` limits how many can be
expanded at the same time.

**Example — `Multiple.vue`:**

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

const opened = ref<number[]>([0]);

const sections = [
  { title: 'Условия доставки', text: 'Курьер привезёт заказ в течение трёх рабочих дней.' },
  { title: 'Способы оплаты', text: 'Оплатите картой онлайн или запросите счёт.' },
  { title: 'Возврат', text: 'Вернуть товар можно в течение 14 дней после получения.' }
];
</script>

<template>
  <div class="m-auto flex max-w-[500px] flex-col gap-2">
    <span class="text-content-secondary">Раскрыты: {{ opened }}</span>

    <CdsExpandablePanels v-model="opened" multiple>
      <CdsExpandablePanel
        v-for="(section, index) in sections"
        :key="index"
        :value="index"
        :title="section.title"
        :text="section.text"
      />
    </CdsExpandablePanels>
  </div>
</template>
```

### States

The `disabled` prop blocks a single panel when set on the panel, and all of them
when set on the group: the title stops responding and loses contrast. The
`readonly` prop leaves the panels in their current state — use it in a view mode
where the content has to be visible but there is nothing to toggle.

**Example — `Disabled.vue`:**

```vue
<script setup lang="ts">
import { CdsExpandablePanel, CdsExpandablePanels } from '@central-design-system/components';

const text = 'Курьер привезёт заказ в течение трёх рабочих дней и позвонит за час до визита.';
</script>

<template>
  <div class="m-auto flex max-w-[500px] flex-col gap-4">
    <CdsExpandablePanels>
      <CdsExpandablePanel title="Доступная панель" :text="text" />
      <CdsExpandablePanel disabled title="Заблокированная панель" :text="text" />
    </CdsExpandablePanels>

    <CdsExpandablePanels disabled>
      <CdsExpandablePanel title="Вся группа заблокирована" :text="text" />
      <CdsExpandablePanel title="Способы оплаты" text="Оплатите картой онлайн или запросите счёт." />
    </CdsExpandablePanels>

    <CdsExpandablePanels readonly :model-value="0">
      <CdsExpandablePanel title="Только для чтения — панель раскрыта и не сворачивается" :text="text" />
    </CdsExpandablePanels>
  </div>
</template>
```

### Icons

The state icon comes from the `expand-icon` and `collapse-icon` props — on the
group, on the panel or on an individual title; the value from the closest level
wins. The `action` slot of the title replaces the icon entirely and receives the
state of the panel, and `hide-actions` removes it altogether.

**Example — `Icon.vue`:**

```vue
<script setup lang="ts">
import {
  CdsExpandablePanel,
  CdsExpandablePanels,
  CdsExpandablePanelTitle,
  CdsIcon
} from '@central-design-system/components';

const text = 'Курьер привезёт заказ в течение трёх рабочих дней и позвонит за час до визита.';
</script>

<template>
  <CdsExpandablePanels class="m-auto max-w-[500px]">
    <CdsExpandablePanel title="Иконки на панели" expand-icon="add" collapse-icon="minus" :text="text" />

    <CdsExpandablePanel :text="text">
      <CdsExpandablePanelTitle expand-icon="chevron-right" collapse-icon="chevron-down">
        Иконки на заголовке
      </CdsExpandablePanelTitle>
    </CdsExpandablePanel>

    <CdsExpandablePanel :text="text">
      <CdsExpandablePanelTitle>
        Своя разметка в слоте action

        <template #action="{ expanded }">
          <CdsIcon :name="expanded ? 'visibility-off' : 'visibility'" />
        </template>
      </CdsExpandablePanelTitle>
    </CdsExpandablePanel>

    <CdsExpandablePanel hide-actions title="Без иконки" :text="text" />
  </CdsExpandablePanels>
</template>
```

### Slots

The `title` and `text` props are enough for a text panel. As soon as the title
needs a counter, a status or an icon, assemble it from
`CdsExpandablePanelTitle` and `CdsExpandablePanelContent`.

| Slot                                  | Description                                                            |
| ------------------------------------- | ---------------------------------------------------------------------- |
| `CdsExpandablePanels` → `default`     | Panels of the group. Slot props carry the `next` and `prev` navigation |
| `CdsExpandablePanel` → `title`        | Title content. Replaces the text from `title`                          |
| `CdsExpandablePanel` → `text`         | Expandable content. Replaces the text from `text`                      |
| `CdsExpandablePanelTitle` → `default` | Title content. Slot props: `expanded`, `disabled`, `readonly`          |
| `CdsExpandablePanelTitle` → `action`  | Expansion icon. Slot props: the same panel state                       |

**Example — `Slots.vue`:**

```vue
<script setup lang="ts">
import {
  CdsBadge,
  CdsExpandablePanel,
  CdsExpandablePanelContent,
  CdsExpandablePanels,
  CdsExpandablePanelTitle,
  CdsIcon,
  CdsLink,
  CdsTag
} from '@central-design-system/components';
</script>

<template>
  <CdsExpandablePanels class="m-auto max-w-[500px]">
    <CdsExpandablePanel>
      <CdsExpandablePanelTitle>
        <div class="flex w-full items-center gap-1">
          <CdsIcon name="file" />
          <span>Документы</span>
          <CdsBadge inline :content="12" />
        </div>
      </CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <div class="flex flex-col gap-1">
          <CdsLink href="#" text="Договор поставки.pdf" />
          <CdsLink href="#" text="Спецификация.xlsx" />
        </div>
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>

    <CdsExpandablePanel>
      <CdsExpandablePanelTitle>
        <template #default="{ expanded }">
          <div class="flex flex-col gap-0.5">
            <span>Статус заявки</span>
            <span v-if="!expanded" class="text-content-secondary">На согласовании у трёх участников</span>
          </div>
        </template>
      </CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <div class="flex flex-wrap gap-1">
          <CdsTag text="Иванов — согласовано" />
          <CdsTag text="Петрова — в работе" />
          <CdsTag text="Сидоров — ждёт" />
        </div>
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>
  </CdsExpandablePanels>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The title names the content — you can tell what is inside before opening it. | «Section 1» and «More» promise nothing: people open the panels at random. |
| Hide the secondary things behind a panel. Required fields stay in plain sight. | Hidden required fields are easy to miss — the form gets submitted with an error. |
| One level of panels: all the sections are visible at once. | A panel inside a panel buries the content two clicks deep — make a separate section instead. |

## Scenarios

### Questions and answers

The classic case for `accordion`: the whole list of questions stays visible and
an answer opens on click. Only one answer is open at a time, so the reader does
not lose their place in the list. The content renders only after the first
expansion; if the answers have to show up in search results, turn on `eager`.

**Example — `Faq.vue`:**

```vue
<script setup lang="ts">
import { CdsExpandablePanel, CdsExpandablePanels } from '@central-design-system/components';

const questions = [
  {
    title: 'Как оплатить заказ по счёту?',
    text: 'Выберите оплату по счёту при оформлении — документ придёт на почту в течение часа. Заказ уйдёт в работу после поступления денег.'
  },
  {
    title: 'Можно ли изменить состав заказа после оформления?',
    text: 'Пока заказ не передан в доставку, состав можно изменить в личном кабинете. После передачи курьеру изменения принимает только служба поддержки.'
  },
  {
    title: 'Сколько идёт доставка в регионы?',
    text: 'От трёх до семи рабочих дней в зависимости от региона. Точный срок появится на странице заказа после сборки.'
  },
  {
    title: 'Как вернуть товар?',
    text: 'Оставьте заявку на возврат в течение 14 дней после получения. Деньги вернутся тем же способом, которым вы платили.'
  }
];
</script>

<template>
  <CdsExpandablePanels variant="accordion" class="m-auto max-w-[560px]">
    <CdsExpandablePanel
      v-for="question in questions"
      :key="question.title"
      :title="question.title"
      :text="question.text"
    />
  </CdsExpandablePanels>
</template>
```

### Form with a summary

The title shows the current value, and the expanded panel holds the field that
changes it. The `default` slot of the title receives `expanded`, so the caption
can change on the fly. Such a form takes little space and keeps what has already
been filled in visible.

**Example — `TripForm.vue`:**

```vue
<script setup lang="ts">
import {
  CdsDatePicker,
  CdsExpandablePanel,
  CdsExpandablePanelContent,
  CdsExpandablePanels,
  CdsExpandablePanelTitle,
  CdsSelect,
  CdsTextInput
} from '@central-design-system/components';
import { computed, ref, unref } from 'vue';

const name = ref('На Байкал');
const selected = ref('third');
const dateRange = ref({ from: '01.01.2026', to: '10.01.2026' });

const items = ref([
  { title: 'Москва', value: 'first' },
  { title: 'Санкт-Петербург', value: 'second' },
  { title: 'Иркутск', value: 'third' }
]);

const cityName = computed(() => unref(items).find((item) => item.value === unref(selected))?.title);
</script>

<template>
  <CdsExpandablePanels class="m-auto max-w-[500px]">
    <CdsExpandablePanel>
      <CdsExpandablePanelTitle expand-icon="edit" collapse-icon="minus">
        <template #default="{ expanded }">
          <div class="flex flex-col gap-0.5">
            <span>Название путешествия</span>
            <span :class="['text-content-secondary', { italic: expanded }]">{{ name }}</span>
          </div>
        </template>
      </CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <CdsTextInput v-model="name" hide-messages label="Название" placeholder="Введите название" />
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>

    <CdsExpandablePanel>
      <CdsExpandablePanelTitle expand-icon="pin" collapse-icon="minus">
        <template #default="{ expanded }">
          <div class="flex flex-col gap-0.5">
            <span>Город поездки</span>
            <span :class="['text-content-secondary', { italic: expanded }]">{{ cityName }}</span>
          </div>
        </template>
      </CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <CdsSelect v-model="selected" :items="items" placeholder="Выберите город" hide-messages />
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>

    <CdsExpandablePanel>
      <CdsExpandablePanelTitle expand-icon="time" collapse-icon="minus">
        <template #default="{ expanded }">
          <div class="flex flex-col gap-0.5">
            <span>Даты поездки</span>
            <span :class="['text-content-secondary', { italic: expanded }]">
              {{ dateRange.from }}—{{ dateRange.to }}
            </span>
          </div>
        </template>
      </CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <CdsDatePicker v-model="dateRange" range />
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>
  </CdsExpandablePanels>
</template>
```

### Filters in a sidebar

Groups of filters in a side panel: `multiple` keeps the needed sections open,
`transparent` removes the extra background, and a badge in the title shows how
many conditions are selected in a collapsed group.

**Example — `Filters.vue`:**

```vue
<script setup lang="ts">
import {
  CdsBadge,
  CdsCheckbox,
  CdsExpandablePanel,
  CdsExpandablePanelContent,
  CdsExpandablePanels,
  CdsExpandablePanelTitle
} from '@central-design-system/components';
import { computed, ref } from 'vue';

const documents = [
  { name: 'Договор поставки № 14', type: 'Договор', status: 'Подписан' },
  { name: 'Счёт № 209', type: 'Счёт', status: 'Черновик' },
  { name: 'Акт сверки за июнь', type: 'Акт', status: 'Подписан' },
  { name: 'Договор аренды № 7', type: 'Договор', status: 'Черновик' },
  { name: 'Счёт № 218', type: 'Счёт', status: 'Подписан' }
];

const types = ['Договор', 'Счёт', 'Акт'];
const statuses = ['Подписан', 'Черновик'];

const selectedTypes = ref<string[]>(['Договор']);
const selectedStatuses = ref<string[]>([]);

const filtered = computed(() =>
  documents.filter(
    (document) =>
      (!selectedTypes.value.length || selectedTypes.value.includes(document.type)) &&
      (!selectedStatuses.value.length || selectedStatuses.value.includes(document.status))
  )
);
</script>

<template>
  <div class="m-auto flex w-[520px] max-w-full gap-4">
    <CdsExpandablePanels appearance="transparent" multiple :model-value="[0, 1]" class="w-[220px] shrink-0">
      <CdsExpandablePanel>
        <CdsExpandablePanelTitle>
          <div class="flex w-full items-center gap-1">
            <span>Тип</span>
            <CdsBadge v-if="selectedTypes.length" inline :content="selectedTypes.length" />
          </div>
        </CdsExpandablePanelTitle>

        <CdsExpandablePanelContent>
          <div class="flex flex-col gap-1">
            <CdsCheckbox
              v-for="type in types"
              :key="type"
              v-model="selectedTypes"
              :value="type"
              :label="type"
              hide-messages
            />
          </div>
        </CdsExpandablePanelContent>
      </CdsExpandablePanel>

      <CdsExpandablePanel>
        <CdsExpandablePanelTitle>
          <div class="flex w-full items-center gap-1">
            <span>Статус</span>
            <CdsBadge v-if="selectedStatuses.length" inline :content="selectedStatuses.length" />
          </div>
        </CdsExpandablePanelTitle>

        <CdsExpandablePanelContent>
          <div class="flex flex-col gap-1">
            <CdsCheckbox
              v-for="status in statuses"
              :key="status"
              v-model="selectedStatuses"
              :value="status"
              :label="status"
              hide-messages
            />
          </div>
        </CdsExpandablePanelContent>
      </CdsExpandablePanel>
    </CdsExpandablePanels>

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="document in filtered" :key="document.name">{{ document.name }}</li>
      <li v-if="!filtered.length" class="text-content-secondary">Ничего не найдено</li>
    </ul>
  </div>
</template>
```

### Step-by-step filling

The group slot hands over `next` and `prev` — buttons inside a panel move the
reader to the next step, while `mandatory` prevents closing all of the steps at
once. For long wizards with per-step validation take
CdsSteps.

**Example — `Wizard.vue`:**

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

const step = ref(0);

const company = ref('');
const city = ref('first');
const contact = ref('');

const cities = [
  { title: 'Москва', value: 'first' },
  { title: 'Санкт-Петербург', value: 'second' },
  { title: 'Новосибирск', value: 'third' }
];
</script>

<template>
  <CdsExpandablePanels
    v-model="step"
    v-slot="{ next, prev }"
    variant="accordion"
    mandatory
    class="m-auto max-w-[500px]"
  >
    <CdsExpandablePanel>
      <CdsExpandablePanelTitle>Шаг 1. Организация</CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <div class="flex flex-col items-start gap-2">
          <CdsTextInput v-model="company" label="Название организации" hide-messages class="w-full" />
          <CdsButton text="Далее" @click="next" />
        </div>
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>

    <CdsExpandablePanel>
      <CdsExpandablePanelTitle>Шаг 2. Адрес</CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <div class="flex flex-col items-start gap-2">
          <CdsSelect v-model="city" :items="cities" label="Город" hide-messages class="w-full" />

          <div class="flex gap-2">
            <CdsButton appearance="secondary" text="Назад" @click="prev" />
            <CdsButton text="Далее" @click="next" />
          </div>
        </div>
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>

    <CdsExpandablePanel>
      <CdsExpandablePanelTitle>Шаг 3. Контакт</CdsExpandablePanelTitle>

      <CdsExpandablePanelContent>
        <div class="flex flex-col items-start gap-2">
          <CdsTextInput v-model="contact" label="Контактное лицо" hide-messages class="w-full" />

          <div class="flex gap-2">
            <CdsButton appearance="secondary" text="Назад" @click="prev" />
            <CdsButton text="Отправить" />
          </div>
        </div>
      </CdsExpandablePanelContent>
    </CdsExpandablePanel>
  </CdsExpandablePanels>
</template>
```

## API

### CdsExpandablePanel

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `collapseIcon` | `IconValue \| undefined` | `'chevron-up'` | no | Icon shown when the panel is expanded and can be collapsed |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `expandIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon shown when the panel is collapsed and can be expanded |
| `focusable` | `boolean \| undefined` | — | no | Highlights the title with a background on focus |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `hideActions` | `boolean \| undefined` | — | no | Hides the expand/collapse icon |
| `hover` | `boolean \| undefined` | `true` | no | Highlights the title with a background on hover |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `static` | `boolean \| undefined` | — | no | Turns off the animation of the title |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `text` | `string \| undefined` | — | no | Text of the expandable content of the panel |
| `title` | `string \| undefined` | — | no | Text of the panel title |
| `value` | `any` | — | no | Value of the component within the group |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `group:selected` | `[value: { value: boolean; }]` | Fires when the panel is expanded or collapsed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Arbitrary content of the panel. |
| `text` | `any` | Expandable content of the panel. |
| `title` | `any` | Content of the panel title. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isSelected` | `boolean` | The panel is expanded |
| `select` | `(value: boolean) => void` | Expands or collapses the panel |
| `toggle` | `() => void` | Toggles the expansion of the panel |

### CdsExpandablePanelContent

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Expandable content of the panel. |

### CdsExpandablePanels

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appearance` | `"primary" \| "secondary" \| "transparent" \| undefined` | `'primary'` | no | Appearance of the panels |
| `collapseIcon` | `IconValue \| undefined` | `'chevron-up'` | no | Icon shown when the panel is expanded and can be collapsed |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `expandIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon shown when the panel is collapsed and can be expanded |
| `focusable` | `boolean \| undefined` | — | no | Highlights the title with a background on focus |
| `gap` | `string \| number \| undefined` | — | no | Spacing between the panels |
| `hideActions` | `boolean \| undefined` | — | no | Hides the expand/collapse icon |
| `hover` | `boolean \| undefined` | `true` | no | Highlights the title with a background on hover |
| `mandatory` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `static` | `boolean \| undefined` | — | no | Turns off the animation of the title |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `variant` | `"default" \| "accordion" \| undefined` | `'default'` | no | Display variant of the panel group |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: unknown]` | Fires when the set of selected panels changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `CdsExpandablePanelsSlotProps` | Panels of the group. The slot props carry the navigation between panels. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `next` | `() => void` | Expands the next panel |
| `prev` | `() => void` | Expands the previous panel |

### CdsExpandablePanelTitle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `collapseIcon` | `IconValue \| undefined` | `'chevron-up'` | no | Icon shown when the panel is expanded and can be collapsed |
| `expandIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon shown when the panel is collapsed and can be expanded |
| `focusable` | `boolean \| undefined` | — | no | Highlights the title with a background on focus |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `hideActions` | `boolean \| undefined` | — | no | Hides the expand/collapse icon |
| `hover` | `boolean \| undefined` | `true` | no | Highlights the title with a background on hover |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `static` | `boolean \| undefined` | — | no | Turns off the animation of the title |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `action` | `CdsExpandablePanelTitleSlotProps` | Expand/collapse icon. The slot props carry the state of the panel. |
| `default` | `CdsExpandablePanelTitleSlotProps` | Content of the title. The slot props carry the state of the panel. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isSelected` | `boolean` | The panel is expanded |
| `toggle` | `() => void` | Toggles the expansion of the panel |

---

# CdsField

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 33/33 · 41 unit · 4 known bugs · lines 96.4% (v4.0.0-alpha.13) · a11y: 6 axe recommendations (v4.0.0-alpha.11)_

The frame of an input: the background, the border, the focus and error states, the inner icons, the clear button and the loading indicator. You put the control itself into the `default` slot — the text fields, selects and autocompletes of the design system are built on `CdsField`.

**See also:** For regular input take the ready-made fields — CdsTextInput, CdsSelect, CdsTextArea. `CdsField` is needed when your control is not in the library. The label, the description and the messages around the frame are added by CdsInput.

## Anatomy

The `default` slot receives a `props` object — bind it to your control so the
field gets an `id`, a class and the link to the messages. Around the control
`CdsField` lays out the inner icons and the clear button.

## Variations

### Icons

The `prepend-inner-icon` and `append-inner-icon` props put an icon inside the
frame — before and after the control. The same areas are available as the
`prepend-inner` and `append-inner` slots when you need a button rather than an
icon.

**Example — `Icons.vue`:**

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

const query = ref('');
</script>

<template>
  <div class="w-[320px] m-auto">
    <CdsField
      v-slot="{ props: fieldProps, focus, blur }"
      prepend-inner-icon="search"
      append-inner-icon="settings"
      :dirty="!!query"
    >
      <input v-bind="fieldProps" v-model="query" placeholder="Поиск по заявкам" @focus="focus" @blur="blur" />
    </CdsField>
  </div>
</template>
```

### Clearing

The `clearable` prop adds a cross; it shows up when the field is marked `dirty`
and appears on hover or focus. The `persistent-clearable` prop keeps the cross
visible at all times. The value is reset not by the component but by you — in
the `@click:clear` handler.

**Example — `Clearable.vue`:**

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

const onHover = ref('Видна при наведении');
const persistent = ref('Видна всегда');
</script>

<template>
  <div class="flex flex-col gap-2 w-[320px] m-auto">
    <CdsField v-slot="{ props: fieldProps, focus, blur }" clearable :dirty="!!onHover" @click:clear="onHover = ''">
      <input v-bind="fieldProps" v-model="onHover" @focus="focus" @blur="blur" />
    </CdsField>

    <CdsField
      v-slot="{ props: fieldProps, focus, blur }"
      clearable
      persistent-clearable
      :dirty="!!persistent"
      @click:clear="persistent = ''"
    >
      <input v-bind="fieldProps" v-model="persistent" @focus="focus" @blur="blur" />
    </CdsField>
  </div>
</template>
```

### States

The `disabled`, `readonly` and `error` props change the color of the frame and
of the text. Set the state of the control inside separately: `CdsField` draws
the frame but does not control your `input`.

**Example — `States.vue`:**

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

<template>
  <div class="flex flex-col gap-2 w-[320px] m-auto">
    <CdsField v-slot="{ props: fieldProps }">
      <input v-bind="fieldProps" value="Обычное поле" readonly />
    </CdsField>

    <CdsField v-slot="{ props: fieldProps }" disabled>
      <input v-bind="fieldProps" value="Заблокировано" disabled />
    </CdsField>

    <CdsField v-slot="{ props: fieldProps }" readonly>
      <input v-bind="fieldProps" value="Только для чтения" readonly />
    </CdsField>

    <CdsField v-slot="{ props: fieldProps }" error>
      <input v-bind="fieldProps" value="Ошибка" readonly />
    </CdsField>
  </div>
</template>
```

### Loading

The `loading` prop shows a bar under the field. The `circle` value replaces it
with a circular indicator inside the frame — handier when the field waits for a
server response while typing.

**Example — `Loading.vue`:**

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

<template>
  <div class="flex flex-col gap-3 w-[320px] m-auto">
    <CdsField v-slot="{ props: fieldProps }" loading>
      <input v-bind="fieldProps" value="Полоса под полем" readonly />
    </CdsField>

    <CdsField v-slot="{ props: fieldProps }" loading="circle">
      <input v-bind="fieldProps" value="Индикатор внутри поля" readonly />
    </CdsField>
  </div>
</template>
```

### Sizes

The `size` prop changes the height of the frame and its inner paddings. The
default size is `md`.

**Example — `Sizes.vue`:**

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

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
</script>

<template>
  <div class="flex flex-col gap-2 w-[320px] m-auto">
    <CdsField v-for="size of sizes" :key="size" v-slot="{ props: fieldProps }" :size="size">
      <input v-bind="fieldProps" :value="'Размер ' + size" readonly />
    </CdsField>
  </div>
</template>
```

## Scenarios

### A field with tags

The control in the `default` slot is any markup you like, so a set of tags and
an input for a new entry fit inside the frame. The `focus` and `blur` handlers
from the slot turn the highlighting of the frame on, `dirty` shows the cross,
and `@click:clear` empties the list.

**Example — `TagsField.vue`:**

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

const tags = ref(['Канцелярия', 'Мебель']);
const draft = ref('');

function addTag() {
  const value = draft.value.trim();
  if (!value) return;

  tags.value = [...tags.value, value];
  draft.value = '';
}
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsField
      v-slot="{ props: fieldProps, focus, blur }"
      prepend-inner-icon="tree"
      clearable
      :dirty="!!tags.length"
      @click:clear="tags = []"
    >
      <div v-bind="fieldProps">
        <CdsTag
          v-for="tag of tags"
          :key="tag"
          size="sm"
          :text="tag"
          closable
          @click:close="tags = tags.filter((item) => item !== tag)"
        />

        <input
          v-model="draft"
          class="flex-1 min-w-[80px] bg-transparent outline-none"
          placeholder="Добавить категорию"
          @focus="focus"
          @blur="blur"
          @keydown.enter.prevent="addTag"
        />
      </div>
    </CdsField>
  </div>
</template>
```

## API

### CdsField

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the field |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
| `color` | `string \| undefined` | — | no | Component color |
| `details` | `boolean \| undefined` | — | no | Reserves the space for hints and error messages under the field |
| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Error state |
| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Field identifier — the value of the `id` HTML attribute for the inner control |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:clear` | `[e: MouseEvent]` | Click on the clear button (clearable prop) |
| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
| `default` | `CdsFieldSlot` | Content inside the field |
| `loader` | `LoaderSlotProps` | Slot for a custom loader (shown when the loading prop is true). |
| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
| `fieldIconColor` | `string \| undefined` | Icon color |

---

# CdsFileInput

_Category: Controls · since 4.0.0 · status: new_

_Tests: API 81/81 · 106 unit · 4 e2e · 11 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 11 axe recommendations (v4.0.0-alpha.11)_

A file field: the user attaches documents by a click, by dragging or by pasting from the clipboard. Around the native `input type="file"` the component gathers everything a form needs: a label, a description, messages, a counter, clearing and a filter by file types.

**See also:** If you need a prominent upload zone with a list of files, take CdsFileUpload; sending the files to the server is the job of CdsUploader.

## Anatomy

The component is built on the same base as
CdsTextInput: the label, the description, the
messages, validation and the colors work the same way. What the field has of its
own is the upload icon on the left (`prepend-icon`, `upload` by default), the
names of the chosen files instead of the typed text and the file counter in the
bottom block. Clearing (`clearable`) is on out of the box.

## Variations

### Label and hints

`label` names the field, the requirements for the files go into `description`,
and `placeholder` hints that a file can be dragged into the field. A chosen file
is shown by its name.

**Example — `Default.vue`:**

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

const model = ref<File | null>(null);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Документ"
      description="Прикрепите один файл"
      placeholder="Выберите или перетащите файл в поле"
    />
  </div>
</template>
```

### Several files

The `multiple` prop allows choosing several files at once — their names are
listed separated by commas.

**Example — `Multiple.vue`:**

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

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

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Можно выбрать несколько файлов"
      placeholder="Выберите или перетащите файлы в поле"
      multiple
    />
  </div>
</template>
```

### Showing as tags

The `chips` prop shows every file as a separate tag
(CdsTag) — a list of several files reads more easily.

**Example — `Chips.vue`:**

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

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

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Выбранные файлы показываются тегами"
      placeholder="Выберите или перетащите файл в поле"
      multiple
      chips
    />
  </div>
</template>
```

### Size and counter

`show-size` adds the size to the file name, `counter` shows the number and the
total size under the field. Long names are truncated in the middle — the
threshold is set by `truncate-length` (22 characters by default).

**Example — `SizeAndCounter.vue`:**

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

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

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Отображается размер файлов и счётчик"
      placeholder="Выберите или перетащите файл в поле"
      multiple
      show-size
      counter
    />
  </div>
</template>
```

### Filter by type

`filter-by-type` accepts MIME types, wildcard types and extensions separated by
commas (`image/*,.pdf`). The files that do not fit never get into the model — the
`rejected` event reports them: show the user what exactly was rejected and why.

**Example — `FilterByType.vue`:**

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

const files = ref<File[]>([]);
const rejectedMessages = ref<string[]>([]);

// `rejected` срабатывает до обновления модели — флаг защищает свежие
// сообщения от сброса в обработчике update:model-value
let justRejected = false;

function onRejected(rejected: File[]) {
  rejectedMessages.value = rejected.map((file) => `${file.name} — не подходит по формату`);
  justRejected = true;
}

function onUpdate() {
  if (justRejected) {
    justRejected = false;

    return;
  }

  rejectedMessages.value = [];
}
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="files"
      label="Сканы документов"
      description="Только изображения или PDF"
      placeholder="Выберите или перетащите файлы"
      filter-by-type="image/*,.pdf"
      multiple
      :error-messages="rejectedMessages"
      @rejected="onRejected"
      @update:model-value="onUpdate"
    />
  </div>
</template>
```

### States

`disabled` blocks the field, `readonly` lets you look at the selection but not
change it, `loading` shows an indicator — while the files are going to the
server, for example.

**Example — `States.vue`:**

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

const file = ref<File | null>(null);

// Файлы создаются только в браузере — SSR-сборка сайта обходится без File
onMounted(() => {
  file.value = new File([new Uint8Array(240_000)], 'отчёт-за-квартал.pdf', { type: 'application/pdf' });
});
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput label="Disabled" placeholder="Выберите файл" disabled />
    <CdsFileInput :model-value="file" label="Readonly" readonly />
    <CdsFileInput :model-value="file" label="Loading" loading />
  </div>
</template>
```

### Slots

The zones of the field match CdsTextInput:
`prepend` / `append` outside the border, `prepend-inner` / `append-inner` inside
it. The extra `selection` slot replaces the standard list of file names.

| Slot name       | Description                                          |
| :-------------- | :--------------------------------------------------- |
| `label`         | Label content (replaces `label`)                     |
| `description`   | Description content (replaces `description`)         |
| `prepend`       | Element before the field (replaces the upload icon)  |
| `append`        | Element after the field                              |
| `prepend-inner` | Element at the start of the field, inside the border |
| `append-inner`  | Element at the end of the field, inside the border   |
| `selection`     | Your own display of the chosen files                 |
| `clear`         | Your own clear icon (with `clearable`)               |
| `loader`        | Your own loading indicator (with `loading`)          |
| `counter`       | Counter content                                      |
| `details`       | The whole bottom block — messages and counter        |
| `messages`      | Content of the messages block                        |

The `selection` slot receives the truncated file names (`fileNames`) and the
total size (`totalBytes`, `totalBytesReadable`).

**Example — `Selection.vue`:**

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

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

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="files"
      label="Вложения"
      placeholder="Выберите или перетащите файлы"
      multiple
      show-size
      counter
    >
      <template #selection="{ fileNames }">
        <CdsTag v-for="name in fileNames" :key="name" prepend-icon="file" size="sm" :text="name" />
      </template>
    </CdsFileInput>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The file requirements are visible before the choice: the description names the formats and the size limit. | The user learns about the restrictions only from an error after picking a file. |
| Tags and a counter: every file reads separately and the number is visible at once. | Comma-separated names merge together already at three or four files. |
| The error names the reason and suggests what to do. | “Upload error” explains neither what is wrong nor how to fix it. |

## Scenarios

### Submitting a form with attachments

The field takes part in CdsForm validation on a par
with the others: `rules` receive the chosen files — check that the attachments
are there and do not exceed the size limit before sending them to the server.
`chips` and `counter` help the user keep track of the list.

**Example — `AttachmentsForm.vue`:**

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

const valid = ref(false);
const topic = ref('');
const files = ref<File[]>([]);
const loading = ref(false);
const sent = ref(false);

const topicRules = [(value: string) => !!value || 'Укажите тему обращения'];

const fileRules = [
  (value: File[]) => (value?.length ?? 0) > 0 || 'Приложите хотя бы один файл',
  (value: File[]) =>
    (value ?? []).every((file) => file.size <= 10 * 1024 * 1024) || 'Файл больше 10 МБ — сожмите его или разбейте архив'
];

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">
    <CdsTextInput v-model="topic" label="Тема обращения" :rules="topicRules" />

    <CdsFileInput
      v-model="files"
      label="Вложения"
      description="До 10 МБ каждый файл"
      placeholder="Выберите или перетащите файлы"
      :rules="fileRules"
      multiple
      chips
      counter
    />

    <CdsButton type="submit" :loading="loading" text="Отправить обращение" />

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

### An upload button without a field

The `hide-input` prop hides the field, leaving only the clickable icon — handy
for embedding the upload into a toolbar or a comment line. Show the chosen files
next to it yourself: here they are tags with `closable`, and a click on the cross
removes a file from the model.

**Example — `UploadButton.vue`:**

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

const files = ref<File[]>([]);

function removeFile(name: string) {
  files.value = files.value.filter((file) => file.name !== name);
}
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <div class="flex items-center gap-1">
      <span>Прикрепите файлы к комментарию</span>
      <CdsFileInput v-model="files" hide-input hide-details multiple aria-label="Прикрепить файлы" />
    </div>

    <div v-if="files.length" class="flex flex-wrap justify-center gap-1">
      <CdsTag
        v-for="file in files"
        :key="file.name"
        prepend-icon="file"
        :text="file.name"
        closable
        @click:close="removeFile(file.name)"
      />
    </div>
  </div>
</template>
```

### An image preview

`filter-by-type="image/*"` lets images through only, and the preview is built
from the model value through `URL.createObjectURL`. Do not forget to release the
previous URL — otherwise the chosen files pile up in the memory of the tab.

**Example — `ImagePreview.vue`:**

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

const file = ref<File | null>(null);
const previewUrl = ref('');

watch(file, (value) => {
  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);

  previewUrl.value = value ? URL.createObjectURL(value) : '';
});

onBeforeUnmount(() => {
  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);
});
</script>

<template>
  <div class="flex flex-col items-center gap-2 max-w-sm m-auto">
    <CdsFileInput
      v-model="file"
      class="w-full"
      label="Логотип компании"
      description="PNG, JPG или SVG"
      placeholder="Выберите или перетащите изображение"
      filter-by-type="image/*"
    />

    <img v-if="previewUrl" :src="previewUrl" alt="Превью логотипа" class="max-h-40 rounded" />
  </div>
</template>
```

## API

### CdsFileInput

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the field |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `chips` | `boolean \| undefined` | — | no | Show the chosen files as tags (CdsTag) instead of a list of names. |
| `clearable` | `boolean \| undefined` | `true` | no | Shows the clear button |
| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
| `color` | `string \| undefined` | — | no | Component color |
| `counter` | `boolean \| undefined` | — | no | Show a counter of the number (and, with `showSize`, of the total size) of the chosen files. |
| `counterSizeString` | `string \| undefined` | `'$cds.fileInput.counterSize'` | no | Localization key for the text of the counter with the file size. |
| `counterString` | `string \| undefined` | `'$cds.fileInput.counter'` | no | Localization key for the text of the file count counter. |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `filterByType` | `string \| undefined` | — | no | Filtering of files by MIME type or extension (`image/*,.pdf`, for example). The rejected files do not get into the model. |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideInput` | `boolean \| undefined` | — | no | Hide the field, leaving only the prepend icon (to use it as a button, for example). |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `File \| File[] \| null \| undefined` | `(props) => props.multiple ? [] : null` | no | Value of the model: an array of files (with `multiple`), a single file or `null`. |
| `multiple` | `boolean \| undefined` | — | no | Allow selecting several files. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field (while no files are chosen yet). |
| `prependIcon` | `IconValue \| undefined` | `'upload'` | no | Icon in the prepend slot, before the content |
| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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. |
| `showSize` | `boolean \| 1000 \| 1024 \| undefined` | `false` | no | Show the size of the chosen files. A boolean or the base: 1000 (kB) or 1024 (KiB). |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `truncateLength` | `string \| number \| undefined` | `22` | no | Maximum length of a file name before it is truncated (the characters at the start and at the end are kept). |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:control` | `[e: MouseEvent]` | Fires on a click in the main area of the control. |
| `mousedown:control` | `[e: MouseEvent]` | Fires on a mouse button press in the main area of the control. |
| `rejected` | `[files: File[]]` | Fires when some of the files were rejected by the `filterByType` filter. |
| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus. |
| `update:modelValue` | `[value: File \| File[]]` | Fires when the list of the chosen files changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
| `counter` | `CdsCounterSlot` | Slot for a custom counter. |
| `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 |
| `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). |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |
| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |
| `selection` | `CdsFileInputSelectionSlot` | Slot for a custom display of the chosen files. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
| `fieldIconColor` | `string \| undefined` | Icon color |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsFileUpload

_Category: Controls · since 4.0.0 · status: new_

_Tests: API 214/214 · 149 unit · 7 e2e · 18 known bugs · lines 99% (v4.0.0-alpha.13) · a11y: 16 axe recommendations (v4.0.0-alpha.11)_

A file upload zone: it accepts files by dragging, by pasting from the clipboard and through the system dialog, and shows the selection as a list with image previews. Around the zone the component gathers everything a form needs: a label, a description, messages and validation.

**See also:** For a compact file field in a form row use CdsFileInput; sending the files to the server is the job of CdsUploader.

## Anatomy

The frame matches the other form fields
(CdsTextInput): the label, the description, the
messages and validation work the same way. What the component has of its own is
the upload zone with an icon, a title and a browse button, and the list of the
chosen files: every file gets a preview (for images), a name, a size and a remove
button.

## Variations

### Choosing files

The basic case is a single file: drag it into the zone, paste it from the
clipboard or pick it with the button. A repeated choice replaces the file.

**Example — `Default.vue`:**

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

const model = ref<File | null>(null);
</script>

<template>
  <div class="max-w-lg m-auto">
    <CdsFileUpload v-model="model" />
  </div>
</template>
```

The `multiple` prop allows choosing several files — they pile up as a list under
the zone. `clearable` gives every one of them a remove button, `show-size` — the
size.

**Example — `Multiple.vue`:**

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

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

<template>
  <div class="flex flex-col gap-4 max-w-lg m-auto">
    <CdsFileUpload v-model="model" subtitle="Можно выбрать несколько файлов сразу" multiple clearable show-size />

    <p class="text-200 text-content-secondary text-center">Выбрано файлов: {{ model.length }}</p>
  </div>
</template>
```

### Texts and the icon

Every caption of the zone is configurable: `title` — the heading, `subtitle` —
the line with the file requirements (visible with `size` `md` and `lg`),
`browse-text` — the text of the button, `divider-text` — the divider, `icon` —
the icon in the center of the zone.

**Example — `Texts.vue`:**

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

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

<template>
  <div class="max-w-lg m-auto">
    <CdsFileUpload
      v-model="model"
      icon="file-download"
      title="Перетащите сканы документов"
      divider-text="или"
      browse-text="Выберите на компьютере"
      subtitle="PDF или JPG до 10 МБ"
      multiple
    />
  </div>
</template>
```

### Sizes

The `size` prop controls the density of the zone: `md` is the default, `lg` adds
air, and `sm` shrinks the zone to a compact row — the browse button is hidden and
the whole area becomes clickable.

**Example — `Sizes.vue`:**

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

const small = ref<File[]>([]);
const medium = ref<File[]>([]);
const large = ref<File[]>([]);
</script>

<template>
  <div class="flex flex-col gap-6 max-w-lg m-auto">
    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">size="sm" — компактная строка, кликабельна целиком</span>
      <CdsFileUpload v-model="small" size="sm" />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">size="md" — по умолчанию</span>
      <CdsFileUpload v-model="medium" />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">size="lg" — просторная зона</span>
      <CdsFileUpload v-model="large" size="lg" />
    </div>
  </div>
</template>
```

### Layout

`inset-file-list` moves the list of the chosen files inside the zone — the
component does not grow downwards as files are added. `hide-browse` removes the
browse button: the zone is clickable as a whole, but say so in the title.

**Example — `Layout.vue`:**

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

const inset = ref<File[]>([]);
const clickable = ref<File[]>([]);
</script>

<template>
  <div class="flex flex-col gap-6 max-w-lg m-auto">
    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">inset-file-list — список файлов внутри зоны</span>
      <CdsFileUpload v-model="inset" multiple clearable show-size inset-file-list />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">hide-browse — без кнопки, кликабельна вся зона</span>
      <CdsFileUpload v-model="clickable" hide-browse title="Нажмите или перетащите файлы" />
    </div>
  </div>
</template>
```

### States

`disabled` blocks the component, `readonly` keeps the list visible but forbids
changes, `loading` shows an indicator — while the files are going to the server,
for example. `error-messages` puts the zone into the error state and shows the
text under it.

**Example — `States.vue`:**

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

const readonlyFiles = ref<File[]>([]);

// Файлы создаются только в браузере — SSR-сборка сайта обходится без File
onMounted(() => {
  readonlyFiles.value = [new File([new Uint8Array(1_200_000)], 'договор-поставки.pdf', { type: 'application/pdf' })];
});
</script>

<template>
  <div class="flex flex-col gap-6 max-w-lg m-auto">
    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">disabled</span>
      <CdsFileUpload disabled />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">readonly — файлы видны, но изменить их нельзя</span>
      <CdsFileUpload :model-value="readonlyFiles" readonly show-size />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">loading</span>
      <CdsFileUpload loading />
    </div>

    <div class="flex flex-col gap-2">
      <span class="text-200 text-content-secondary">error — обязательное поле</span>
      <CdsFileUpload :error-messages="['Прикрепите хотя бы один файл']" />
    </div>
  </div>
</template>
```

### Filtering by type

`filter-by-type` accepts MIME types, wildcard types and extensions separated by
commas (`image/*,.pdf`). The files that do not fit never get into the model — the
`rejected` event reports them: show the user what exactly was rejected and why.

**Example — `Filter.vue`:**

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

const files = ref<File[]>([]);
const rejectedMessages = ref<string[]>([]);

// `rejected` срабатывает до обновления модели — флаг защищает свежие
// сообщения от сброса в обработчике update:model-value
let justRejected = false;

function onRejected(rejected: File[]) {
  rejectedMessages.value = rejected.map((file) => `${file.name} — не подходит по формату`);
  justRejected = true;
}

function onUpdate() {
  if (justRejected) {
    justRejected = false;

    return;
  }

  rejectedMessages.value = [];
}
</script>

<template>
  <div class="max-w-lg m-auto">
    <CdsFileUpload
      v-model="files"
      title="Перетащите изображения или PDF"
      subtitle="Другие форматы будут отклонены"
      filter-by-type="image/*,.pdf"
      multiple
      clearable
      :error-messages="rejectedMessages"
      @rejected="onRejected"
      @update:model-value="onUpdate"
    />
  </div>
</template>
```

### Slots

The parts of the zone are replaced by the slots of the same name, and `item`
redraws every file in the list: `CdsFileUploadItem` is available inside — it
receives the props of the file automatically, it is enough to pass the handlers
from the slot arguments.

| Slot name                            | Description                                                 |
| :----------------------------------- | :---------------------------------------------------------- |
| `title` / `icon` / `divider`         | The title, the icon and the divider of the zone             |
| `browse`                             | The file browse button (`props` holds the click handler)    |
| `item`                               | An item of the list of the chosen files                     |
| `single`                             | The only file with `inset-file-list` and without `multiple` |
| `default`                            | Your own upload zone as a whole                             |
| `input`                              | The native `input type="file"` for manual placement         |
| `loader`                             | Your own loading indicator (with `loading`)                 |
| `label` / `description` / `messages` | The texts of the frame — as in the other form fields        |

**Example — `Slots.vue`:**

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

const model = ref<File[]>([]);

const extension = (file: File) => file.name.split('.').at(-1)?.toUpperCase() ?? 'ФАЙЛ';
</script>

<template>
  <div class="max-w-lg m-auto">
    <CdsFileUpload v-model="model" multiple clearable show-size>
      <template #item="{ file, props }">
        <CdsFileUploadItem v-bind="props">
          <template #append>
            <CdsTag size="sm" :text="extension(file)" />
          </template>
        </CdsFileUploadItem>
      </template>
    </CdsFileUpload>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The file requirements are visible before the choice: the subtitle names the formats and the size limit. | A filter without an explanation: unsuitable files are rejected and the reason stays invisible to the user. |
| The error names the reason and suggests what to do. | “Error” explains neither what is wrong nor how to fix it. |
| Files of the same kind are collected by one zone with multiple — the user adds everything at once. | A separate zone for every file forces picking them one by one and stretches the form. |

## Scenarios

### Applying for a job

The component takes part in CdsForm validation on a par
with the other fields: `rules` receive the chosen files. Here the résumé is
required and is accepted as a PDF only — `filter-by-type` cuts the foreign
formats off, and the rules insure against an empty submission and a file that is
too heavy.

**Example — `ResumeForm.vue`:**

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

const valid = ref(false);
const name = ref('');
const resume = ref<File>();
const loading = ref(false);
const sent = ref(false);

const nameRules = [(value: string) => !!value || 'Представьтесь, пожалуйста'];

const resumeRules = [
  (value?: File) => !!value || 'Приложите резюме в PDF',
  (value?: File) => !value || value.size <= 10 * 1024 * 1024 || 'Файл больше 10 МБ — сожмите его'
];

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-[400px] m-auto" @submit.prevent="submit">
    <CdsTextInput v-model="name" label="Имя и фамилия" placeholder="Введите ФИО" :rules="nameRules" />

    <CdsFileUpload
      v-model="resume"
      label="Резюме"
      subtitle="PDF до 10 МБ"
      filter-by-type=".pdf"
      :rules="resumeRules"
      clearable
      show-size
    />

    <CdsButton type="submit" :loading="loading" text="Откликнуться" />

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

### An image gallery

`filter-by-type="image/*"` lets images through only — every one of them gets a
preview in the list automatically. `inset-file-list` gathers what was uploaded
inside the zone, and `show-size` helps keep an eye on the volume.

**Example — `ImageGallery.vue`:**

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

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

<template>
  <div class="max-w-lg m-auto">
    <CdsFileUpload
      v-model="images"
      title="Перетащите фотографии"
      subtitle="PNG или JPG — превью появится в списке"
      filter-by-type="image/*"
      multiple
      clearable
      show-size
      inset-file-list
    />
  </div>
</template>
```

### Uploading on selection

The files do not have to wait for the form submission — start the upload right
away: watch the model, turn `loading` on for the duration of the request and
confirm the result through `messages`. The request here is simulated with a
timer.

**Example — `AutoUpload.vue`:**

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

const files = ref<File[]>([]);
const loading = ref(false);
const uploaded = ref(false);

let timer: ReturnType<typeof setTimeout>;

// Имитация запроса: новые файлы «уходят на сервер» полторы секунды
watch(
  () => files.value.length,
  (length, previous) => {
    clearTimeout(timer);
    uploaded.value = false;
    loading.value = false;

    if (length > (previous ?? 0)) {
      loading.value = true;
      timer = setTimeout(() => {
        loading.value = false;
        uploaded.value = true;
      }, 1500);
    }
  }
);
</script>

<template>
  <div class="max-w-lg m-auto">
    <CdsFileUpload
      v-model="files"
      title="Файлы отправятся сразу после выбора"
      :loading="loading"
      :messages="uploaded ? 'Файлы загружены' : undefined"
      multiple
      clearable
      show-size
    />
  </div>
</template>
```

## API

### CdsFileUpload

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `browseText` | `string \| undefined` | `'$cds.fileUpload.browse'` | no | Text of the file browse button. Supports localization keys (`$cds.fileUpload.browse`). |
| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `clearable` | `boolean \| undefined` | — | no | Allows removing the chosen files from the list. |
| `color` | `string \| undefined` | — | no | Component color |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `dividerText` | `string \| undefined` | `'$cds.fileUpload.divider'` | no | Text of the divider between the icon and the file browse button. |
| `error` | `boolean \| undefined` | — | no | Puts the component into the error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `filterByType` | `string \| undefined` | — | no | Filtering of files by MIME type or extension (`image/*,.pdf`, for example). The rejected files do not get into the model. |
| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
| `hideBrowse` | `boolean \| undefined` | — | no | Hides the file browse button — the whole upload zone becomes clickable. |
| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `icon` | `IconValue \| undefined` | `'upload'` | no | Icon in the center of the upload zone. |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `insetFileList` | `boolean \| undefined` | — | no | Shows the list of the chosen files inside the upload zone instead of under it. |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `File \| File[] \| null \| undefined` | `null` | no | The chosen files. An array with `multiple`, a single `File` otherwise. |
| `multiple` | `boolean \| undefined` | — | no | Allows choosing several files. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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. |
| `scrim` | `string \| boolean \| undefined` | `true` | no | Dimming of the upload zone while files are being dragged over it. |
| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of the file. A number sets the base for the human-readable conversion. |
| `size` | `"sm" \| "md" \| "lg" \| undefined` | `'md'` | no | Size of the upload zone. With `sm` the zone is shown as a compact row without the browse button and the divider. |
| `subtitle` | `string \| undefined` | — | no | Subtitle under the file browse button. Shown with `size` `md` and `lg` only. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| undefined` | `'$cds.fileUpload.title'` | no | Title of the upload zone. |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `rejected` | `[files: File[]]` | The files did not pass the `filterByType` filtering. |
| `update:focused` | `[focused: boolean]` | The focus state changed. |
| `update:modelValue` | `[files: File[]]` | The list of the chosen files changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `browse` | `CdsFileUploadBrowseSlot` | The file browse button. |
| `default` | `any` | Fully replaces the upload zone with your own markup. |
| `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` | `any` | Divider between the title and the file browse button. |
| `icon` | `any` | Icon in the center of the upload zone. |
| `input` | `{ inputNode: VNode<RendererNode, RendererElement, { [key: string]: any; }>; }` | The native `input[type=file]`, given out for manual placement in the markup. |
| `item` | `CdsFileUploadFileSlot` | An item of the list of the chosen files. |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
| `loader` | `LoaderSlotProps` | The loading indicator. |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |
| `single` | `CdsFileUploadFileSlot` | The only chosen file with `insetFileList` and without `multiple`. |
| `title` | `any` | Title of the upload zone. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `controlRef` | `HTMLInputElement \| undefined` | Ref to the native `input[type=file]` element — for opening the file dialog programmatically. |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

### CdsFileUploadDropzone

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `browseText` | `string \| undefined` | `'$cds.fileUpload.browse'` | no | Text of the file browse button. Supports localization keys (`$cds.fileUpload.browse`). |
| `clearable` | `boolean \| undefined` | — | no | Allows removing the chosen files from the list. |
| `color` | `string \| undefined` | — | no | Background color of the surface |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `dividerText` | `string \| undefined` | `'$cds.fileUpload.divider'` | no | Text of the divider between the icon and the file browse button. |
| `error` | `boolean \| undefined` | — | no | Shows the upload zone in the error state. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `hideBrowse` | `boolean \| undefined` | — | no | Hides the file browse button — the whole upload zone becomes clickable. |
| `icon` | `IconValue \| undefined` | `'upload'` | no | Icon in the center of the upload zone. |
| `insetFileList` | `boolean \| undefined` | — | no | Shows the list of the chosen files inside the upload zone instead of under it. |
| `length` | `string \| number \| undefined` | `150` | no | Length of the divider. Defaults to pixels. |
| `location` | `Anchor \| null \| undefined` | — | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `File[] \| undefined` | `[]` | no | The list of the chosen files. Used when `CdsFileUploadDropzone` is applied on its own. |
| `multiple` | `boolean \| undefined` | — | no | Allows choosing several files. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the divider. |
| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `scrim` | `string \| boolean \| undefined` | `true` | no | Dimming of the upload zone while files are being dragged over it. |
| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of the file. A number sets the base for the human-readable conversion. |
| `size` | `"sm" \| "md" \| "lg" \| undefined` | `'md'` | no | Size of the upload zone. With `sm` the zone is shown as a compact row without the browse button and the divider. |
| `subtitle` | `string \| undefined` | — | no | Subtitle under the file browse button. Shown with `size` `md` and `lg` only. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `thickness` | `string \| number \| undefined` | — | no | Thickness of the divider. Defaults to pixels. |
| `title` | `string \| undefined` | `'$cds.fileUpload.title'` | no | Title of the upload zone. |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:browse` | `[]` | The file browse button was pressed. |
| `click:remove` | `[index: number]` | Removal of a file by its index was requested. |
| `drop` | `[files: File[]]` | Files were dropped into the upload zone. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `browse` | `CdsFileUploadBrowseSlot` | The file browse button. |
| `default` | `{ isDragging: boolean; hasFiles: boolean; files: readonly File[]; props: { onClick: () => void; }; }` | Fully replaces the content of the upload zone. |
| `divider` | `any` | Divider between the title and the file browse button. |
| `icon` | `any` | Icon in the center of the upload zone. |
| `input` | `any` | The native `input[type=file]`. |
| `item` | `CdsFileUploadFileSlot` | An item of the list of the chosen files inside the upload zone. |
| `loader` | `any` | The loading indicator. |
| `single` | `CdsFileUploadFileSlot` | The only chosen file with `insetFileList` and without `multiple`. |
| `title` | `any` | Title of the upload zone. |

### CdsFileUploadItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Forces the active state of the item |
| `activeClass` | `string \| undefined` | — | no | Class applied to list items when they are in the active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendAvatar` | `string \| undefined` | — | no | Avatar (image URL) shown after the item content |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon shown after the item content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `clearable` | `boolean \| undefined` | — | no | Allows removing the file from the list. |
| `color` | `string \| undefined` | — | no | Component color |
| `description` | `string \| number \| boolean \| undefined` | — | no | Description of the list item shown below the title and the subtitle |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `file` | `File \| undefined` | `null` | no | The file shown by the list item. |
| `fileIcon` | `IconValue \| undefined` | `'file'` | no | Fallback icon for the files that have no preview. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `index` | `number \| undefined` | — | no | Index of the item; used for keyboard navigation |
| `lines` | `false \| "one" \| "two" \| "three" \| undefined` | `'two'` | no | Number of lines in the list items; affects their height. `false` turns off the fixed height |
| `link` | `boolean \| undefined` | — | no | Turns the item into a clickable link. Detected automatically when `href` or `to` is set |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `nav` | `boolean \| undefined` | — | no | Applies navigation list styles (rounded active items) |
| `prependAvatar` | `string \| undefined` | — | no | Avatar (image URL) shown before the item content |
| `prependGap` | `string \| number \| undefined` | — | no | Indent before the item content (reserves space for the prepend icon or avatar) |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon shown before the item content |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of the file instead of its MIME type. |
| `slim` | `boolean \| undefined` | — | no | Removes the inner paddings of the list and of the menu container: the list fills the available area completely |
| `subtitle` | `string \| number \| boolean \| undefined` | — | no | Subtitle of the item shown below the title |
| `tabindex` | `string \| number \| undefined` | — | no | Value of the element `tabindex` attribute |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| number \| boolean \| undefined` | — | no | Title of the item shown in the component |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `value` | `any` | — | no | Value of the item used for selection and activation in the list |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click` | `[event: MouseEvent \| KeyboardEvent]` | A click on the list item. |
| `click:remove` | `[]` | Removal of the file was requested. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `ListItemSlot` | Content after the item text (in place of the append icon or avatar) |
| `clear` | `{ props: { onClick: () => void; }; }` | The file removal button. |
| `default` | `ListItemSlot` | Default content inside the item |
| `description` | `ListItemDescriptionSlot` | Content of the item description (shown below the title and the subtitle) |
| `prepend` | `ListItemSlot` | Content before the item text (in place of the prepend icon or avatar) |
| `subtitle` | `ListItemSubtitleSlot` | Content of the item subtitle |
| `title` | `ListItemTitleSlot` | Content of the item title |

### CdsFileUploadList

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activatable` | `boolean \| undefined` | — | no | Allows items to be activated (highlighting the current item without selection mode) |
| `activated` | `any` | — | no | Identifiers of the active items (supports v-model through `update:activated`) |
| `activeClass` | `string \| undefined` | — | no | Class applied to list items when they are in the active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `activeStrategy` | `ActiveStrategyProp \| undefined` | — | no | Activation strategy for items (single, multiple, and so on) |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `clearable` | `boolean \| undefined` | — | no | Allows removing files from the list. |
| `collapseIcon` | `IconValue \| undefined` | — | no | Icon shown on a collapsed group |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `expandIcon` | `IconValue \| undefined` | — | no | Icon shown on an expanded group |
| `files` | `File[] \| undefined` | — | no | The list of files. Taken from the `CdsFileUpload` context by default. |
| `filterable` | `boolean \| undefined` | — | no | **FOR INTERNAL USE ONLY** Turns on filtering mode: the space key does not select an item but is used for typing. Applies to the CdsCombobox and CdsAutocomplete components |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `indent` | `string \| number \| undefined` | — | no | Indent size for nested item groups |
| `itemChildren` | `SelectItemKey` | `'children'` | no | Object field that holds the child items, or a function that returns them |
| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
| `itemsRegistration` | `ItemsRegistrationType \| undefined` | `'render'` | no | Item registration strategy: `render` — as they are rendered, otherwise all at once |
| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
| `itemType` | `SelectItemKey` | `'type'` | no | Object field that defines the item type (`item`, `divider`, `subheader`), or a function that returns it |
| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
| `lines` | `false \| "one" \| "two" \| "three" \| undefined` | `false` | no | Number of lines in the list items; affects their height. `false` turns off the fixed height |
| `mandatory` | `boolean \| undefined` | — | no | Makes the selection mandatory: forbids clearing the selection of the last item |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `nav` | `boolean \| undefined` | — | no | Applies navigation list styles (rounded active items) |
| `navigationIndex` | `number \| undefined` | — | no | Index of the current item during keyboard navigation (supports v-model) |
| `navigationStrategy` | `"focus" \| "track" \| undefined` | `'focus'` | no | Keyboard navigation strategy: `focus` — moves the focus, `track` — a virtual cursor |
| `opened` | `any` | — | no | Identifiers of the expanded groups (supports v-model through `update:opened`) |
| `openStrategy` | `OpenStrategyProp \| undefined` | `'list'` | no | Expansion strategy for groups (`list`, `single`, `multiple`) |
| `prependGap` | `string \| number \| undefined` | — | no | Indent before the item content (reserves space for the prepend icon or avatar) |
| `required` | `boolean \| undefined` | — | no | Makes the selection mandatory: forbids clearing the selection of the last item |
| `returnObject` | `boolean \| undefined` | — | no | Return an object in the model value instead of an array |
| `selectable` | `boolean \| undefined` | — | no | Allows items to be selected |
| `selected` | `any` | — | no | Identifiers of the selected items (supports v-model through `update:selected`) |
| `selectStrategy` | `SelectStrategyProp \| undefined` | `'single-leaf'` | no | Selection strategy for items (`single-leaf`, `leaf`, `independent`, `classic`, and so on) |
| `showSize` | `ShowSize \| undefined` | `false` | no | Shows the size of every file. |
| `slim` | `boolean \| undefined` | — | no | Removes the inner paddings of the list and of the menu container: the list fills the available area completely |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ files: readonly File[]; onClickRemove: (index: number) => void; }` | Fully replaces the content of the list. |
| `item` | `CdsFileUploadFileSlot` | An item of the list. |

---

# CdsFooter

_Category: Layouts · since 4.0.0_

_Tests: API 12/12 · 21 unit · 1 known bug · lines 96.7% (v4.0.0-alpha.13) · a11y: 6 axe recommendations (v4.0.0-alpha.11)_

The footer of the application: a copyright notice and utility links on regular pages, an action bar on forms. The layout measures the height of the footer and reserves the space, so it never covers the last line of the content.

**See also:** The footer works only inside CdsLayout — outside the layout it renders nothing and warns about it in the console. The top bar of the application is built by CdsHeader, and the content of both by CdsToolbar.

## Variations

### Separator

The footer is pinned to the bottom edge and overlaps the content, so its border
is worth marking: `bordered` draws a line, `elevated` casts a shadow upwards.
The shadow matters more when a long list continues under the footer.

**Example — `Separators.vue`:**

```vue
<script setup lang="ts">
import { CdsFooter, CdsLayout, CdsMain, CdsPage, CdsRadio, CdsRadioGroup } from '@central-design-system/components';
import { ref } from 'vue';

const separator = ref('bordered');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="separator" direction="horizontal" hide-details>
      <CdsRadio value="none" label="Без разделителя" />
      <CdsRadio value="bordered" label="Граница" />
      <CdsRadio value="elevated" label="Тень" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsMain>
          <CdsPage padding>
            <div class="flex flex-col gap-2">
              <div v-for="n in 6" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Блок {{ n }}
              </div>
            </div>
          </CdsPage>
        </CdsMain>

        <CdsFooter :bordered="separator === 'bordered'" :elevated="separator === 'elevated'">
          <div class="flex h-[48px] items-center px-4 text-content-secondary">© 2026 Портал закупок</div>
        </CdsFooter>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Color

The `bg-color` prop paints the background of the footer with a palette alias,
`color` paints the text and the icons inside. If only the background is set, the
text color is picked to be contrasting automatically.

**Example — `Colors.vue`:**

```vue
<script setup lang="ts">
import { CdsFooter, CdsLayout, CdsMain, CdsPage, CdsRadio, CdsRadioGroup } from '@central-design-system/components';
import { ref } from 'vue';

const bgColor = ref('default');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="bgColor" direction="horizontal" hide-details>
      <CdsRadio value="default" label="Цвет темы" />
      <CdsRadio value="neutral" label="neutral" />
      <CdsRadio value="indigo" label="indigo" />
      <CdsRadio value="teal" label="teal" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
          </CdsPage>
        </CdsMain>

        <CdsFooter :bg-color="bgColor === 'default' ? undefined : bgColor">
          <div class="flex h-[48px] items-center px-4">© 2026 Портал закупок</div>
        </CdsFooter>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Floating mode

The `reveal` prop hides the footer when scrolling down and brings it back when
scrolling up. The `@reveal` event reports the change of visibility — to adjust a
selection counter, for example.

**Example — `Reveal.vue`:**

```vue
<script setup lang="ts">
import { CdsFooter, CdsLayout, CdsMain, CdsPage } from '@central-design-system/components';
import { ref } from 'vue';

const revealed = ref(true);
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsMain>
        <CdsPage padding>
          <div class="mb-2 text-content-secondary">Подвал сейчас {{ revealed ? 'виден' : 'скрыт' }}</div>
          <div class="flex flex-col gap-2">
            <div v-for="n in 20" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Блок {{ n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>

      <CdsFooter reveal elevated @reveal="revealed = $event">
        <div class="flex h-[48px] items-center px-4 text-content-secondary">Выбрано 0 из 20</div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

### Visibility

The `model-value` prop removes the footer entirely: the layout stops reserving
space for it, and the content takes the full height. This is how you hide an
action bar until the form has changed.

**Example — `Visibility.vue`:**

```vue
<script setup lang="ts">
import { CdsFooter, CdsLayout, CdsMain, CdsPage } from '@central-design-system/components';
</script>

<template>
  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Подвал виден</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Контент страницы</div>
            </CdsPage>
          </CdsMain>

          <CdsFooter bordered>
            <div class="flex h-[48px] items-center px-4 text-content-secondary">© 2026 Портал закупок</div>
          </CdsFooter>
        </CdsLayout>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">:model-value="false"</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Подвал скрыт — контент занимает всю высоту
              </div>
            </CdsPage>
          </CdsMain>

          <CdsFooter :model-value="false" bordered>
            <div class="flex h-[48px] items-center px-4 text-content-secondary">© 2026 Портал закупок</div>
          </CdsFooter>
        </CdsLayout>
      </div>
    </div>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The footer is pinned to the bottom and keeps the form actions at hand at any scroll position. | Actions at the end of a long page have to be found by scrolling. |
| The footer holds the utility links and the copyright: that is where people look for them. | Section navigation in the footer duplicates the side drawer and confuses the reader. |

## Scenarios

### Site footer

The copyright on the left, the utility links on the right — the familiar layout
people look for at the bottom of a page. The height comes from the content, and
`height` tells the layout the expected value before the first measurement.

**Example — `PageFooter.vue`:**

```vue
<script setup lang="ts">
import { CdsFooter, CdsLayout, CdsLink, CdsMain, CdsPage } from '@central-design-system/components';
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
        </CdsPage>
      </CdsMain>

      <CdsFooter bordered :height="56">
        <div class="flex h-[56px] flex-wrap items-center justify-between gap-2 px-4">
          <span class="text-content-secondary">© 2026 Портал закупок</span>
          <span class="flex items-center gap-4">
            <CdsLink href="#">Помощь</CdsLink>
            <CdsLink href="#">Конфиденциальность</CdsLink>
            <CdsLink href="#">Контакты</CdsLink>
          </span>
        </div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

### Form action bar

On a long form the "Cancel" and "Publish" buttons live in the footer: they are
visible at any scroll position and need no reaching for. `CdsToolbarTitle`
stretches and pushes the buttons to the right edge, and `elevated` separates the
bar from the fields.

**Example — `FormActions.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsFooter,
  CdsForm,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsTextArea,
  CdsTextInput,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const saving = ref(false);

function save() {
  saving.value = true;
  setTimeout(() => {
    saving.value = false;
  }, 1500);
}
</script>

<template>
  <div class="h-[360px]">
    <CdsLayout container>
      <CdsMain>
        <CdsPage padding>
          <CdsForm class="flex flex-col gap-2">
            <CdsTextInput label="Название закупки" />
            <CdsTextInput label="Заказчик" />
            <CdsTextArea label="Описание" :rows="6" />
            <CdsTextInput label="Контактное лицо" />
            <CdsTextInput label="Телефон" />
          </CdsForm>
        </CdsPage>
      </CdsMain>

      <CdsFooter elevated :height="56">
        <CdsToolbar class="h-[56px] gap-2">
          <CdsToolbarTitle class="text-content-secondary">Черновик сохраняется автоматически</CdsToolbarTitle>
          <CdsButton variant="soft" color="neutral">Отмена</CdsButton>
          <CdsButton :loading="saving" @click="save">Опубликовать</CdsButton>
        </CdsToolbar>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsFooter

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `bordered` | `boolean \| undefined` | `false` | no | Shows the border. |
| `color` | `string \| undefined` | — | no | Component color |
| `elevated` | `boolean \| undefined` | `false` | no | Shows the shadow. |
| `height` | `string \| number \| undefined` | `50` | no | Height of the element. |
| `modelValue` | `boolean \| undefined` | `true` | no | Visibility of the element in the layout. |
| `reveal` | `boolean \| undefined` | `false` | no | Floating mode: the element appears/hides on scroll. |
| `revealOffset` | `number \| undefined` | `250` | no | Scroll threshold (px) up to which the floating element stays visible. |
| `theme` | `string \| undefined` | — | no | Component theme |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `focusin` | `[event: FocusEvent]` | Focus moved inside the footer. |
| `reveal` | `[value: boolean]` | Visibility of the floating footer has changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the footer (`CdsToolbar` and others). |

---

# CdsForm

_Category: Controls · since 4.0.0_

_Tests: API 20/20 · 36 unit · 2 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 10 axe recommendations (v4.0.0-alpha.11)_

A form joins fields into one group: it collects their validation into a common status, intercepts the submission and can reset the values. CDS fields with the `rules` prop connect to the form automatically — with no registration and no extra code.

**See also:** The form does not render the fields itself — build them out of CdsTextInput, CdsSelect, CdsCheckbox and other controls. The validation rules are declared on the fields themselves through the `rules` prop.

## Anatomy

The form is a native `form` with an optional header: the heading and the
description are rendered above the content, and the fields from the default slot
stay as they are. The heading is bound to the form through `aria-labelledby`, the
description — through `aria-describedby`.

## Variations

### Heading and description

The `label` prop names the form, `description` adds an explanation under the
heading. The slots of the same name accept arbitrary markup.

**Example — `LabelAndDescription.vue`:**

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

<template>
  <CdsForm
    label="Адрес доставки"
    description="Привезём заказ по этому адресу"
    class="flex flex-col gap-2 w-[350px] m-auto"
  >
    <CdsTextInput label="Город" placeholder="Москва" />
    <CdsTextInput label="Улица и дом" placeholder="Тверская, 1" />
  </CdsForm>
</template>
```

### Validity status

The `v-model` of the form is the common status of its fields: `null` while the
form has not been checked, `false` on errors and `true` when all the fields are
valid. The status is updated on the fly — it is handy for blocking the submit
button, for example.

**Example — `ValidStatus.vue`:**

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

const valid = ref<boolean | null>(null);
const login = ref('');
const password = ref('');

const rules = {
  login: [(value: string) => !!value || 'Введите логин'],
  password: [(value: string) => value.length >= 8 || 'Минимум 8 символов']
};
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
    <CdsTextInput v-model="login" :rules="rules.login" label="Логин" placeholder="Введите логин" />
    <CdsTextInput
      v-model="password"
      :rules="rules.password"
      type="password"
      label="Пароль"
      placeholder="Минимум 8 символов"
    />
    <div class="mt-2">
      <CdsButton :disabled="!valid" type="submit" block>Войти</CdsButton>
    </div>
  </CdsForm>
</template>
```

### The moment of validation

The `validate-on` prop sets the moment the check runs for all the fields of the
form; the field's own `validate-on` takes precedence. Switch the mode and try it
out: with `input` (the default) the error appears as you type, with `blur` —
after leaving the field, with `submit` — only when the form is submitted.

**Example — `ValidateOn.vue`:**

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

const mode = ref<'input' | 'blur' | 'submit'>('input');
const formRef = ref<InstanceType<typeof CdsForm>>();

const name = ref('');
const email = ref('');

const rules = {
  name: [(value: string) => !!value || 'Обязательное поле'],
  email: [(value: string) => /.+@.+\..+/.test(value) || 'Некорректная почта']
};

watch(mode, () => unref(formRef)?.resetValidation());
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <div class="flex items-center justify-between">
      <span class="text-sm text-content-secondary">validate-on</span>
      <CdsButtonToggle v-model="mode" mandatory variant="soft" color="neutral" size="sm">
        <CdsButton text="input" value="input" />
        <CdsButton text="blur" value="blur" />
        <CdsButton text="submit" value="submit" />
      </CdsButtonToggle>
    </div>

    <CdsForm ref="formRef" :validate-on="mode" class="flex flex-col gap-2" @submit.prevent>
      <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
      <CdsTextInput v-model="email" :rules="rules.email" label="Электронная почта" placeholder="name@company.ru" />
      <div class="mt-2">
        <CdsButton type="submit">Отправить</CdsButton>
      </div>
    </CdsForm>
  </div>
</template>
```

### Fast validation

The `first-fail` prop stops the check at the first invalid field. Submit the
form: the error is shown only for "Имя", although "Фамилия" is invalid too.

**Example — `FastValidation.vue`:**

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

const firstName = ref('');
const lastName = ref('1020');

const rules = {
  firstName: [(value: string) => value.length >= 3 || 'Имя не короче 3 символов'],
  lastName: [(value: string) => !/\d/.test(value) || 'Фамилия не может содержать цифры']
};
</script>

<template>
  <CdsForm first-fail class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
    <CdsTextInput v-model="firstName" :rules="rules.firstName" label="Имя" placeholder="Введите имя" />
    <CdsTextInput v-model="lastName" :rules="rules.lastName" label="Фамилия" placeholder="Введите фамилию" />
    <div class="mt-2">
      <CdsButton type="submit">Отправить</CdsButton>
    </div>
  </CdsForm>
</template>
```

### States

`disabled` blocks all the fields of the form at once, `readonly` keeps the values
visible and copyable but forbids changing them. There is no need to configure the
individual fields — the state is inherited.

**Example — `DisabledAndReadonly.vue`:**

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

<template>
  <div class="flex flex-col gap-4 w-[350px] m-auto">
    <CdsForm disabled label="Недоступная форма" class="flex flex-col gap-2">
      <CdsTextInput label="Имя" value="Анна Смирнова" />
      <CdsTextInput label="Электронная почта" value="anna@company.ru" />
    </CdsForm>
    <CdsForm readonly label="Только для чтения" class="flex flex-col gap-2">
      <CdsTextInput label="Имя" value="Анна Смирнова" />
      <CdsTextInput label="Электронная почта" value="anna@company.ru" />
    </CdsForm>
  </div>
</template>
```

### Hiding the details

The bottom block with the messages is controlled by the `hide-details` prop on
the fields themselves: `true` always hides the block — errors included, `false`
always reserves space for it, `auto` shows the block only when there is something
to show. In dense forms use `auto`: the fields sit right next to each other, but
the validation errors are not lost. Switch the value and submit an empty form.

**Example — `HideDetails.vue`:**

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

const mode = ref('auto');
const hideDetails = computed(() => (mode.value === 'auto' ? ('auto' as const) : mode.value === 'true'));

const rules = {
  login: [(value: string) => !!value || 'Логин не может быть пустым'],
  password: [(value: string) => !!value || 'Пароль не может быть пустым']
};
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <div class="flex items-center justify-between">
      <span class="text-sm text-content-secondary">hide-details</span>
      <CdsButtonToggle v-model="mode" mandatory variant="soft" color="neutral" size="sm">
        <CdsButton text="auto" value="auto" />
        <CdsButton text="true" value="true" />
        <CdsButton text="false" value="false" />
      </CdsButtonToggle>
    </div>

    <CdsForm class="flex flex-col gap-2" @submit.prevent>
      <template #default="{ reset }">
        <CdsTextInput
          :hide-details="hideDetails"
          :rules="rules.login"
          label="Логин"
          placeholder="Введите логин"
          clearable
        />
        <CdsTextInput
          :hide-details="hideDetails"
          :rules="rules.password"
          type="password"
          label="Пароль"
          placeholder="Введите пароль"
        />
        <div class="flex gap-2 mt-2 justify-end">
          <CdsButton variant="soft" color="neutral" @click="reset">Сбросить</CdsButton>
          <CdsButton type="submit">Отправить</CdsButton>
        </div>
      </template>
    </CdsForm>
  </div>
</template>
```

### Slots

The default slot receives the state of the form and the control methods — the
"Check" and "Reset" buttons are built without a ref to the component.

| Slot name     | Description                                                                                           |
| :------------ | :---------------------------------------------------------------------------------------------------- |
| `label`       | Heading content (replaces `label`)                                                                    |
| `description` | Description content (replaces `description`)                                                          |
| `default`     | Form content; slot props: `isValid`, `errors`, `isValidating`, `validate`, `reset`, `resetValidation` |

**Example — `Slots.vue`:**

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

const valid = ref<boolean | null>(null);
const value = ref('');

const rules = [(input: string) => !!input || 'Не может быть пустым'];
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent>
    <template #default="{ isValid, validate, reset, resetValidation }">
      <CdsTextInput v-model="value" :rules="rules" label="Поле" placeholder="Введите текст" />
      <div class="text-sm text-content-secondary">
        Статус формы: {{ isValid === null ? 'не проверена' : isValid ? 'валидна' : 'есть ошибки' }}
      </div>
      <div class="flex flex-wrap gap-2 mt-2">
        <CdsButton @click="validate">Проверить</CdsButton>
        <CdsButton variant="soft" color="brand" @click="reset">Сброс</CdsButton>
        <CdsButton variant="soft" color="neutral" @click="resetValidation">Сброс валидации</CdsButton>
      </div>
    </template>
  </CdsForm>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The heading and the description explain what the form is and what happens after submission. | A set of fields without context makes the user guess why they are filling them in. |
| Show an error after the input or on submission — while a field is untouched the form stays silent. | A form that complains before the user's first action looks broken. |
| The submit button names the action — it is clear what happens after the click. | A faceless “OK” says nothing about what the form will do. |

## Scenarios

### Submitting a form

The `submit` event is a Promise: `await event` returns the validation result, and
the handler decides on its own whether to send the data. The `.prevent` modifier
turns off the native page submission. The request here is simulated with
`setTimeout`, and the button shows `loading` for the duration of the "request".

**Example — `SubmitForm.vue`:**

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

const name = ref('');
const email = ref('');
const loading = ref(false);
const sent = ref(false);

const rules = {
  name: [(value: string) => !!value || 'Введите имя'],
  email: [(value: string) => /.+@.+\..+/.test(value) || 'Некорректная почта']
};

async function onSubmit(event: SubmitEventPromise) {
  sent.value = false;

  const { valid } = await event;

  if (!valid) return;

  loading.value = true;

  setTimeout(() => {
    loading.value = false;
    sent.value = true;
  }, 1500);
}
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="onSubmit">
    <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
    <CdsTextInput v-model="email" :rules="rules.email" label="Электронная почта" placeholder="name@company.ru" />
    <div class="mt-2">
      <CdsButton :loading="loading" type="submit">Отправить заявку</CdsButton>
    </div>
    <div v-if="sent" class="text-sm text-content-secondary">Заявка отправлена — мы напишем вам на почту.</div>
  </CdsForm>
</template>
```

### Control from outside

The `validate`, `reset` and `resetValidation` methods are also available through
a ref to the form. That is how the form is driven from outside — from the footer
of a modal or a wizard panel, where the buttons live outside the form markup.

**Example — `RefControl.vue`:**

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

const formRef = ref<InstanceType<typeof CdsForm>>();

const name = ref('');
const agree = ref(false);
const result = ref('');

const rules = {
  name: [(value: string) => !!value || 'Введите имя'],
  agree: [(value: boolean) => !!value || 'Нужно согласие, чтобы продолжить']
};

async function validate() {
  const form = unref(formRef);

  if (!form) return;

  const { valid } = await form.validate();

  result.value = valid ? 'Форма валидна' : 'В форме есть ошибки';
}

function reset() {
  unref(formRef)?.reset();
  result.value = '';
}

function resetValidation() {
  unref(formRef)?.resetValidation();
  result.value = '';
}
</script>

<template>
  <div class="flex flex-col gap-2 w-[380px] m-auto">
    <CdsForm ref="formRef" class="flex flex-col gap-2">
      <CdsTextInput v-model="name" :rules="rules.name" label="Имя" placeholder="Введите имя" />
      <CdsCheckbox v-model="agree" :rules="rules.agree" label="Согласен с условиями" />
    </CdsForm>
    <div class="flex flex-wrap gap-2">
      <CdsButton @click="validate">Проверить</CdsButton>
      <CdsButton variant="soft" color="brand" @click="reset">Сбросить</CdsButton>
      <CdsButton variant="soft" color="neutral" @click="resetValidation">Сбросить валидацию</CdsButton>
    </div>
    <div v-if="result" class="text-sm text-content-secondary">{{ result }}</div>
  </div>
</template>
```

### Vee-validate

The form gets along with external validation libraries. With
[vee-validate](https://vee-validate.logaretm.com/v4/) the schema is set in
`useForm`, and the error messages of the fields are passed into `error-messages`.

**Example — `VeeValidate.vue`:**

```vue
<script setup lang="ts">
import { CdsButton, CdsCheckbox, CdsForm, CdsTextInput } from '@central-design-system/components';
import { useField, useForm } from 'vee-validate';
import { ref } from 'vue';

const { handleSubmit, handleReset } = useForm({
  validationSchema: {
    name(value: string) {
      if (!value) return 'Обязательно для заполнения';
      if (value.length < 3) return 'Минимальное кол-во символов 3';
      if (value.length > 10) return 'Максимальное кол-во символов 10';
      return true;
    },
    phone(value: string) {
      if (!value) return 'Обязательно для заполнения';
      if (value.length < 8) return 'Минимальное кол-во символов 8';
      if (value.length > 9) return 'Максимальное кол-во символов 9';
      return true;
    },
    email(value: string) {
      if (!value) return 'Обязательно для заполнения';
      if (!/^[a-z.-]+@[a-z.-]+\.[a-z]+$/i.test(value)) return 'Некорректный E-mail';
      return true;
    },
    checkbox(value: boolean) {
      if (!value) return 'Обязательно для заполнения';
      return true;
    }
  }
});

const name = useField('name');
const phone = useField('phone');
const email = useField('email');
const checkbox = useField('checkbox');

const result = ref('');

const submit = handleSubmit((values) => {
  result.value = `Отправлено: ${JSON.stringify(values)}`;
});

const clear = () => {
  handleReset();
  result.value = '';
};
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsTextInput
      v-model="name.value.value"
      :error-messages="name.errorMessage.value"
      label="Имя"
      placeholder="Введите имя"
    />
    <CdsTextInput
      v-model="phone.value.value"
      :error-messages="phone.errorMessage.value"
      label="Номер телефона"
      placeholder="Введите номер"
    />
    <CdsTextInput
      v-model="email.value.value"
      :error-messages="email.errorMessage.value"
      label="E-mail"
      placeholder="Введите E-mail"
    />
    <CdsCheckbox
      v-model="checkbox.value.value"
      :error-messages="checkbox.errorMessage.value"
      value="1"
      label="Согласен с условиями"
    />
    <div class="flex gap-2">
      <CdsButton type="submit">Отправить</CdsButton>
      <CdsButton variant="soft" color="brand" @click="clear">Очистить</CdsButton>
    </div>
    <div v-if="result" class="text-sm text-content-secondary break-all">{{ result }}</div>
  </CdsForm>
</template>
```

### Vuelidate

With [vuelidate](https://vuelidate-next.netlify.app/) the rules are declared
declaratively, and the field errors are passed into `error-messages` in the same
way.

**Example — `Vuelidate.vue`:**

```vue
<script setup lang="ts">
import { CdsButton, CdsCheckbox, CdsForm, CdsTextInput } from '@central-design-system/components';
import { useVuelidate } from '@vuelidate/core';
import { email, maxLength, minLength, required } from '@vuelidate/validators';
import { reactive, ref, unref } from 'vue';

const initialState = {
  name: '',
  email: '',
  phone: '',
  checkbox: null as boolean | null
};

const state = reactive({ ...initialState });
const result = ref('');

const rules = {
  name: { required },
  phone: { required, minLength: minLength(8), maxLength: maxLength(9) },
  email: { required, email },
  checkbox: { required }
};

const v$ = useVuelidate(rules, state);

const clear = () => {
  v$.value.$reset();
  result.value = '';

  for (const [key, value] of Object.entries(initialState)) {
    (state as Record<string, any>)[key] = value;
  }
};

const submit = () => {
  if (v$.value.$invalid) {
    v$.value.$touch();
    return;
  }

  result.value = `Отправлено: ${JSON.stringify(state)}`;
};
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsTextInput
      v-model="state.name"
      :error-messages="v$.name.$errors.map((e) => unref(e.$message))"
      label="Имя"
      placeholder="Введите имя"
      @input="v$.name.$touch()"
      @blur="v$.name.$touch()"
    />
    <CdsTextInput
      v-model="state.phone"
      :error-messages="v$.phone.$errors.map((e) => unref(e.$message))"
      label="Номер телефона"
      placeholder="Введите номер"
      @input="v$.phone.$touch()"
      @blur="v$.phone.$touch()"
    />
    <CdsTextInput
      v-model="state.email"
      :error-messages="v$.email.$errors.map((e) => unref(e.$message))"
      label="E-mail"
      placeholder="Введите E-mail"
      @input="v$.email.$touch()"
      @blur="v$.email.$touch()"
    />
    <CdsCheckbox
      v-model="state.checkbox"
      :error-messages="v$.checkbox.$errors.map((e) => unref(e.$message))"
      label="Согласен с условиями"
      @change="v$.checkbox.$touch()"
      @blur="v$.checkbox.$touch()"
    />
    <div class="flex gap-2">
      <CdsButton type="submit">Отправить</CdsButton>
      <CdsButton variant="soft" color="brand" @click="clear">Очистить</CdsButton>
    </div>
    <div v-if="result" class="text-sm text-content-secondary break-all">{{ result }}</div>
  </CdsForm>
</template>
```

## API

### CdsForm

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `description` | `string \| undefined` | — | no | Description of the form. Rendered under the heading through `CdsDescription`. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `firstFail` | `boolean \| undefined` | — | no | Stops the validation at the very first invalid field — the remaining fields are not checked |
| `label` | `string \| undefined` | — | no | Heading of the form. Rendered above the content through `CdsDescription`. |
| `modelValue` | `boolean \| null \| undefined` | `null` | no | Resulting validity of the form: `true` — every field passed the check, `false` — there are errors, `null` — the form has not been validated yet |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `validateOn` | `ValidateOn \| undefined` | `'input'` | no | When to run the validation of the form fields: on input, on blur or manually only |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `submit` | `[payload: SubmitEventPromise]` | Submission of the form. The event is a Promise with the validation result. |
| `update:modelValue` | `[value: boolean \| null]` | The overall validity status of the form changed (v-model). |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ errors: FieldValidationResult[]; isDisabled: boolean \| null \| undefined; isReadonly: boolean \| null \| undefined; isValidating: boolean; isValid: boolean \| null \| undefined; items: FormField[]; validate: () => Promise<FormValidationResult>; reset: () => void; resetValidation: () => void; }` | Main content of the form. Receives the current state and the validation methods. |
| `description` | `any` | Description of the form (overrides the `description` prop). |
| `label` | `any` | Heading of the form (overrides the `label` prop). |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `errors` | `{ id: string \| number; errorMessages: string[]; }[]` | Validation errors of the form fields: the identifier of a field and its error messages. |
| `isDisabled` | `boolean \| null \| undefined` | Whether all the fields of the form are blocked. |
| `isReadonly` | `boolean \| null \| undefined` | Whether the fields of the form are read-only. |
| `isValid` | `boolean \| null \| undefined` | Validity of the form: `true` — every field passed the check, `false` — there are errors, `null` — the form has not been validated yet. |
| `isValidating` | `boolean` | Whether the form is being validated right now. |
| `items` | `{ id: string \| number; validate: () => Promise<string[]>; reset: () => Promise<void>; resetValidation: () => Promise<void>; vm: Raw<ComponentInternalInstance>; isValid: boolean \| null; errorMessages: string[]; }[]` | The fields registered in the form together with their validation state. |
| `resetValidation` | `() => void` | Resets the validation state only, keeping the entered values. |
| `validate` | `() => Promise<{ valid: boolean; errors: FieldValidationResult[] \| { id: string \| number; errorMessages: string[]; }[]; }>` | Runs the validation of all the form fields and returns the result together with the list of errors. |

---

# CdsFunctionalButton

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 15/15 · 6 unit · lines 100% (v4.0.0-alpha.13) · a11y: 3 axe recommendations (v4.0.0-alpha.11)_

A functional button is a utility action next to the content: download a file in a row of a list, reveal a password in a field, collapse a block, open the menu of a record. It is a CdsButton with `size="sm"`, `variant="soft"` and `color="neutral"` fixed in place: the background is transparent and appears only on hover, so the button does not compete for attention with the content it stands next to.

**See also:** Style the primary action of the screen — "Save", "Submit the request" — with CdsButton, and a navigation inside a paragraph with CdsLink. If the icon triggers nothing and only explains the content, leave it as CdsIcon.

## Variations

### Icon

The `icon` prop sets the icon — the usual look of a functional button. Such a
button has no text, so add an `aria-label`: it stays the only name of the
action.

**Example — `Icons.vue`:**

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

const actions = [
  { icon: 'edit', label: 'Редактировать' },
  { icon: 'copy', label: 'Дублировать' },
  { icon: 'download', label: 'Скачать' },
  { icon: 'delete', label: 'Удалить' },
  { icon: 'more-vertical', label: 'Ещё' }
];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsFunctionalButton v-for="action of actions" :key="action.icon" :icon="action.icon" :aria-label="action.label" />
  </div>
</template>
```

### Content

The `default` slot replaces the icon with your own content — a short label for
an action that an icon cannot explain, for example.

**Example — `Content.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsFunctionalButton>Показать все</CdsFunctionalButton>
    <CdsFunctionalButton>+3</CdsFunctionalButton>
  </div>
</template>
```

### States

The `loading` prop shows the progress of an operation instead of the icon,
`disabled` dims the button and forbids pressing it, and `readonly` keeps the
button looking regular but takes it out of the focus order and blocks the click.

**Example — `States.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsFunctionalButton icon="save" aria-label="Сохранить" />
    <CdsFunctionalButton icon="save" aria-label="Сохранение" loading />
    <CdsFunctionalButton icon="save" aria-label="Сохранить" disabled />
    <CdsFunctionalButton icon="save" aria-label="Сохранить" readonly />
  </div>
</template>
```

### Button as a link

Pass `href` (or `to` with a `RouteLocationRaw` object from vue-router) — the
button renders as an `a` tag with all the link attributes, keeping its look.

**Example — `Link.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsFunctionalButton
      icon="external-link"
      href="https://github.com"
      target="_blank"
      rel="noreferrer"
      aria-label="Открыть исходный код"
    />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The primary action of the screen is a regular button: it is visible and hard to miss. | A functional button blends into the text and does not read as the primary action. |
| Два-три частых действия рядом, остальные — под кнопкой «Ещё». | A row of identical icons takes long to read, and the right one has to be found by trial. |
| A button without text has an aria-label — the screen reader names the action. | Без подписи кнопка звучит как «кнопка», а редкое действие не угадать и по иконке. |

## Scenarios

### Actions in a row of a list

Download and delete are actions on a particular record, not on the screen. The
buttons stand at the right edge of the row, and an `aria-label` with the name of
the document tells the buttons of the neighboring rows apart.

**Example — `RowActions.vue`:**

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

const documents = ref([
  { id: 1, name: 'Договор поставки № 42.pdf', size: '340 КБ' },
  { id: 2, name: 'Спецификация.xlsx', size: '82 КБ' },
  { id: 3, name: 'Акт сверки за март.pdf', size: '128 КБ' }
]);

const remove = (id: number) => {
  documents.value = documents.value.filter((document) => document.id !== id);
};
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <div v-for="document of documents" :key="document.id" class="flex items-center gap-2">
      <CdsIcon icon="file" size="lg" color="content-secondary" />

      <div class="flex min-w-0 flex-col">
        <span class="truncate">{{ document.name }}</span>
        <span class="text-100 text-content-secondary">{{ document.size }}</span>
      </div>

      <div class="ml-auto flex gap-1">
        <CdsFunctionalButton icon="download" :aria-label="`Скачать ${document.name}`" />
        <CdsFunctionalButton icon="delete" :aria-label="`Удалить ${document.name}`" @click="remove(document.id)" />
      </div>
    </div>

    <span v-if="!documents.length" class="text-content-secondary">Все документы удалены</span>
  </div>
</template>
```

### A button inside an input

In the `append-inner` and `prepend-inner` slots of the inputs a functional
button fits the size of the field exactly. Here it toggles `type` between
`password` and `text`, and the `aria-label` changes together with the icon.

**Example — `PasswordToggle.vue`:**

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

const password = ref('qwerty123');
const visible = ref(false);
</script>

<template>
  <CdsTextInput
    v-model="password"
    class="m-auto w-full max-w-md"
    label="Пароль"
    :type="visible ? 'text' : 'password'"
    hint="Минимум 8 символов"
  >
    <template #append-inner>
      <CdsFunctionalButton
        :icon="visible ? 'visibility-off' : 'visibility'"
        :aria-label="visible ? 'Скрыть пароль' : 'Показать пароль'"
        @click="visible = !visible"
      />
    </template>
  </CdsTextInput>
</template>
```

### Copying a value

A button next to a value copies it into the clipboard: `loading` shows the short
operation, and the `check` icon confirms the result and turns back into `copy` a
couple of seconds later.

**Example — `CopyValue.vue`:**

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

const account = '40702810900000012345';

const loading = ref(false);
const copied = ref(false);

const copy = () => {
  loading.value = true;

  setTimeout(() => {
    loading.value = false;
    copied.value = true;

    setTimeout(() => (copied.value = false), 2000);
  }, 600);
};
</script>

<template>
  <div class="m-auto flex w-[320px] items-center gap-2">
    <div class="flex min-w-0 flex-col">
      <span class="text-100 text-content-secondary">Расчётный счёт</span>
      <span class="truncate">{{ account }}</span>
    </div>

    <CdsFunctionalButton
      class="ml-auto"
      :icon="copied ? 'check' : 'copy'"
      :loading="loading"
      :aria-label="copied ? 'Номер скопирован' : 'Скопировать номер счёта'"
      @click="copy"
    />
  </div>
</template>
```

### Collapsing a block

A chevron expands and collapses a section: the icon changes together with the
state, and `aria-expanded` reports it to the screen reader.

**Example — `Collapsible.vue`:**

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

const expanded = ref(true);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <div class="flex items-center gap-2">
      <span class="font-bold">Условия оплаты</span>

      <CdsFunctionalButton
        class="ml-auto"
        :icon="expanded ? 'chevron-up' : 'chevron-down'"
        :aria-expanded="expanded"
        :aria-label="expanded ? 'Свернуть условия оплаты' : 'Развернуть условия оплаты'"
        @click="expanded = !expanded"
      />
    </div>

    <p v-if="expanded" class="text-content-secondary">
      Оплата в течение 15 рабочих дней после подписания акта. Аванс — 30% от суммы договора.
    </p>
  </div>
</template>
```

## API

### CdsFunctionalButton

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `icon` | `IconValue \| undefined` | — | no | Icon |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'button'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content inside the button |
| `loader` | `any` | Loading indicator |

---

# CdsGrid

_Category: Layouts · since 4.0.0_

_Tests: API 18/18 · 29 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A responsive modular grid: `CdsGrid`, `CdsRow` and `CdsCol` lay the content out in columns — from 4 on a phone to 16 on wide screens. The grid works in two modes — Flexbox (the default) and CSS Grid — and the whole markup is also available as ready-made CSS classes, without a single component.

**See also:** The grid lays out the content inside a page. Build the frame of the application — the header, the drawers and the footer — from CdsLayout.

## Anatomy

Every layout starts with `CdsGrid` — the container can sit at any nesting level
as long as it takes the full width of its parent. Inside a Flexbox grid the
`CdsCol` columns are grouped into `CdsRow` rows; in CSS Grid mode the rows are
not needed — the columns wrap on their own.

## Variations

### Flexbox or CSS Grid

By default the grid is built on Flexbox. The second mode — CSS Grid — is turned
on once for the whole application by the `cssGrid` option and adds capabilities
Flexbox does not have: nested `subgrid` grids and explicit positioning of the
columns through `span`, `start` and `end`. In exchange, the Flexbox mode can
change the order of the columns through `order`.

```ts
import { createCds } from '@central-design-system/components';

const cds = createCds({ cssGrid: true });
```

The components and the props are the same in both modes, only the generated
markup differs. In the examples below the CSS Grid mode is turned on locally —
through `provide(CssGridSymbol, true)`; in an application the `cssGrid` option
is enough.

### Columns and breakpoints

The width of a column is set by the `xs`–`xl` breakpoint props: the number says
how many grid columns `CdsCol` takes starting from that breakpoint. The values
work "bottom-up": `md="4"` applies to `md` and wider.

**Example — `Basic.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsRow>
      <CdsCol :md="4"><div class="cell">md: 4</div></CdsCol>
      <CdsCol :md="4"><div class="cell">md: 4</div></CdsCol>
      <CdsCol :md="4"><div class="cell">md: 4</div></CdsCol>
      <CdsCol :md="4"><div class="cell">md: 4</div></CdsCol>
    </CdsRow>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

The number of columns in the grid depends on the width of the screen, so the
same number takes a different share of the row on different breakpoints:

| Breakpoint | Screen width | Columns in the grid |
| ---------- | ------------ | ------------------- |
| `xs`       | ≥ 320px      | 4                   |
| `sm`       | ≥ 672px      | 8                   |
| `md`       | ≥ 1056px     | 16                  |
| `lg`       | ≥ 1312px     | 16                  |
| `xl`       | ≥ 1584px     | 16                  |

Combine the breakpoints to describe the behavior of the layout on every screen:
here each column takes half of the row on a phone and a quarter starting from a
tablet. The value `0` hides the column on a breakpoint.

**Example — `Responsive.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsRow>
      <CdsCol :xs="2" :sm="2" :md="4"><div class="cell">xs: 2 · sm: 2 · md: 4</div></CdsCol>
      <CdsCol :xs="2" :sm="2" :md="4"><div class="cell">xs: 2 · sm: 2 · md: 4</div></CdsCol>
      <CdsCol :xs="2" :sm="2" :md="4"><div class="cell">xs: 2 · sm: 2 · md: 4</div></CdsCol>
      <CdsCol :xs="2" :sm="2" :md="4"><div class="cell">xs: 2 · sm: 2 · md: 4</div></CdsCol>
    </CdsRow>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

### Automatic columns

A `CdsCol` without breakpoint props splits the row evenly with its neighbors:
one column takes the whole width, four take a quarter each. Handy when the
shares are equal and there is no point in recalculating them per breakpoint.
Works in Flexbox mode only.

**Example — `AutoColumns.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsRow class="cds-row-padding">
      <CdsCol><div class="cell">1 из 1</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-row-padding">
      <CdsCol><div class="cell">1 из 2</div></CdsCol>
      <CdsCol><div class="cell">2 из 2</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-row-padding">
      <CdsCol><div class="cell">1 из 4</div></CdsCol>
      <CdsCol><div class="cell">2 из 4</div></CdsCol>
      <CdsCol><div class="cell">3 из 4</div></CdsCol>
      <CdsCol><div class="cell">4 из 4</div></CdsCol>
    </CdsRow>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

### Grid modes

The `narrow` and `condensed` props shrink the gap between the columns from 32px
to 16px and 1px respectively. `CdsRow` has the same props — that is how the
modes are mixed inside one grid. The `wide` prop removes the maximum width limit
(1584px) and stretches the grid across the whole container.

**Example — `Modes.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col gap-3">
    <div>
      <p class="caption">По умолчанию — отступ между колонками 32px</p>
      <CdsGrid class="grid-wide">
        <CdsRow>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
        </CdsRow>
      </CdsGrid>
    </div>
    <div>
      <p class="caption">narrow — отступ 16px</p>
      <CdsGrid narrow class="grid-narrow">
        <CdsRow>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
        </CdsRow>
      </CdsGrid>
    </div>
    <div>
      <p class="caption">condensed — отступ 1px</p>
      <CdsGrid condensed class="grid-condensed">
        <CdsRow>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
          <CdsCol :md="4"><div class="cell" /></CdsCol>
        </CdsRow>
      </CdsGrid>
    </div>
  </div>
</template>

<style scoped>
.caption {
  margin-bottom: 8px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
}

/* Фон сетки подсвечивает отступы; у каждого вида — свой цвет, как в гайдах CDS 3 */
.grid-wide {
  background-color: var(--cds-color-status-progress-fill);
}

.grid-narrow {
  background-color: var(--cds-color-other-teal-fill);
}

.grid-condensed {
  background-color: var(--cds-color-other-purple-fill);
}

.cell {
  min-height: 48px;
  background-color: var(--cds-color-surface-primary);
}

.grid-wide .cell {
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}

.grid-narrow .cell {
  box-shadow: 0 0 0 1px var(--cds-color-other-teal-line);
}

.grid-condensed .cell {
  box-shadow: 0 0 0 1px var(--cds-color-other-purple-line);
}
</style>
```

### Offset and order

Instead of a number, a breakpoint prop can take an object. The `span` key sets
the width, `offset` shifts the column to the right by the given number of
columns.

**Example — `Offset.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsRow class="cds-row-padding">
      <CdsCol :md="{ span: 4, offset: 12 }"><div class="cell">offset: 12</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-row-padding">
      <CdsCol :md="{ span: 8, offset: 8 }"><div class="cell">offset: 8</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-row-padding">
      <CdsCol :md="{ span: 12, offset: 4 }"><div class="cell">offset: 4</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-row-padding">
      <CdsCol :md="16"><div class="cell">offset: 0</div></CdsCol>
    </CdsRow>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

The `order` key changes the visual order of the columns without touching the
markup — to show the columns on a desktop in a different sequence than in the
DOM, for example. Works in Flexbox mode only.

**Example — `Order.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsRow>
      <CdsCol :md="{ span: 8, order: 3 }"><div class="cell">1-я в разметке · order: 3</div></CdsCol>
      <CdsCol :md="{ span: 4, order: 1 }"><div class="cell">2-я · order: 1</div></CdsCol>
      <CdsCol :md="{ span: 4, order: 2 }"><div class="cell">3-я · order: 2</div></CdsCol>
    </CdsRow>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

### CSS Grid mode

In CSS Grid mode the columns go straight into `CdsGrid` — without `CdsRow`: the
grid wraps them onto a new line itself when the row is full.

**Example — `CssGrid.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CssGridSymbol } from '@central-design-system/components';
import { provide } from 'vue';

// В приложении режим включается один раз: createCds({ cssGrid: true })
provide(CssGridSymbol, true);
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsCol :xs="2" :md="4"><div class="cell">xs: 2 · md: 4</div></CdsCol>
    <CdsCol :xs="2" :md="4"><div class="cell">xs: 2 · md: 4</div></CdsCol>
    <CdsCol :xs="2" :md="4"><div class="cell">xs: 2 · md: 4</div></CdsCol>
    <CdsCol :xs="2" :md="4"><div class="cell">xs: 2 · md: 4</div></CdsCol>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

A nested grid with the `subgrid` prop inherits the columns of its parent: put it
inside a `CdsCol` and its columns line up exactly with the lines of the outer
grid. The `narrow` and `condensed` modes of a nested grid work independently
from the root one.

**Example — `Subgrid.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CssGridSymbol } from '@central-design-system/components';
import { provide } from 'vue';

// В приложении режим включается один раз: createCds({ cssGrid: true })
provide(CssGridSymbol, true);
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsCol :md="4"><div class="cell">md: 4</div></CdsCol>
    <CdsCol :md="12">
      <CdsGrid subgrid class="subgrid-demo">
        <CdsCol :md="4"><div class="cell cell--nested">md: 4</div></CdsCol>
        <CdsCol :md="4"><div class="cell cell--nested">md: 4</div></CdsCol>
        <CdsCol :md="4"><div class="cell cell--nested">md: 4</div></CdsCol>
      </CdsGrid>
    </CdsCol>
  </CdsGrid>
</template>

<style scoped>
/* Фон подсвечивает отступы; у вложенной сетки — свой цвет, чтобы видеть её границы */
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.subgrid-demo {
  background-color: var(--cds-color-other-purple-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}

.cell--nested {
  box-shadow: 0 0 0 1px var(--cds-color-other-purple-line);
}
</style>
```

A column can be positioned explicitly: in a breakpoint object `start` and `end`
set the starting and the ending grid line, and the `span` prop fixes the range
for all breakpoints at once — as a number or as a share: `'25%'`, `'50%'`,
`'75%'`, `'100%'`.

**Example — `SpanStartEnd.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CssGridSymbol } from '@central-design-system/components';
import { provide } from 'vue';

// В приложении режим включается один раз: createCds({ cssGrid: true })
provide(CssGridSymbol, true);
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsCol :span="8"><div class="cell">span: 8 — на любом брейкпоинте</div></CdsCol>
    <CdsCol :md="{ start: 5, span: 8 }"><div class="cell">start: 5 · span: 8</div></CdsCol>
    <CdsCol :md="{ start: 9, end: 17 }"><div class="cell">start: 9 · end: 17</div></CdsCol>
    <CdsCol md="50%"><div class="cell">md: 50%</div></CdsCol>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

### CSS classes

The whole grid is duplicated with utility classes — lay a layout out without Vue
components: in emails, on static pages or inside somebody else's code. The
components generate the same classes, so both ways mix freely.

**Example — `Classes.vue`:**

```vue
<template>
  <div class="cds-grid grid-demo">
    <div class="cds-row">
      <div class="cds-col-xs-2 cds-col-md-4"><div class="cell">cds-col-md-4</div></div>
      <div class="cds-col-xs-2 cds-col-md-4"><div class="cell">cds-col-md-4</div></div>
      <div class="cds-col-xs-2 cds-col-md-8"><div class="cell">cds-col-md-8</div></div>
    </div>
  </div>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

Classes of the Flexbox grid:

| Class                                        | Purpose                                            |
| -------------------------------------------- | -------------------------------------------------- |
| `cds-grid`                                   | Grid container                                     |
| `cds-grid-narrow` / `cds-grid-condensed`     | Narrow (16px) and condensed (1px) gap              |
| `cds-grid--wide`                             | No maximum width limit                             |
| `cds-row`                                    | Row; `cds-row-narrow`, `cds-row-condensed` — modes |
| `cds-col-{bp}-{n}`                           | Column `n` wide on the `bp` breakpoint and wider   |
| `cds-col-{bp}` / `cds-col-{bp}-auto`         | Automatic column / width by content                |
| `cds-offset-{bp}-{n}`                        | Shift to the right by `n` columns                  |
| `cds-order-{bp}-{n}`                         | Visual order of the column                         |
| `cds-row-padding` / `cds-col-padding`        | Vertical paddings equal to half of the gutter      |
| `cds-aspect-ratio cds-aspect-ratio--{w}x{h}` | Aspect ratio of a block: `16x9`, `4x3`, `1x1`, …   |

Classes of the CSS Grid mode:

| Class                                     | Purpose                                        |
| ----------------------------------------- | ---------------------------------------------- |
| `cds--css-grid`                           | Container; `--narrow`, `--condensed`, `--wide` |
| `cds--css-grid-column`                    | Column                                         |
| `cds--col-span-{n}`                       | Range of `n` columns on all breakpoints        |
| `cds--{bp}:col-span-{n}`                  | Range starting from the `bp` breakpoint        |
| `cds--col-span-{25\|50\|75\|100}`         | Range as a share of the grid                   |
| `cds--col-start-{n}` / `cds--col-end-{n}` | Starting and ending line                       |
| `cds--subgrid`                            | Nested grid; modes — `--narrow` and so on      |

The `cds-no-gutter` and `cds-no-gutter--start` / `cds-no-gutter--end` classes
remove the paddings of the columns — for the whole row or on one side. Their
counterparts `cds-hang--start` / `cds-hang--end` give the padding back to the
content when it has to be aligned to the modular grid.

**Example — `NoGutter.vue`:**

```vue
<script setup lang="ts">
import { CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';
</script>

<template>
  <CdsGrid class="grid-demo">
    <CdsRow class="cds-row-padding">
      <CdsCol :md="8"><div class="cell">с отступами</div></CdsCol>
      <CdsCol :md="8"><div class="cell">с отступами</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-no-gutter cds-row-padding">
      <CdsCol :md="8"><div class="cell">cds-no-gutter</div></CdsCol>
      <CdsCol :md="8"><div class="cell">cds-no-gutter</div></CdsCol>
    </CdsRow>
    <CdsRow class="cds-no-gutter--start cds-row-padding">
      <CdsCol :md="8"><div class="cell">cds-no-gutter--start</div></CdsCol>
      <CdsCol :md="8"><div class="cell">cds-no-gutter--start</div></CdsCol>
    </CdsRow>
  </CdsGrid>
</template>

<style scoped>
.grid-demo {
  background-color: var(--cds-color-status-progress-fill);
}

.cell {
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 48px;
  font-size: 12px;
  color: var(--cds-color-content-secondary);
  background-color: var(--cds-color-surface-primary);
  box-shadow: 0 0 0 1px var(--cds-color-status-progress-line);
}
</style>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The spans of a row add up to the full width of the grid — 16 columns. | Spans adding up to more than 16 wrap a column onto a new line and break the row. |
| The content stretches together with the column and survives a change of breakpoint. | A fixed width argues with the grid and overflows the column on narrow screens. |

## Scenarios

### Card tiles

A showcase of reports: on a phone the cards go in a column, on a tablet two per
row, on a wide screen four in a row. The `cds-row-padding` class gives the
vertical gap between the rows of the tiles.

**Example — `Cards.vue`:**

```vue
<script setup lang="ts">
import { CdsCard, CdsCol, CdsGrid, CdsRow } from '@central-design-system/components';

const reports = [
  { title: 'Продажи', text: 'Выручка и динамика по месяцам' },
  { title: 'Склад', text: 'Остатки и оборачиваемость' },
  { title: 'Клиенты', text: 'Новые и повторные заказы' },
  { title: 'Финансы', text: 'Платежи и задолженность' }
];
</script>

<template>
  <CdsGrid>
    <CdsRow class="cds-row-padding">
      <CdsCol v-for="report in reports" :key="report.title" :xs="4" :sm="4" :md="8" :lg="4">
        <CdsCard :title="report.title" :text="report.text" height="100%" />
      </CdsCol>
    </CdsRow>
  </CdsGrid>
</template>
```

### Two-column form

The grid lays out the fields of a form: the paired fields (`sm="4" md="8"`)
split the row in half starting from a tablet, while the comment and the buttons
take the whole row. On a phone everything folds into a single column with no
extra conditions. The vertical rhythm comes from the `py-1` utility classes on
the columns — tighter than `cds-row-padding` — and `hide-details` on the
controls removes the reserved area for messages.

**Example — `FormLayout.vue`:**

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

const name = ref('');
const surname = ref('');
const email = ref('');
const phone = ref('');
const company = ref('');
const city = ref<string>();
const comment = ref('');
</script>

<template>
  <CdsForm>
    <CdsGrid>
      <CdsRow>
        <CdsCol class="py-1" :sm="4" :md="8">
          <CdsTextInput v-model="name" label="Имя" placeholder="Иван" />
        </CdsCol>
        <CdsCol class="py-1" :sm="4" :md="8">
          <CdsTextInput v-model="surname" label="Фамилия" placeholder="Петров" />
        </CdsCol>
        <CdsCol class="py-1" :sm="4" :md="8">
          <CdsTextInput v-model="email" label="Рабочая почта" placeholder="ivan@company.ru" type="email" />
        </CdsCol>
        <CdsCol class="py-1" :sm="4" :md="8">
          <CdsTextInput v-model="phone" label="Телефон" placeholder="+7 912 345-67-89" type="tel" />
        </CdsCol>
        <CdsCol class="py-1" :sm="4" :md="8">
          <CdsTextInput v-model="company" label="Компания" placeholder="«Северный ветер»" />
        </CdsCol>
        <CdsCol class="py-1" :sm="4" :md="8">
          <CdsSelect
            v-model="city"
            label="Город"
            placeholder="Выберите город"
            :items="['Москва', 'Санкт-Петербург', 'Екатеринбург', 'Новосибирск']"
          />
        </CdsCol>
        <CdsCol class="py-1" :sm="8" :md="16">
          <CdsTextArea v-model="comment" label="Комментарий" placeholder="Чем мы можем помочь?" :rows="3" />
        </CdsCol>
        <CdsCol class="py-1" :sm="8" :md="16">
          <div class="flex gap-3">
            <CdsButton type="submit" text="Отправить заявку" />
            <CdsButton variant="soft" color="neutral" text="Очистить" />
          </div>
        </CdsCol>
      </CdsRow>
    </CdsGrid>
  </CdsForm>
</template>
```

### List with filters

The classic "filters on the left, results on the right" proportion: the panel
takes 4 columns, the list takes 12. On a phone and a tablet the filters stand
above the list — that is what the full-width `xs` and `sm` values are for.

**Example — `SidebarFilters.vue`:**

```vue
<script setup lang="ts">
import {
  CdsCard,
  CdsCheckbox,
  CdsCol,
  CdsGrid,
  CdsRow,
  CdsSelect,
  CdsTextInput
} from '@central-design-system/components';
import { computed, ref } from 'vue';

const documents = [
  { title: 'Договор поставки № 114', subtitle: 'Подписан · 12 июля', signed: true },
  { title: 'Акт сверки за июнь', subtitle: 'Черновик · 3 июля', signed: false },
  { title: 'Счёт № 2087', subtitle: 'Подписан · 28 июня', signed: true }
];

const query = ref('');
const onlySigned = ref(false);

const filtered = computed(() =>
  documents.filter(
    (document) =>
      document.title.toLowerCase().includes(query.value.toLowerCase()) && (!onlySigned.value || document.signed)
  )
);
</script>

<template>
  <CdsGrid>
    <CdsRow>
      <CdsCol :xs="4" :sm="8" :md="4">
        <div class="flex flex-col gap-2">
          <CdsTextInput v-model="query" label="Название" placeholder="Поиск по документам" />
          <CdsSelect label="Период" :items="['За месяц', 'За квартал', 'За год']" model-value="За месяц" />
          <CdsCheckbox v-model="onlySigned" label="Только подписанные" />
        </div>
      </CdsCol>
      <CdsCol :xs="4" :sm="8" :md="12">
        <div class="flex flex-col gap-2">
          <CdsCard
            v-for="document in filtered"
            :key="document.title"
            :title="document.title"
            :subtitle="document.subtitle"
          />
        </div>
      </CdsCol>
    </CdsRow>
  </CdsGrid>
</template>
```

## API

### CdsGrid

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `condensed` | `boolean \| undefined` | — | no | Condensed grid. The gap is reduced to 1px on both sides |
| `narrow` | `boolean \| undefined` | — | no | Narrow grid |
| `subgrid` | `boolean \| undefined` | — | no | Only CSS Grid supported. A nested grid |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `wide` | `boolean \| undefined` | — | no | Removes the default max-width and stretches the grid across the whole width of the container |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Rows of the grid — `CdsRow` |

### CdsCol

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `lg` | `ColumnBreakpoint<ColumnGridBreakpoint \| ColumnFlexBreakpoint>` | — | no | >1312px |
| `md` | `ColumnBreakpoint<ColumnGridBreakpoint \| ColumnFlexBreakpoint>` | — | no | >1056px |
| `sm` | `ColumnBreakpoint<ColumnGridBreakpoint \| ColumnFlexBreakpoint>` | — | no | >672px |
| `span` | `string \| number \| ColumnSpanType \| undefined` | — | no | Only CSS Grid supported. A permanent column range, start or end values that never change. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `xl` | `ColumnBreakpoint<ColumnGridBreakpoint \| ColumnFlexBreakpoint>` | — | no | >1584px |
| `xs` | `ColumnBreakpoint<ColumnGridBreakpoint \| ColumnFlexBreakpoint>` | — | no | >320px |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the column |

### CdsRow

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `condensed` | `boolean \| undefined` | — | no | Condensed grid. The gap is reduced to 1px on both sides |
| `narrow` | `boolean \| undefined` | — | no | Narrow grid |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Columns of the row — `CdsCol` |

---

# CdsHeader

_Category: Layouts · since 4.0.0_

_Tests: API 12/12 · 21 unit · lines 100% (v4.0.0-alpha.13) · a11y: 6 axe recommendations (v4.0.0-alpha.11)_

The header of the application: the title, the global search, notifications, the profile — everything that has to be at hand on any screen. The layout measures its height itself and reserves the space, so the content never ends up under the header.

**See also:** The header works only inside CdsLayout — outside the layout it renders nothing and warns about it in the console. The content of the header is laid out by CdsToolbar, and the bottom bar of the application is built by CdsFooter.

## Variations

### Separator

The header overlaps the scrollable content, so its edge is worth marking:
`bordered` draws a border, `elevated` casts a shadow. The shadow is more
noticeable and suits long lists better, the border suits calm pages.

**Example — `Separators.vue`:**

```vue
<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const separator = ref('bordered');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="separator" direction="horizontal" hide-details>
      <CdsRadio value="none" label="Без разделителя" />
      <CdsRadio value="bordered" label="Граница" />
      <CdsRadio value="elevated" label="Тень" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader :bordered="separator === 'bordered'" :elevated="separator === 'elevated'">
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="flex flex-col gap-2">
              <div v-for="n in 6" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Блок {{ n }}
              </div>
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Height

The height comes from the content: the layout measures the header and reserves
exactly as much space as it takes. The `height` prop is an initial estimate
before the first measurement: set the expected height so the content does not
jump on mount.

**Example — `Height.vue`:**

```vue
<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const size = ref(56);
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="size" direction="horizontal" hide-details>
      <CdsRadio :value="40" label="40 px" />
      <CdsRadio :value="56" label="56 px" />
      <CdsRadio :value="80" label="80 px" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader bordered :height="size">
          <CdsToolbar :style="{ height: size + 'px' }">
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Контент начинается ровно под шапкой: макет замерил её и зарезервировал {{ size }} px.
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Color

The `bg-color` prop paints the background of the header with a palette alias,
`color` paints the text and the icons inside. If only the background is set, the
text color is picked to be contrasting automatically.

**Example — `Colors.vue`:**

```vue
<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const bgColor = ref('default');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="bgColor" direction="horizontal" hide-details>
      <CdsRadio value="default" label="Цвет темы" />
      <CdsRadio value="indigo" label="indigo" />
      <CdsRadio value="teal" label="teal" />
      <CdsRadio value="neutral" label="neutral" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader :bg-color="bgColor === 'default' ? undefined : bgColor">
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Floating mode

The `reveal` prop hides the header when scrolling down and brings it back when
scrolling up — on long lists this gives the screen to the content. The
`reveal-offset` prop sets the zone near the top of the page where the header
stays in place. The `@reveal` event reports the change of visibility, and moving
the keyboard focus inside a hidden header brings it back.

**Example — `Reveal.vue`:**

```vue
<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';
import { ref } from 'vue';

const revealed = ref(true);
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsHeader reveal elevated :reveal-offset="120" @reveal="revealed = $event">
        <CdsToolbar>
          <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="mb-2 text-content-secondary">Шапка сейчас {{ revealed ? 'видна' : 'скрыта' }}</div>
          <div class="flex flex-col gap-2">
            <div v-for="n in 20" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Блок {{ n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Visibility

The `model-value` prop removes the header entirely: the layout stops reserving
space for it and the content takes the freed height. This is a handy way to hide
the header in full-screen modes — document viewing, a presentation.

**Example — `Visibility.vue`:**

```vue
<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';
</script>

<template>
  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Шапка видна</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsHeader bordered>
            <CdsToolbar>
              <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
            </CdsToolbar>
          </CdsHeader>

          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Контент страницы</div>
            </CdsPage>
          </CdsMain>
        </CdsLayout>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">:model-value="false"</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsHeader :model-value="false" bordered>
            <CdsToolbar>
              <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
            </CdsToolbar>
          </CdsHeader>

          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Шапка скрыта — контент поднялся на её место
              </div>
            </CdsPage>
          </CdsMain>
        </CdsLayout>
      </div>
    </div>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A border or a shadow separates the header from the content — while scrolling you can see where it ends. | Without a separator the content slides under the header and blends into it. |
| The header holds the title and one or two constantly needed actions. | A header crammed with buttons stops being an anchor and squeezes out the title. |

## Scenarios

### Application header

The basic set: a menu button, a logo, the title in `CdsToolbarTitle` and the
actions on the right. `CdsToolbarTitle` stretches and pushes the left and the
right groups to the edges, so no extra spacers are needed.

**Example — `AppBar.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsBadge,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered :height="64">
        <CdsToolbar class="h-[64px]">
          <CdsFunctionalButton icon="menu" class="mr-2" aria-label="Открыть навигацию" />
          <CdsAvatar icon="company" class="mr-2" />
          <CdsToolbarTitle>Портал закупок</CdsToolbarTitle>

          <CdsFunctionalButton icon="search" aria-label="Поиск" />
          <CdsBadge :content="3">
            <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
          </CdsBadge>
          <CdsAvatar icon="user" class="ml-2" />
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Header with tabs

Two `CdsToolbar` components in a row turn the header into a two-level one: the
name of the section on top, CdsTabs with the
subsections below. The tabs stay on the screen together with the header, so you
can switch from any point of the list.

**Example — `HeaderTabs.vue`:**

```vue
<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsTab,
  CdsTabs,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('active');
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered :height="96">
        <CdsToolbar>
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
        </CdsToolbar>
        <CdsToolbar no-gutter="start">
          <CdsTabs v-model="tab">
            <CdsTab value="active">Активные</CdsTab>
            <CdsTab value="draft">Черновики</CdsTab>
            <CdsTab value="archive">Архив</CdsTab>
          </CdsTabs>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Вкладка: {{ tab }}</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsHeader

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `bordered` | `boolean \| undefined` | `false` | no | Shows the border. |
| `color` | `string \| undefined` | — | no | Component color |
| `elevated` | `boolean \| undefined` | `false` | no | Shows the shadow. |
| `height` | `string \| number \| undefined` | `50` | no | Height of the element. |
| `modelValue` | `boolean \| undefined` | `true` | no | Visibility of the element in the layout. |
| `reveal` | `boolean \| undefined` | `false` | no | Floating mode: the element appears/hides on scroll. |
| `revealOffset` | `number \| undefined` | `250` | no | Scroll threshold (px) up to which the floating element stays visible. |
| `theme` | `string \| undefined` | — | no | Component theme |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `focusin` | `[event: FocusEvent]` | Focus moved inside the header. |
| `reveal` | `[value: boolean]` | Visibility of the floating header has changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the header (`CdsToolbar` and others). |

---

# CdsHighlight

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 9/9 · 16 unit · lines 100% (v4.0.0-alpha.13) · a11y: 2 axe recommendations (v4.0.0-alpha.11)_

Highlighting explains why a row made it into the results: the component finds the matches with the query (`query`) or with ready ranges (`matches`) in the text and wraps them into `mark`. Take it for search results, autocomplete suggestions and filtered lists.

**See also:** In CdsAutocomplete, CdsCombobox and CdsSelect the highlighting of the matches is already built in — a standalone `CdsHighlight` is not needed there. For a permanent label next to the text take CdsTag, for a counter take CdsBadge.

## Variations

### Search query

The `text` prop takes the source string, `query` takes what the user was looking
for. The query can be a string or an array of terms: all of them get
highlighted.

**Example — `Query.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      query="договор"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      :query="['поставки', 'подряда']"
    />
  </div>
</template>
```

### All occurrences

By default the first occurrence of every term is highlighted. The `match-all`
prop highlights all of them — in a long text this shows the full picture.

**Example — `MatchAll.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      query="договор"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Шаблоны: договор поставки, договор аренды и договор подряда"
      query="договор"
      match-all
    />
  </div>
</template>
```

### Case

The `ignore-case` prop looks for matches regardless of the case. You need it
almost always when the query is typed by the user.

**Example — `IgnoreCase.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight class="text-900 text-content-primary" text="ИНН, Инн и инн — одно и то же" query="инн" match-all />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="ИНН, Инн и инн — одно и то же"
      query="инн"
      match-all
      ignore-case
    />
  </div>
</template>
```

### Ready ranges

When the matches are found by the server rather than by the browser, pass them
into `matches` — an array of `[start, end]` pairs by the indexes of the source
string. The ranges take precedence over `query`, and overlapping ones are merged
automatically.

**Example — `Matches.vue`:**

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

// Диапазоны [start, end] в исходной строке: «канцелярских товаров» и «офиса»
const matches = [
  [28, 48],
  [67, 72]
] as const;
</script>

<template>
  <div class="flex justify-center">
    <CdsHighlight
      class="text-900 text-content-primary"
      text="Заявка на участие в закупке канцелярских товаров для регионального офиса"
      :matches="matches"
    />
  </div>
</template>
```

### Color and density

The `color` prop sets the color of the highlighting — the background is tinted
with it too, so a single value is enough. `opacity` changes the density of the
background.

**Example — `Colors.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight class="text-900 text-content-primary" text="Подсветка цветом по умолчанию" query="по умолчанию" />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Подсветка цветом бренда"
      query="цветом бренда"
      color="brand-primary"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Более плотный фон подсветки"
      query="плотный фон"
      color="green"
      opacity="28%"
    />
  </div>
</template>
```

### Markup

The `tag` prop sets the tag of the wrapper (`span` by default), `mark-class`
adds your own class to every match.

**Example — `Tag.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsHighlight
      class="text-900 text-content-primary"
      tag="p"
      text="Подсветка внутри абзаца: тег задаётся пропом tag"
      query="внутри абзаца"
    />

    <CdsHighlight
      class="text-900 text-content-primary"
      text="Совпадению можно добавить свой класс"
      query="свой класс"
      mark-class="font-bold"
    />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Only what the user searched for is highlighted — it is clear why the row made it into the results. | The whole row is highlighted: the highlighting stops highlighting anything. |
| In a long text turn on match-all: the user sees every match at once. | Only the first occurrence is highlighted — it looks like there are no matches further on. |
| For a query typed by the user turn on ignore-case — they do not double-check the case. | Без ignore-case запрос «инн» не находит «ИНН», и совпадение теряется. |

## Scenarios

### Searching through a list

The same query filters the list and highlights the matches in the found rows.
`match-all` and `ignore-case` keep the highlighting and the filter consistent:
once a row made it into the results, the match inside it is visible.

**Example — `SearchResults.vue`:**

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

const query = ref('дог');

const documents = [
  'Договор поставки канцелярии',
  'Договор аренды помещения',
  'Акт сверки взаиморасчётов',
  'Счёт на оплату № 1024'
];

const found = computed(() => {
  const needle = query.value.trim().toLowerCase();

  return needle ? documents.filter((document) => document.toLowerCase().includes(needle)) : documents;
});
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <CdsTextInput v-model="query" placeholder="Поиск по документам" prepend-inner-icon="search" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="document in found" :key="document">
        <CdsHighlight
          class="text-900 text-content-primary"
          :text="document"
          :query="query.trim()"
          match-all
          ignore-case
        />
      </li>

      <li v-if="found.length === 0" class="text-900 text-content-secondary">Ничего не найдено</li>
    </ul>
  </div>
</template>
```

### A query of several words

Split the typed phrase into words and pass them as an array into `query` — the
component highlights every word separately, even if they stand far apart in the
text.

**Example — `WordSearch.vue`:**

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

const query = ref('бумага а4');

const description =
  'Закупка бумаги: бумага А4 плотностью 80 г/м², бумага А3 и картон. Поставка на склад в Москве до конца месяца.';

const terms = computed(() => query.value.trim().split(/\s+/).filter(Boolean));
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <CdsTextInput v-model="query" label="Запрос" placeholder="Например: бумага а4" clearable />

    <CdsHighlight
      class="text-900 text-content-primary"
      tag="p"
      :text="description"
      :query="terms"
      match-all
      ignore-case
    />
  </div>
</template>
```

### Matches from the server

The full-text search on the backend already knows which fragments count as
matches: it accounts for morphology, synonyms and typos. Give those ranges to
`matches` — the client will not search anything again.

**Example — `ServerRanges.vue`:**

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

interface SearchResult {
  id: number;
  title: string;
  matches: [number, number][];
}

const loading = ref(false);
const results = ref<SearchResult[]>([]);

// Ответ поиска: сервер сам решил, какие фрагменты считать совпадениями
const response: SearchResult[] = [
  { id: 1, title: 'Заявка на поставку бумаги А4 для офиса', matches: [[19, 28]] },
  { id: 2, title: 'Договор поставки бумаги и картона', matches: [[17, 23]] }
];

const search = () => {
  loading.value = true;
  results.value = [];

  setTimeout(() => {
    results.value = response;
    loading.value = false;
  }, 1200);
};
</script>

<template>
  <div class="flex w-[350px] flex-col gap-2 m-auto">
    <CdsButton text="Найти «бумага А4»" :loading="loading" @click="search" />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="result in results" :key="result.id">
        <CdsHighlight class="text-900 text-content-primary" :text="result.title" :matches="result.matches" />
      </li>
    </ul>
  </div>
</template>
```

## API

### CdsHighlight

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Color of the highlighted text. |
| `ignoreCase` | `boolean \| undefined` | — | no | Ignores the case when searching by `query`. |
| `markClass` | `string \| undefined` | — | no | Extra CSS class for the `<mark>` element. |
| `matchAll` | `boolean \| undefined` | — | no | Highlights every occurrence, not just the first one. |
| `matches` | `readonly MatchRange[] \| undefined` | — | no | Ready match ranges `[start, end]`. They take precedence over `query`. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the highlight background (the `--cds-highlight-opacity` CSS variable). |
| `query` | `string \| string[] \| undefined` | — | no | Search query: a string or an array of term strings. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'span'` | no | Custom HTML tag or component to render |
| `text` | `string \| undefined` | `''` | no | The text the highlighting is performed in. |

---

# CdsIcon

_Category: Content · since 4.0.0_

_Tests: API 15/15 · 24 unit · 4 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 3 axe recommendations (v4.0.0-alpha.11)_

An icon is a short visual mark next to the text: the status of a record, the type of a file, the direction of a transition. The component takes an icon by name from a connected pack and subordinates its size, color and spacing to the design system tokens.

**See also:** Inside other components you do not assemble an icon separately: CdsButton, CdsTextInput, CdsList and others have the `icon`, `prepend-icon` and `append-icon` props. For a standalone action take CdsFunctionalButton — an icon button with a label and states. All the available icons are in the gallery, and connecting your own pack is described in the guide.

## Variations

### Icon

The `icon` prop takes the name of an icon from the default pack — `add` or
`search`, for example. The `name` prop does the same and reads more naturally
when the icon is set by a string. Besides a name, `icon` also accepts an icon
component and an array of SVG paths, so you can pass your own graphics into it.

**Example — `Default.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsIcon icon="add" />
    <CdsIcon icon="search" />
    <CdsIcon icon="settings" />
    <CdsIcon name="star-fill" />
  </div>
</template>
```

An icon from another connected pack is written with the prefix of that pack —
`i-ri:settings-3-line`. How to connect a pack is described in the
icons guide.

### Sizes

The `size` prop takes one of the scale values — from `xs` to `xl` — or a number
in pixels when the icon works as an illustration. The default is `md`, level
with the body text.

**Example — `Sizes.vue`:**

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

const sizes = CdsIcon.constants.sizes;
</script>

<template>
  <div class="flex flex-wrap items-end justify-center gap-5">
    <div v-for="size in sizes" :key="size" class="flex flex-col items-center gap-1">
      <CdsIcon icon="star-fill" :size="size" />
      <span class="text-50 text-content-secondary">{{ size }}</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsIcon icon="star-fill" :size="40" />
      <span class="text-50 text-content-secondary">40</span>
    </div>
  </div>
</template>
```

### Color

Without `color` the icon inherits the text color of its parent — this is the
default behavior and the right one in most cases.
The `color` prop takes a palette token (`content-secondary`, `brand-primary`), a
status color alias (`green`, `red`, `lemon`) or a `hex/rgb` value. The `opacity`
prop mutes the icon without changing its color.

**Example — `Colors.vue`:**

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

<template>
  <div class="text-brand-primary-content flex flex-wrap items-center justify-center gap-4">
    <CdsIcon icon="star-fill" size="lg" />
    <CdsIcon icon="star-fill" size="lg" color="content-secondary" />
    <CdsIcon icon="success-fill" size="lg" color="green" />
    <CdsIcon icon="error-fill" size="lg" color="red" />
    <CdsIcon icon="star" size="lg" color="#9e45f9" />
    <CdsIcon icon="star-fill" size="lg" color="brand-primary" />
    <CdsIcon icon="star-fill" size="lg" color="brand-primary" :opacity="0.4" />
  </div>
</template>
```

### Spacing from the text

The `start` and `end` props add spacing on the side of the text: `start` for an
icon before the label, `end` for one after it. This saves you from picking
margins by hand.

**Example — `Spacing.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-6">
    <span>
      <CdsIcon icon="download" start />
      Скачать отчёт
    </span>

    <span>
      Открыть в новой вкладке
      <CdsIcon icon="external-link" end />
    </span>
  </div>
</template>
```

### Reacting to a click

If you attach a `@click` handler to an icon, it gets `role="button"`, joins the
Tab order and changes the cursor; `disabled` removes it from the order and stops
it from accepting clicks. This is handy for small toggles inside your own
components — for a full-fledged action
CdsFunctionalButton fits better.

**Example — `Clickable.vue`:**

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

const count = ref(0);
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsIcon icon="refresh" size="lg" @click="count++" />
    <CdsIcon icon="refresh" size="lg" color="content-disable" disabled @click="count++" />

    <span class="text-100 text-content-secondary">Обновлений: {{ count }}</span>
  </div>
</template>
```

### Slot

The name of the icon can be passed as text into the default slot — the result is
the same as with `icon`. Useful when the name comes from an expression in the
template.

**Example — `WithSlot.vue`:**

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

const icon = 'notification';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsIcon size="lg">star-fill</CdsIcon>
    <CdsIcon size="lg">{{ icon }}</CdsIcon>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The icon stands next to a label and speeds up reading the line. | Without a label the icon has to be decoded: does a check mark mean «paid» or «verified»? |
| The color comes from the palette — the icon follows the theme and stays readable. | An arbitrary color falls out of the theme: on a dark background such an icon gets lost. |
| A clickable icon is a button: it has a name, hover states and keyboard focus. | A handler on an icon gives you a pointer cursor, but no name for a screen reader and no visible hover response. |

## Scenarios

### Statuses in a list

An icon to the left of a label sets the status by color and shape, while the
text names it in words. The colors come from the status aliases, `size="sm"`
fits the icon to small text, and `start` adds the spacing before the label.

**Example — `StatusList.vue`:**

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

const orders = [
  { id: 1, title: 'Счёт № 5512', status: 'Оплачен', icon: 'success-fill', color: 'green' },
  { id: 2, title: 'Счёт № 5513', status: 'Ожидает оплаты', icon: 'time', color: 'content-secondary' },
  { id: 3, title: 'Счёт № 5514', status: 'Просрочен', icon: 'error-fill', color: 'red' },
  { id: 4, title: 'Счёт № 5515', status: 'Требует проверки', icon: 'warning-fill', color: 'lemon' }
];
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-2">
    <div v-for="order in orders" :key="order.id" class="flex items-center justify-between gap-3">
      <span>{{ order.title }}</span>

      <span class="text-200 text-content-secondary">
        <CdsIcon :icon="order.icon" :color="order.color" size="sm" start />
        {{ order.status }}
      </span>
    </div>
  </div>
</template>
```

### List of attachments

The icon shows the type of a file and keeps the eye on the left edge of the
list. The `lg` size makes it more noticeable than the label, and the
`content-secondary` color keeps it from competing with the file name. The action
next to it is already a button: `CdsFunctionalButton` with an `aria-label`.

**Example — `FileList.vue`:**

```vue
<script setup lang="ts">
import { CdsFunctionalButton, CdsIcon } from '@central-design-system/components';

const files = [
  { name: 'Договор поставки № 42.pdf', size: '340 КБ', icon: 'file' },
  { name: 'Спецификация.xlsx', size: '82 КБ', icon: 'view-rows' },
  { name: 'Приложения.zip', size: '4,1 МБ', icon: 'archive' }
];
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-3">
    <div v-for="file in files" :key="file.name" class="flex items-center gap-2">
      <CdsIcon :icon="file.icon" size="lg" color="content-secondary" />

      <div class="flex min-w-0 flex-col">
        <span class="truncate">{{ file.name }}</span>
        <span class="text-100 text-content-secondary">{{ file.size }}</span>
      </div>

      <CdsFunctionalButton class="ml-auto" icon="download" :aria-label="`Скачать ${file.name}`" />
    </div>
  </div>
</template>
```

### Progress of an operation

The icon reflects the state of a process: the request is ready, is being sent,
has been sent. Only `icon` and `color` change — the component repaints in place
and the status line does not jump.

**Example — `SubmitFlow.vue`:**

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

const state = ref<'idle' | 'sending' | 'done'>('idle');

const status = computed(() => {
  if (state.value === 'sending') return { icon: 'hourglass', color: 'content-secondary', text: 'Отправляем заявку…' };
  if (state.value === 'done') return { icon: 'success-fill', color: 'green', text: 'Заявка отправлена' };

  return { icon: 'file', color: 'content-secondary', text: 'Заявка готова к отправке' };
});

function send() {
  state.value = 'sending';
  setTimeout(() => (state.value = 'done'), 1500);
}
</script>

<template>
  <div class="m-auto flex w-[300px] flex-col items-center gap-3">
    <span class="text-content-secondary">
      <CdsIcon :icon="status.icon" :color="status.color" start />
      {{ status.text }}
    </span>

    <CdsButton text="Отправить" :loading="state === 'sending'" :disabled="state === 'done'" @click="send" />
  </div>
</template>
```

### A note inside text

Inside a paragraph the icon aligns to the middle of the line, so you can put it
right into the text. The `sm` size and `start` keep it from breaking the line.

**Example — `InlineNote.vue`:**

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

<template>
  <p class="text-200 m-auto w-[360px] text-content-secondary">
    <CdsIcon icon="info" size="sm" start />
    Заявку можно отредактировать, пока она не отправлена. После отправки изменения согласовываются с заказчиком.
  </p>
</template>
```

## API

### CdsIcon

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `end` | `boolean \| undefined` | — | no | Adds spacing to the left of the icon — for an icon after the text |
| `icon` | `IconValue \| undefined` | — | no | Name of the icon or the icon component to render |
| `name` | `string \| undefined` | — | no | String name of an icon from a registered pack (an alias for icon) |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the icon — a number between 0 and 1 |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `start` | `boolean \| undefined` | — | no | Adds spacing to the right of the icon — for an icon before the text |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'i'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Name of the icon as text — an alternative to the `icon` prop |

---

# CdsImage

_Category: Content · since 4.0.0_

_Tests: API 39/39 · 51 unit · 1 known bug · lines 95.3% (v4.0.0-alpha.13) · a11y: 4 axe recommendations (v4.0.0-alpha.11)_

An image that knows how to wait. The component reserves space in the layout according to the given proportions, loads the file when the picture enters the viewport, and shows a placeholder while it is on its way. Over the image you can lay a gradient and any content — a caption, a tag, a button.

**See also:** For a photo of a person or a company logo in a round frame take CdsAvatar, for interface pictograms — CdsIcon. If the proportions have to be set not for a picture but for an arbitrary block — a video, a map, an iframe — use CdsResponsive, and a slideshow of several images is assembled by CdsCarousel.

## Anatomy

The first diagram is a loaded image: the container holds the size and the
proportions, the `img` tag sits inside, and an optional gradient lies on top.
The second one is the same place while the file has not arrived yet: a blurred
placeholder from `lazy-src` and the content of the `placeholder` slot.

## Variations

### Size and proportions

The minimum needed to show a picture is `src` and one size constraint: `width`,
`height`, `max-width` or `max-height`. The `alt` prop describes the image for
readers with screen readers and goes into the `aria-label` of the container.

**Example — `Default.vue`:**

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

<template>
  <CdsImage class="m-auto" src="/images/temp/wallpaper.webp" alt="Туман над лесным озером на рассвете" width="480" />
</template>
```

The `aspect-ratio` prop reserves the space for the image before it loads — the
neighboring content will not jump. The value is accepted both as the fraction
`16/9` and as the number `1.7778`. Without it the component waits for the file
and takes the proportions from its own dimensions — and if the file fails to
open, the space for the picture collapses.

**Example — `AspectRatio.vue`:**

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

const ratios = ['16/9', '4/3', '1'];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <div v-for="ratio in ratios" :key="ratio" class="flex flex-col items-center gap-1">
      <CdsImage src="/images/temp/desert.webp" alt="Столовые горы на закате" width="200" :aspect-ratio="ratio" cover />
      <span class="text-100 text-content-secondary">aspect-ratio="{{ ratio }}"</span>
    </div>
  </div>
</template>
```

### Filling the container

By default the image fits into the container as a whole (`object-fit: contain`)
and leaves margins when the proportions do not match. The `cover` prop does the
opposite: it fills the frame and crops the excess — this way photos of different
sizes line up into an even grid.

**Example — `Cover.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="bg-surface-secondary"
        src="/images/temp/ny.webp"
        alt="Люди идут по улице Нью-Йорка на закате"
        width="280"
        aspect-ratio="16/9"
      />
      <span class="text-100 text-content-secondary">По умолчанию — изображение видно целиком</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="bg-surface-secondary"
        src="/images/temp/ny.webp"
        alt="Люди идут по улице Нью-Йорка на закате"
        width="280"
        aspect-ratio="16/9"
        cover
      />
      <span class="text-100 text-content-secondary">cover — рамка заполнена, края обрезаны</span>
    </div>
  </div>
</template>
```

The `position` prop sets which part of the frame stays visible when cropping. It
accepts any `object-position` value, including pairs like `left top` and
percentages.

**Example — `Position.vue`:**

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

const positions = ['top', 'center', 'bottom'];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <div v-for="position in positions" :key="position" class="flex flex-col items-center gap-1">
      <CdsImage
        src="/images/temp/ny.webp"
        alt="Люди идут по улице Нью-Йорка на закате"
        width="220"
        aspect-ratio="16/9"
        :position="position"
        cover
      />
      <span class="text-100 text-content-secondary">position="{{ position }}"</span>
    </div>
  </div>
</template>
```

### Loading

The image starts loading when it enters the viewport — markup below the fold
does not drag dozens of files along with it. The observation thresholds are
configured by the `options` prop (the `IntersectionObserver` options), and
`eager` turns the waiting off and loads the picture right away — which is what
you should do with the images of the first screen.

While the file is on its way, the component shows `lazy-src` — a thumbnail of
the same frame, stretched and blurred — and the content of the `placeholder`
slot. The `color` prop sets the color of the backdrop under them. The `loadstart`
and `load` events report the progress of the loading.

**Example — `Loading.vue`:**

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

const pending = ref(true);

// Пока файл не доехал, вместо него показываются lazy-src и слот placeholder
const src = computed(() =>
  pending.value ? 'https://cdn.example.com/slow-image.webp' : '/images/temp/cyber-girl.webp'
);
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsButton variant="soft" color="brand" @click="pending = !pending">
      {{ pending ? 'Завершить загрузку' : 'Начать заново' }}
    </CdsButton>

    <CdsImage
      :src="src"
      lazy-src="/images/temp/thumbnail.jpg"
      alt="Девушка у панорамного окна с видом на ночной город"
      width="480"
      aspect-ratio="16/9"
      cover
    >
      <template #placeholder>
        <div class="flex h-full items-center justify-center">
          <CdsProgressCircle indeterminate />
        </div>
      </template>
    </CdsImage>
  </div>
</template>
```

### Loading error

If the file failed to open, the component shows the `error` slot and reports it
with the `error` event. Without that slot the `placeholder` stays in place of
the picture — so for an error it is better to give your own fallback with a
clear text.

**Example — `Error.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsImage } from '@central-design-system/components';
</script>

<template>
  <CdsImage
    class="m-auto"
    src="https://cdn.example.com/broken.webp"
    alt="Схема расположения складов"
    width="360"
    aspect-ratio="16/9"
    cover
  >
    <template #error>
      <div class="flex h-full flex-col items-center justify-center gap-1 bg-surface-secondary text-content-secondary">
        <CdsIcon name="error" size="lg" />
        <span class="text-100">Изображение недоступно</span>
      </div>
    </template>
  </CdsImage>
</template>
```

### Gradient

The `gradient` prop lays a CSS gradient over the image — the value is passed as
the arguments of `linear-gradient()`. Usually you need it to keep the text over
a photo readable on any frame.

**Example — `Gradient.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-6">
    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="items-end"
        src="/images/temp/villa.webp"
        alt="Вилла с бассейном в вечернем свете"
        width="280"
        aspect-ratio="16/9"
        cover
      >
        <p class="w-full p-2 text-200 text-content-on-dark">Вилла Роза, Синтра</p>
      </CdsImage>
      <span class="text-100 text-content-secondary">Без градиента</span>
    </div>

    <div class="flex flex-col items-center gap-1">
      <CdsImage
        class="items-end"
        src="/images/temp/villa.webp"
        alt="Вилла с бассейном в вечернем свете"
        width="280"
        aspect-ratio="16/9"
        gradient="to top, rgba(0, 0, 0, 0.75), transparent 55%"
        cover
      >
        <p class="w-full p-2 text-200 text-content-on-dark">Вилла Роза, Синтра</p>
      </CdsImage>
      <span class="text-100 text-content-secondary">С градиентом</span>
    </div>
  </div>
</template>
```

### Content over the image

The default slot renders above the image and stretches over the whole container:
you can put a caption, a tag or a button inside. Set the layout with utilities
on the component itself (`items-end`, `justify-center`) or through
`content-class`.

**Example — `Overlay.vue`:**

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

<template>
  <CdsImage
    class="m-auto"
    src="/images/temp/cat.webp"
    alt="Кот с разноцветной шерстью"
    width="280"
    aspect-ratio="1"
    gradient="to top, rgba(0, 0, 0, 0.7), transparent 45%"
    cover
  >
    <div class="flex h-full flex-col items-start justify-between p-2">
      <CdsTag color="green" size="sm">Новинка</CdsTag>
      <span class="text-200 text-content-on-dark">Радужный кот, холст, 40 × 60</span>
    </div>
  </CdsImage>
</template>
```

### Responsive sources

The `srcset` and `sizes` props go straight into the `img` tag — the browser
picks the file for the pixel density and the width of the place itself. When a
narrow screen needs not just a smaller file but a different frame, add `<source>`
elements into the `sources` slot: the component wraps the image into `<picture>`.
Narrow the window — in the example the wide panorama gives way to a vertical
frame.

**Example — `Sources.vue`:**

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

<template>
  <CdsImage
    class="m-auto"
    src="/images/temp/city.webp"
    alt="Панорама города на закате"
    width="100%"
    max-width="560"
    aspect-ratio="16/9"
    cover
  >
    <template #sources>
      <source media="(max-width: 700px)" srcset="/images/temp/ny.webp" />
    </template>
  </CdsImage>
</template>
```

### Slots

| Slot          | Description                                           |
| :------------ | :---------------------------------------------------- |
| `default`     | Content over the image                                |
| `placeholder` | What to show while the image is loading               |
| `error`       | What to show when the image failed to load            |
| `sources`     | `<source>` elements; wraps the image into `<picture>` |

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The same aspect-ratio and cover keep the row even, even when the sources differ in size. | Without set proportions every picture pulls its own height and the row falls apart. |
| Show diagrams, plans and logos in full — without cover. | cover crops the edges and part of the diagram is lost. |
| A gradient under the text holds the contrast on any picture. | Text placed straight on a photo blends into the light areas. |

## Scenarios

### Catalog cards

Listing covers come from different sources and almost never match in size. A
shared `aspect-ratio` and `cover` bring them to one frame, `color` holds a
neutral backdrop while the file is loading, and the default slot leaves a tag in
the corner of the cover.

**Example — `ListingCards.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardItem,
  CdsCardSubtitle,
  CdsCardTitle,
  CdsImage,
  CdsTag
} from '@central-design-system/components';

const listings = [
  {
    id: 'villa',
    src: '/images/temp/villa.webp',
    alt: 'Вилла с бассейном и садом на закате',
    tag: 'Хит',
    title: 'Вилла с бассейном',
    subtitle: 'Португалия, Синтра · 6 гостей',
    price: '18 400 ₽ за ночь'
  },
  {
    id: 'jungle',
    src: '/images/temp/airbnb.webp',
    alt: 'Деревянный дом в джунглях рядом с водопадом',
    tag: 'Новинка',
    title: 'Дом у водопада',
    subtitle: 'Бали, Убуд · 4 гостя',
    price: '9 900 ₽ за ночь'
  }
];
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsCard v-for="listing in listings" :key="listing.id" width="300">
      <CdsImage
        class="items-start"
        :src="listing.src"
        :alt="listing.alt"
        aspect-ratio="4/3"
        color="surface-secondary"
        cover
      >
        <CdsTag class="m-2" color="green" size="sm">{{ listing.tag }}</CdsTag>
      </CdsImage>

      <CdsCardItem>
        <CdsCardTitle>{{ listing.title }}</CdsCardTitle>
        <CdsCardSubtitle>{{ listing.subtitle }}</CdsCardSubtitle>
      </CdsCardItem>

      <CdsCardActions class="justify-between">
        <span class="text-200 text-content-primary">{{ listing.price }}</span>
        <CdsButton size="sm" text="Забронировать" />
      </CdsCardActions>
    </CdsCard>
  </div>
</template>
```

### Page cover

A wide header with text over a photo: `height` sets the height of the band,
`cover` and `position` crop the shot to fit it, and `gradient` darkens the
bottom so that the title and the button stay readable. Such a picture needs
`eager` — it is on the first screen and has no reason to wait for the viewport.

**Example — `HeroBanner.vue`:**

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

<template>
  <CdsImage
    class="items-end"
    src="/images/temp/wallpaper.webp"
    alt="Туман над лесным озером на рассвете"
    width="100%"
    height="280"
    gradient="to top, rgba(0, 0, 0, 0.8), rgba(0, 0, 0, 0.1) 70%"
    position="center"
    eager
    cover
  >
    <div class="flex w-full flex-col items-start gap-2 p-4">
      <p class="text-500 text-content-on-dark">Маршруты выходного дня</p>
      <p class="max-w-md text-200 text-content-on-dark opacity-80">
        Двенадцать озёр в двух часах езды от города — с картами, точками старта и списком снаряжения.
      </p>
      <CdsButton variant="solid" color="inverse" text="Открыть подборку" />
    </div>
  </CdsImage>
</template>
```

### Gallery with previews

A click on a thumbnail changes the `src` of the large image. The thumbnails get
a shared `aspect-ratio` and `cover`, so the row stays even, and `color` holds
the backdrop of the large frame while the new file is loading. If the frames
also have to be flipped — with arrows or a swipe — take the ready-made
“Gallery with thumbnails”
scenario of CdsCarousel.

**Example — `Gallery.vue`:**

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

const photos = [
  { src: '/images/temp/villa.webp', alt: 'Вилла с бассейном и садом на закате' },
  { src: '/images/temp/airbnb.webp', alt: 'Деревянный дом в джунглях рядом с водопадом' },
  { src: '/images/temp/wallpaper.webp', alt: 'Туман над лесным озером на рассвете' },
  { src: '/images/temp/desert.webp', alt: 'Столовые горы на закате' },
  { src: '/images/temp/space.webp', alt: 'Человек в скафандре под звёздным небом' }
];

const active = ref(0);
const current = computed(() => photos[active.value]);
</script>

<template>
  <div class="m-auto flex w-full max-w-[560px] flex-col gap-2">
    <CdsImage :src="current.src" :alt="current.alt" color="surface-secondary" width="100%" aspect-ratio="16/9" cover />

    <div class="flex flex-wrap gap-2">
      <button
        v-for="(photo, index) in photos"
        :key="photo.src"
        type="button"
        class="cursor-pointer overflow-hidden rounded-200 border-2"
        :class="index === active ? 'border-brand-primary' : 'border-transparent'"
        :aria-label="photo.alt"
        :aria-current="index === active"
        @click="active = index"
      >
        <CdsImage :src="photo.src" alt="" width="88" aspect-ratio="1" cover />
      </button>
    </div>
  </div>
</template>
```

## API

### CdsImage

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the image with `position: absolute`, filling its parent. |
| `alt` | `string \| undefined` | — | no | Alternative text of the image (the `alt` attribute). |
| `aspectRatio` | `string \| number \| undefined` | — | no | Aspect ratio of the content. For example `1.7778` (16/9) or `'4/3'`. |
| `color` | `string \| undefined` | — | no | Background color of the placeholder shown while loading. |
| `contentClass` | `any` | — | no | CSS class applied to the content wrapper. |
| `cover` | `boolean \| undefined` | — | no | Scales the image so that it covers the whole container (`object-fit: cover`). |
| `crossorigin` | `"" \| "anonymous" \| "use-credentials" \| undefined` | — | no | Value of the `crossorigin` attribute. |
| `draggable` | `boolean \| "true" \| "false" \| undefined` | — | no | Controls whether the image can be dragged (the `draggable` attribute). |
| `eager` | `boolean \| undefined` | — | no | Loads the image immediately instead of waiting for it to enter the viewport. |
| `gradient` | `string \| undefined` | — | no | CSS gradient laid over the image. For example `'to top, rgba(0,0,0,.4), transparent'`. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `imageClass` | `any` | — | no | CSS class applied to the inner `<img>` element. |
| `inline` | `boolean \| undefined` | — | no | Renders the component as an inline block (`inline-flex`) instead of a block one. |
| `lazySrc` | `string \| undefined` | — | no | Source of the low-quality placeholder image shown until the main one loads. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `options` | `IntersectionObserverInit \| undefined` | `{}` | no | `IntersectionObserver` options for lazy loading. |
| `position` | `string \| undefined` | — | no | Value of `object-position` that places the image inside the container. |
| `referrerpolicy` | `"origin" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url" \| undefined` | — | no | Value of the `referrerpolicy` attribute. |
| `sizes` | `string \| undefined` | — | no | Value of the `sizes` attribute for responsive images. |
| `src` | `string \| CdsImageSrcObject \| undefined` | `''` | no | Image source. A string or an object with `src`/`srcset`/`lazySrc`/`aspect`. |
| `srcset` | `string \| undefined` | — | no | Set of image sources for different resolutions (the `srcset` attribute). |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'fade-transition'` | no | Transition animation |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `error` | `[value: string \| undefined]` | Fires when the image fails to load. |
| `load` | `[value: string \| undefined]` | Fires after the image has loaded successfully. |
| `loadstart` | `[value: string \| undefined]` | Fires when the image starts loading. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content shown over the image. |
| `error` | `any` | Content shown when the image fails to load. |
| `placeholder` | `any` | Content shown while the image is loading. |
| `sources` | `any` | Extra `<source>` elements for the `<picture>` tag. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `currentSrc` | `string` | Actual address of the loaded image — taking `srcset` and the density chosen by the browser into account. |
| `image` | `HTMLImageElement \| undefined` | Reference to the `img` DOM element. |
| `naturalHeight` | `number \| undefined` | Natural height of the loaded image in pixels. |
| `naturalWidth` | `number \| undefined` | Natural width of the loaded image in pixels. |
| `state` | `"error" \| "loading" \| "idle" \| "loaded"` | Loading state of the image: idle, loading, success or error. |

---

# CdsInput

_Category: Atoms · since 4.0.0_

_Tests: API 52/52 · 59 unit · 5 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 0 axe recommendations (v4.0.0-alpha.11)_

The wrapper of an input: the label, the description, the outer icons, the block of messages and the validation by rules. You put the control itself into the `default` slot — usually a CdsField with your `input` inside.

**See also:** For regular input take the ready-made fields — CdsTextInput, CdsSelect, CdsTextArea: they are already assembled from `CdsInput` and `CdsField`. `CdsInput` is needed when your control is not in the library.

## Anatomy

`CdsInput` lays out on a grid the label (CdsLabel),
the description (CdsDescription), the outer
icons, your control and the block of messages
(CdsMessages). The `default` slot gives out `id`,
`messagesId` and the validation states — all of them are refs, so reach for
`id.value` in the template.

## Variations

### Label and description

The `label` prop names the field, `description` adds an explanation under the
label. The slots of the same names accept arbitrary markup.

**Example — `LabelAndDescription.vue`:**

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

const value = ref('');
</script>

<template>
  <CdsInput
    v-slot="{ id }"
    label="ИНН организации"
    description="10 цифр для юрлица, 12 — для ИП"
    class="w-[350px] m-auto"
  >
    <CdsField v-slot="{ props: fieldProps, focus, blur }" :id="id.value">
      <input v-bind="fieldProps" v-model="value" placeholder="0000000000" @focus="focus" @blur="blur" />
    </CdsField>
  </CdsInput>
</template>
```

### Messages and hints

There is a single line of text under the field, and the props split it by
states: `messages` is visible at rest, `hint` while `focused`, and
`error-messages` on top of the rest. `CdsInput` does not track the focus state
itself: pass it with the `focused` prop.

**Example — `Messages.vue`:**

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

const focused = ref(false);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsInput v-slot="{ id }" label="Сообщение" messages="Видно всегда">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Подсказка" hint="Видна, пока поле в фокусе" :focused="focused">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value" :focused="focused">
        <input v-bind="fieldProps" @focus="focused = true" @blur="focused = false" />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Ошибка" :error-messages="['Заполните поле']">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value" error>
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>
  </div>
</template>
```

### Hiding the details

The `hide-details` prop removes the bottom block entirely — the fields can be
placed tight against each other. The `auto` value hides the block only while
there is nothing to show.

**Example — `HideDetails.vue`:**

```vue
<script setup lang="ts">
import { CdsField, CdsInput } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsInput v-slot="{ id }" label="Блок деталей на месте">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Блок деталей скрыт" hide-details>
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Скрыт, пока нечего показать" hide-details="auto" messages="А теперь есть">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>
  </div>
</template>
```

### Icons

The `prepend-icon` and `append-icon` props put an icon outside the control.
Clicks on them are caught by `@click:prepend` and `@click:append`.

**Example — `Icons.vue`:**

```vue
<script setup lang="ts">
import { CdsField, CdsInput } from '@central-design-system/components';
</script>

<template>
  <CdsInput v-slot="{ id }" label="Дата поставки" prepend-icon="calendar" append-icon="info" class="w-[350px] m-auto">
    <CdsField v-slot="{ props: fieldProps }" :id="id.value">
      <input v-bind="fieldProps" readonly />
    </CdsField>
  </CdsInput>
</template>
```

### Direction

The `direction` prop changes the grid: `horizontal` puts the icons on the sides
of the control, `vertical` puts them above and below it.

**Example — `Direction.vue`:**

```vue
<script setup lang="ts">
import { CdsField, CdsInput } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col gap-3 w-[350px] m-auto">
    <CdsInput v-slot="{ id }" label="Горизонтально" prepend-icon="file" append-icon="info">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>

    <CdsInput v-slot="{ id }" label="Вертикально" direction="vertical" prepend-icon="file" append-icon="info">
      <CdsField v-slot="{ props: fieldProps }" :id="id.value">
        <input v-bind="fieldProps" readonly />
      </CdsField>
    </CdsInput>
  </div>
</template>
```

## Scenarios

### Validating your own field

The `rules` prop accepts validation functions, `validation-value` accepts the
value to pass to them. The result arrives in the slot through `isValid`: bind it
to the `error` prop of `CdsField` and the frame turns red together with the
message.

**Example — `CustomControl.vue`:**

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

const inn = ref('770');
const focused = ref(false);

const rules = [
  (value: string) => !!value || 'Заполните ИНН',
  (value: string) => /^\d{10}$|^\d{12}$/.test(value) || 'ИНН состоит из 10 или 12 цифр'
];
</script>

<template>
  <CdsInput
    v-slot="{ id, isValid }"
    label="ИНН организации"
    description="10 цифр для юрлица, 12 — для ИП"
    :validation-value="inn"
    :rules="rules"
    :focused="focused"
    class="w-[350px] m-auto"
  >
    <CdsField
      v-slot="{ props: fieldProps }"
      :id="id.value"
      :error="isValid.value === false"
      :focused="focused"
      :dirty="!!inn"
      prepend-inner-icon="company"
      clearable
      @click:clear="inn = ''"
    >
      <input
        v-bind="fieldProps"
        v-model="inn"
        placeholder="0000000000"
        @focus="focused = true"
        @blur="focused = false"
      />
    </CdsField>
  </CdsInput>
</template>
```

## API

### CdsInput

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `color` | `string \| undefined` | — | no | Component color |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `any` | — | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: any]` | Fires when the model of the component changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `default` | `CdsInputSlot` | Default slot |
| `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 |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsLabel

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 7/7 · 10 unit · 2 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A label names a field — it says what is expected from the user. It renders as a `label` tag and binds to the control through `for`, so a click on the label moves the focus into the field.

**See also:** The ready-made fields already have the label built in — the `label` prop of CdsTextInput and the other controls. A standalone `CdsLabel` is needed for groups of fields and for your own controls. The explanation under the label is added by CdsDescription.

## Variations

### Text

The `text` prop sets the caption. The `default` slot accepts arbitrary markup —
an icon with an explanation next to the text, for example.

**Example — `Text.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsLabel } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsLabel text="Название организации" />

    <CdsLabel>
      Название организации
      <CdsIcon icon="info" size="sm" end />
    </CdsLabel>
  </div>
</template>
```

### States

The `disabled` and `readonly` props mute the label together with the field: both
stop reacting to a click, and `disabled` also changes the color.

**Example — `States.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsLabel text="Обычная метка" />
    <CdsLabel text="Метка заблокированного поля" disabled />
    <CdsLabel text="Метка поля только для чтения" readonly />
  </div>
</template>
```

## Scenarios

### A label for your own control

The `for` prop takes the `id` of the control — the browser binds them itself: a
click on the label sets the focus, and the screen reader reads the caption
together with the field.

**Example — `CustomControl.vue`:**

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

const agreed = ref(false);
</script>

<template>
  <div class="flex items-center gap-1">
    <input id="agreement" v-model="agreed" type="checkbox" />

    <CdsLabel for="agreement" text="Согласен с условиями обработки данных" />
  </div>
</template>
```

## API

### CdsLabel

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `for` | `string \| undefined` | — | no | Identifier of the field the label belongs to — the value of the `for` HTML attribute |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Text of the label for the field |

---

# CdsLayout

_Category: Layouts · since 4.0.0_

_Tests: API 22/22 · 31 unit · 1 known bug · lines 85.6% (v4.0.0-alpha.13) · a11y: 13 axe recommendations (v4.0.0-alpha.11)_

The frame of the application: `CdsLayout` places the header, the side drawers, the content and the footer, measures their sizes and takes the scrolling over. The parts of the layout know about each other — the content never slides under the header and never hides behind a drawer.

**See also:** The parts of the layout are described on their own pages: CdsHeader, CdsDrawer, CdsMain, CdsPage, CdsFooter and CdsToolbar. You can assemble the frame with the mouse and copy the ready code in the layout builder.

## Anatomy

`CdsLayout` is the root element of the application. The parts of the layout go
inside it: the header, the drawers, `CdsMain` with `CdsPage` and the footer. The
order in the template does not matter — the layout calculates the positions
itself.

## Variations

### The view scheme

The `view` prop describes the layout with three strings: top, middle, bottom.
The letters are the parts of the layout: `h` — the header, `f` — the footer, `l`
and `r` — the left and the right drawer, `p` — the page. The corner letters of
the top and the bottom string settle the argument over the corners: `hhh` gives
the whole width to the header, `lhh` gives the top left corner to the drawer.

**Example — `View.vue`:**

```vue
<script setup lang="ts">
import {
  CdsDrawer,
  CdsFooter,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const view = ref('hhh lpr fff');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="view" direction="horizontal" hide-details>
      <CdsRadio value="hhh lpr fff" label="hhh lpr fff" />
      <CdsRadio value="lhh lpr lff" label="lhh lpr lff" />
      <CdsRadio value="lhh lpr fff" label="lhh lpr fff" />
    </CdsRadioGroup>

    <div class="h-[520px]">
      <CdsLayout container :view="view">
        <CdsHeader bordered>
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsDrawer permanent border>
          <CdsList>
            <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
            <CdsListItem title="Договоры" href="#" prepend-icon="file" />
            <CdsListItem title="Контрагенты" href="#" prepend-icon="company" />
          </CdsList>
        </CdsDrawer>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Схема <code>{{ view }}</code>
            </div>
          </CdsPage>
        </CdsMain>

        <CdsFooter bordered :height="40">
          <div class="flex h-[40px] items-center px-4 text-content-secondary">Подвал</div>
        </CdsFooter>
      </CdsLayout>
    </div>
  </div>
</template>
```

An uppercase letter gives the part `position: fixed`: `HHH lpr fff` nails the
header to the window, `hhh LPR fff` nails both drawers. The default value is
`hhh lpr fff`.

### Container mode

By default the layout takes the whole page and controls its scrolling. The
`container` prop locks it inside its parent: the layout gets its own scroll
area, and the header and the footer keep their places inside it. This is a handy
way to show the application in a preview, to embed it into somebody else's page
or to build a working area of a fixed height.

**Example — `ContainerMode.vue`:**

```vue
<script setup lang="ts">
import {
  CdsFooter,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[520px] overflow-hidden rounded-200 border border-line-primary">
    <CdsLayout container>
      <CdsHeader elevated>
        <CdsToolbar>
          <CdsToolbarTitle>Шапка остаётся на месте</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="flex flex-col gap-2">
            <div v-for="n in 12" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Блок {{ n }} — прокрутите область, страница за ней не двигается
            </div>
          </div>
        </CdsPage>
      </CdsMain>

      <CdsFooter elevated :height="40">
        <div class="flex h-[40px] items-center px-4 text-content-secondary">Подвал</div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

### Events

The layout watches its scroll area and shares what it sees: `@scroll` gives the
position, the direction and the turning point, `@resize` gives the new sizes,
`@scroll-height` gives the height of the content. The floating header and footer
are built on these events, but you can use them for your own logic too — to load
the next page of a list, for example.

**Example — `Events.vue`:**

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

const top = ref(0);
const direction = ref<'up' | 'down' | 'left' | 'right'>('down');
const size = ref({ width: 0, height: 0 });
</script>

<template>
  <div class="h-[520px]">
    <CdsLayout
      container
      @scroll="
        top = $event.position.top;
        direction = $event.direction;
      "
      @resize="size = $event"
    >
      <CdsMain>
        <CdsPage padding>
          <div class="mb-2 rounded-200 bg-surface-secondary p-4 text-content-primary">
            Прокручено: {{ Math.round(top) }} px · направление: {{ direction === 'down' ? 'вниз' : 'вверх' }} · ширина
            содержимого: {{ Math.round(size.width) }} px
          </div>
          <div class="flex flex-col gap-2">
            <div v-for="n in 15" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-secondary">
              Блок {{ n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The content lives in CdsMain → CdsPage: the layout reserves the space for the header and the drawers itself. | Content placed directly inside CdsLayout slides under the header — nobody calculates the paddings. |
| The sections of the application belong in the side drawer: the list grows downwards and stays readable. | With every section in the header, they shrink as their number grows and stop fitting. |

## Scenarios

### Application shell

The typical set: a header with `CdsToolbar`, permanent navigation in
`CdsDrawer`, `CdsMain` → `CdsPage` with the content and a footer. A button in
the header toggles `minified` — the drawer shrinks to icons and gives the width
to the content, and on hover it expands back.

**Example — `AppShell.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardSubtitle,
  CdsCardText,
  CdsCardTitle,
  CdsDrawer,
  CdsFooter,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsLink,
  CdsList,
  CdsListGroup,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const minified = ref(false);
const stats = [
  { title: 'Активные закупки', value: '128', hint: '+12 за неделю' },
  { title: 'Заявки на рассмотрении', value: '34', hint: '8 требуют действия' },
  { title: 'Поставщики', value: '512', hint: '+5 новых' },
  { title: 'Сообщения', value: '17', hint: '3 непрочитанных' }
];
</script>

<template>
  <div class="h-[640px]">
    <CdsLayout container>
      <CdsHeader bordered elevated :height="64">
        <CdsToolbar>
          <CdsFunctionalButton icon="menu" class="mr-2" aria-label="Свернуть навигацию" @click="minified = !minified" />
          <CdsAvatar icon="company" class="mr-2" />
          <CdsToolbarTitle>Портал закупок</CdsToolbarTitle>

          <CdsFunctionalButton icon="search" aria-label="Поиск" />
          <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
          <CdsAvatar icon="user" class="ml-2" />
        </CdsToolbar>
      </CdsHeader>

      <CdsDrawer permanent border :minified="minified">
        <CdsList>
          <CdsListItem title="Дашборд" href="#" prepend-icon="tree" active />
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" />
          <CdsListItem title="Заявки" href="#" prepend-icon="file" />
          <CdsListGroup>
            <template #activator="{ props }">
              <CdsListItem title="Контрагенты" prepend-icon="company" v-bind="props" />
            </template>
            <CdsListItem title="Поставщики" href="#" prepend-icon="user-group" />
            <CdsListItem title="Заказчики" href="#" prepend-icon="user" />
          </CdsListGroup>
          <CdsListItem title="Аналитика" href="#" prepend-icon="view-rows" />
          <CdsListItem title="Настройки" href="#" prepend-icon="settings" />
        </CdsList>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <CdsToolbar class="mb-4 gap-4 rounded-200">
            <CdsToolbarTitle class="text-xl font-bold">Дашборд</CdsToolbarTitle>
            <CdsButton variant="soft" color="neutral" prepend-icon="adjust">Фильтры</CdsButton>
            <CdsButton prepend-icon="add">Создать закупку</CdsButton>
          </CdsToolbar>

          <div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
            <CdsCard v-for="stat in stats" :key="stat.title" class="p-4">
              <CdsCardSubtitle>{{ stat.title }}</CdsCardSubtitle>
              <CdsCardTitle class="text-2xl font-bold">{{ stat.value }}</CdsCardTitle>
              <CdsCardText class="text-content-secondary">{{ stat.hint }}</CdsCardText>
            </CdsCard>
          </div>

          <CdsCard class="mt-4 p-4">
            <CdsCardTitle>Последние закупки</CdsCardTitle>
            <CdsCardText>
              Прокрутите страницу, чтобы увидеть, как шапка и подвал остаются на месте, а содержимое страницы скроллится
              внутри макета.
            </CdsCardText>
            <CdsList>
              <CdsListItem
                v-for="n in 12"
                :key="n"
                :title="'Закупка №' + (1000 + n)"
                :subtitle="'Поставщик ООО «Компания ' + n + '»'"
                href="#"
                prepend-icon="shopping-cart"
                append-icon="chevron-right"
              />
            </CdsList>
            <CdsCardActions class="justify-end">
              <CdsButton variant="soft" color="neutral">Показать все</CdsButton>
            </CdsCardActions>
          </CdsCard>
        </CdsPage>
      </CdsMain>

      <CdsFooter bordered :height="48">
        <div class="flex h-[48px] items-center justify-between px-4">
          <span class="text-content-secondary">© 2026 Портал закупок</span>
          <span class="flex items-center gap-4">
            <CdsLink href="#">Помощь</CdsLink>
            <CdsLink href="#">Конфиденциальность</CdsLink>
          </span>
        </div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

### A header that hides on scroll

On long lists the space is worth more than the navigation. The `reveal` prop of
the header and the footer hides them when scrolling down and brings them back
when scrolling up; `reveal-offset` sets the zone near the top of the list where
the header stays in place.

**Example — `RevealOnScroll.vue`:**

```vue
<script setup lang="ts">
import {
  CdsFooter,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const revealed = ref(true);
</script>

<template>
  <div class="h-[500px]">
    <CdsLayout container>
      <CdsHeader reveal elevated :reveal-offset="80" @reveal="revealed = $event">
        <CdsToolbar>
          <CdsToolbarTitle>Каталог поставщиков</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="mb-2 text-content-secondary">
            Шапка {{ revealed ? 'видна' : 'скрыта' }} — прокрутите вниз, чтобы освободить место списку, и вверх, чтобы
            вернуть её.
          </div>
          <div class="flex flex-col gap-2">
            <div v-for="n in 20" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Поставщик №{{ n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>

      <CdsFooter reveal elevated :height="40">
        <div class="flex h-[40px] items-center px-4 text-content-secondary">Найдено 20 поставщиков</div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

### Working area with filters

The `lhh lpr fff` scheme gives the top left corner to the navigation — it starts
from the very top, and the header takes the remaining width. The right drawer
with `temporary` slides over the content on a button click and closes on a click
on the overlay, so it takes no place in the layout.

**Example — `WorkArea.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCheckbox,
  CdsDrawer,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const filters = ref(false);
const statuses = ref<string[]>(['active']);
</script>

<template>
  <div class="h-[520px]">
    <CdsLayout container view="lhh lpr fff">
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
          <CdsButton variant="soft" color="neutral" prepend-icon="adjust" @click="filters = !filters"
            >Фильтры</CdsButton
          >
        </CdsToolbar>
      </CdsHeader>

      <CdsDrawer permanent border>
        <CdsList>
          <CdsListItem title="Все закупки" href="#" prepend-icon="shopping-cart" active />
          <CdsListItem title="Избранное" href="#" prepend-icon="star" />
          <CdsListItem title="Архив" href="#" prepend-icon="archive" />
        </CdsList>
      </CdsDrawer>

      <CdsDrawer v-model="filters" right temporary border>
        <template #prepend>
          <div class="font-bold text-content-primary">Фильтры</div>
        </template>

        <div class="flex flex-col gap-1">
          <CdsCheckbox v-model="statuses" value="active" label="Активные" hide-details />
          <CdsCheckbox v-model="statuses" value="draft" label="Черновики" hide-details />
          <CdsCheckbox v-model="statuses" value="done" label="Завершённые" hide-details />
        </div>

        <template #append>
          <CdsButton block @click="filters = false">Применить</CdsButton>
        </template>
      </CdsDrawer>

      <CdsMain>
        <CdsPage padding>
          <div class="flex flex-col gap-2">
            <div v-for="n in 8" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Закупка №{{ 2400 + n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsLayout

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `container` | `boolean \| undefined` | `false` | no | Container mode: the layout scrolls inside itself instead of scrolling the page. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `view` | `string \| undefined` | `'hhh lpr fff'` | no | Layout scheme of three strings: top (header), middle (left-page-right), bottom (footer). For example `'hhh lpr fff'`. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `resize` | `[contentRect: Pick<DOMRectReadOnly, "width" \| "height">]` | The size of the layout area has changed. |
| `scroll` | `[info: ScrollObserver]` | The layout area has been scrolled. |
| `scrollHeight` | `[height: number]` | The height of the scrollable content has changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the layout: `CdsHeader`, `CdsDrawer`, `CdsMain`, `CdsFooter`. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `animate` | `() => void` | Turns on the rebuild animation of the layout for the duration of the next size update. |
| `containerHeight` | `number` | Height of the content area without the header and the footer, in pixels. |
| `footer` | `LayoutPart` | Size and offset of the layout footer. |
| `header` | `LayoutPart` | Size and offset of the layout header. |
| `height` | `number` | Full height of the layout in pixels. |
| `instances` | `Record<string, unknown>` | Components registered in the layout by their identifiers — the header, the footer, the drawers, the content. |
| `isContainer` | `boolean` | Whether the layout is limited in width by a container (`container`) instead of stretching across the whole screen. |
| `left` | `LayoutPart` | Size and offset of the left drawer of the layout. |
| `right` | `LayoutPart` | Size and offset of the right drawer of the layout. |
| `rootRef` | `HTMLElement \| undefined` | Ref to the root DOM element of the layout. |
| `rows` | `{ top: string[]; middle: string[]; bottom: string[]; }` | Identifiers of the components distributed across the rows of the layout: top, middle and bottom. |
| `scroll` | `ScrollObserver` | Scroll state of the layout: position, direction and delta. |
| `scrollbarWidth` | `number` | Width of the system scrollbar in pixels — taken into account when the scroll is locked. |
| `totalWidth` | `number` | Full width of the layout in pixels. |
| `update` | `(part: "left" \| "right" \| "footer" \| "header", prop: keyof LayoutPart, value: number \| boolean) => void` | Updates the size, the offset or the space reservation for a part of the layout. |

---

# CdsLink

_Category: Navigation · since 4.0.0_

_Tests: API 10/10 · 19 unit · 2 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 7 axe recommendations (v4.0.0-alpha.11)_

A link sends the user somewhere else: to a neighboring page of the application, to an external service or to an email address. Inside the application the path comes from the `to` prop and vue-router takes over the navigation; for outside destinations the address goes into `href`.

**See also:** If the element triggers an action instead of a navigation — saves, deletes, opens a modal — take CdsButton. A button also accepts `href` or `to` when a navigation has to look like a button. The path through the hierarchy of sections is built by CdsBreadcrumbs, and sections of equal weight are switched by CdsTabs.

## Variations

### Link text

The `text` prop sets the label as a string, the `default` slot as arbitrary
markup — text with an icon, for example. The slot wins over the prop.

**Example — `Content.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsLink } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsLink href="#" text="Текст из пропа text" />

    <CdsLink href="#">Контент из слота default</CdsLink>

    <CdsLink href="#">
      <CdsIcon icon="file-download" :size="16" start />
      Скачать спецификацию
    </CdsLink>
  </div>
</template>
```

### Address

The `href` prop renders a regular link. Attributes are written on the component
just like on an `a` tag: `target="_blank"` opens the page in a new tab — mark
such a link with an icon so that leaving the application does not come as a
surprise. Visited links change color; anchors like `#section` stay as they are.

**Example — `Href.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsLink } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsLink href="https://www.b2b-center.ru" text="Открыть сайт b2b-center.ru" />

    <CdsLink href="https://www.b2b-center.ru" target="_blank" rel="noopener">
      Открыть в новой вкладке
      <CdsIcon icon="external-link" :size="16" end />
    </CdsLink>
  </div>
</template>
```

### Application route

The `to` prop accepts a path or a vue-router route object: the navigation runs
without a page reload, and on the active route the link gets
`aria-current="page"`. The `replace` prop replaces the current history entry
instead of adding a new one — so going "back" skips the intermediate screen. The
`exact` prop treats the route as active only on a full match, not by prefix.

```vue
<CdsLink to="/profile" text="Профиль" />
<CdsLink :to="{ name: 'order', params: { id } }" exact text="Заказ" />
<CdsLink to="/login" replace text="Войти" />
```

### Disabled link

The `disabled` prop dims the color and removes the navigation: the component
cancels the click, sets `aria-disabled` and takes the link out of the Tab order.
Explain nearby why the navigation is unavailable — the gray state alone does not
name the reason.

**Example — `Disabled.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsLink href="https://www.b2b-center.ru" text="Доступная ссылка" />

    <CdsLink href="https://www.b2b-center.ru" disabled text="Недоступная ссылка" />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The link text names where it leads — clear even outside the paragraph. | «Здесь» и «подробнее» ничего не обещают: цель перехода приходится угадывать. |
| A link leads to a page, a button triggers an action. | A link that deletes data betrays the expectation of a navigation. |
| The link is a short phrase inside the sentence; the rest of the text stays text. | A whole paragraph inside a link is hard to read, and the destination gets lost in the details. |

## Scenarios

### A link inside text

Inside a paragraph the link covers exactly the phrase that names the
destination. A `@click.prevent` handler keeps the user on the page and reveals
the details in place, while `href="mailto:…"` opens the mail client.

**Example — `InlineText.vue`:**

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

const expanded = ref(false);
</script>

<template>
  <div class="m-auto w-[420px] max-w-full">
    <p class="m-0">
      Заявка уходит на проверку сразу после отправки. Порядок рассмотрения описан в
      <CdsLink href="#" text="регламенте закупок" @click.prevent="expanded = !expanded" />, а вопросы принимает
      <CdsLink href="mailto:support@example.com" text="служба поддержки" />.
    </p>

    <p v-if="expanded" class="mt-3 mb-0">
      Заявку проверяют три рабочих дня. Если данных не хватает, вы получите письмо с уточнениями и дополните заявку без
      повторной подачи.
    </p>
  </div>
</template>
```

### Result list

The titles of the found documents are links: the user scans the list and opens
the one they need. The text comes from the `text` prop, and the `click` handler
shows the selected document without leaving the page.

**Example — `SearchResults.vue`:**

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

const documents = [
  'Регламент закупок',
  'Договор поставки № 114',
  'Акт сверки за II квартал',
  'Спецификация оборудования',
  'Протокол разногласий'
];

const query = ref('');
const opened = ref<string | null>(null);

const results = computed(() =>
  documents.filter((title) => title.toLowerCase().includes(query.value.trim().toLowerCase()))
);
</script>

<template>
  <div class="m-auto flex w-[350px] max-w-full flex-col gap-2">
    <CdsTextInput v-model="query" label="Поиск по документам" placeholder="Введите название" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="title in results" :key="title">
        <CdsLink href="#" :text="title" @click.prevent="opened = title" />
      </li>
      <li v-if="!results.length">Ничего не нашлось — измените запрос.</li>
    </ul>

    <p v-if="opened" class="m-0">Открыт документ «{{ opened }}».</p>
  </div>
</template>
```

### Documents with restricted access

The list shows all the documents of a procedure, but some of them are closed:
`disabled` keeps their titles visible and blocks the navigation. The request
access button lifts the restriction — the links come alive without reloading the
list.

**Example — `Restricted.vue`:**

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

const documents = [
  { title: 'Извещение о закупке', restricted: false },
  { title: 'Техническое задание', restricted: false },
  { title: 'Смета проекта', restricted: true },
  { title: 'Протокол комиссии', restricted: true }
];

const granted = ref(false);
const requesting = ref(false);

function requestAccess() {
  requesting.value = true;

  setTimeout(() => {
    requesting.value = false;
    granted.value = true;
  }, 1000);
}
</script>

<template>
  <div class="m-auto flex w-[350px] max-w-full flex-col gap-2">
    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="document in documents" :key="document.title">
        <CdsLink href="#" :disabled="document.restricted && !granted" :text="document.title" @click.prevent />
      </li>
    </ul>

    <template v-if="!granted">
      <p class="m-0">Смета и протокол открыты только участникам процедуры.</p>

      <CdsButton variant="soft" color="brand" text="Запросить доступ" :loading="requesting" @click="requestAccess" />
    </template>
  </div>
</template>
```

## API

### CdsLink

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `disabled` | `boolean \| undefined` | — | no | Disables the link: no navigation happens, aria-disabled and tabindex=-1 are set |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click` | `[e: MouseEvent]` | Click on the link |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Link content. Takes precedence over the text prop. |

---

# CdsList

_Category: Content · since 4.0.0_

_Tests: API 164/164 · 190 unit · 5 e2e · 15 known bugs · lines 98.3% (v4.0.0-alpha.13) · a11y: 35 axe recommendations (v4.0.0-alpha.11)_

A list shows a set of records of the same kind — menu sections, documents, employees, settings — so that the one you need is easy to find and pick. Build it from an `items` array in a single line, or from `CdsListItem` components when a row is more than a title with an icon.

**See also:** To pick a value in a form, take CdsSelect; for a tree with checkboxes, async loading and drag and drop — CdsTree; for tabular data with columns — CdsTable. Inside CdsMenu, CdsSelect and CdsAutocomplete the list is already in use — there is no need to assemble it by hand.

## Anatomy

The first diagram is the skeleton of a list: subheaders split it into sections,
dividers separate blocks, groups reveal nested items. The second one is the
structure of an item: the `prepend` and `append` areas on the sides and three
text blocks between them. Every area is available both as a prop
(`prepend-icon`, `title`) and as a slot of the same name.

## Variations

### List data

The `items` prop takes an array of objects and builds the whole list out of it.
The `title` field gives the heading, `value` — the value of the item (this is
how the list knows what is selected), `props` — any props of `CdsListItem`.

**Example — `Items.vue`:**

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

const items = [
  { title: 'Профиль', value: 'profile', props: { prependIcon: 'user' } },
  { title: 'Организация', value: 'company', props: { prependIcon: 'company' } },
  { title: 'Сотрудники', value: 'employees', props: { prependIcon: 'user-group' } },
  { title: 'Настройки', value: 'settings', props: { prependIcon: 'settings' } }
];
</script>

<template>
  <CdsList class="m-auto w-[200px]" :items="items" />
</template>
```

When the data arrives from the server in its own format, do not reshape it:
`item-title`, `item-value` and `item-children` tell the list which fields to
take. Each of them accepts both a field name and a function — that way, for
example, `item-props` assembles the props of an item from several fields of the
object.

**Example — `CustomItems.vue`:**

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

const employees = [
  { id: 1, name: 'Анна Смирнова', role: 'Руководитель отдела закупок' },
  { id: 2, name: 'Дмитрий Орлов', role: 'Менеджер по тендерам' },
  { id: 3, name: 'Елена Васильева', role: 'Юрист' },
  { id: 4, name: 'Игорь Крылов', role: 'Бухгалтер' }
];
</script>

<template>
  <CdsList
    class="m-auto w-[250px]"
    :items="employees"
    item-title="name"
    item-value="id"
    :item-props="(item: Record<string, any>) => ({ subtitle: item.role, prependIcon: 'user' })"
    lines="two"
  />
</template>
```

The `props` field configures a single item: adds icons, turns on the active
state or disables the row.

**Example — `ItemProps.vue`:**

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

const items = [
  { title: 'Черновик', value: 'draft', props: { prependIcon: 'file' } },
  { title: 'На согласовании', value: 'review', props: { prependIcon: 'time', appendIcon: 'chevron-right' } },
  { title: 'Опубликован', value: 'published', props: { prependIcon: 'check', active: true } },
  { title: 'В архиве', value: 'archived', props: { prependIcon: 'archive', disabled: true } }
];
</script>

<template>
  <CdsList class="m-auto w-[280px]" :items="items" />
</template>
```

### Item content

An item has three text blocks: `title` names the record, `subtitle` refines it,
`description` adds an explanation. On the sides stand an icon (`prepend-icon`,
`append-icon`) or an avatar (`prepend-avatar`, `append-avatar`).

**Example — `ItemContent.vue`:**

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

<template>
  <CdsList class="m-auto w-[360px]" :lines="false">
    <CdsListItem prepend-icon="file" title="Счёт на оплату № 5512" />

    <CdsListItem prepend-icon="file" title="Договор аренды № 17" subtitle="ООО «Ромашка»" />

    <CdsListItem
      prepend-icon="file"
      append-icon="chevron-right"
      title="Акт сверки за март"
      subtitle="ООО «Ромашка»"
      description="Ожидает подписания второй стороной"
    />

    <CdsListItem
      prepend-avatar="https://i.pravatar.cc/80?img=47"
      title="Анна Смирнова"
      subtitle="Руководитель отдела закупок"
    />
  </CdsList>
</template>
```

The `lines` prop limits the subtitle and the description to one, two or three
lines — the rest of the text is truncated with an ellipsis, and records with
text of different length keep a common rhythm. With `three`, the icons in the
`prepend` and `append` areas align to the top of the record instead of its
center. `:lines="false"` removes the limit — the text takes as many lines as it
needs.

**Example — `Lines.vue`:**

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

const lines = ['one', 'two', 'three'] as const;

const items = [
  {
    title: 'Договор поставки № 42 от 14 марта',
    value: 'supply',
    props: {
      prependIcon: 'file',
      subtitle:
        'ООО «Ромашка» · поставка канцелярии и расходных материалов для филиалов в Москве и Санкт-Петербурге до конца квартала'
    }
  },
  {
    title: 'Акт сверки взаиморасчётов за март',
    value: 'act',
    props: {
      prependIcon: 'file',
      subtitle: 'ООО «Василёк» · расхождений не выявлено, подписан обеими сторонами 12 марта'
    }
  }
];
</script>

<template>
  <div class="m-auto flex flex-wrap justify-center gap-4">
    <div v-for="line of lines" :key="line" class="flex w-[280px] flex-col gap-1">
      <span class="text-100 text-content-secondary">lines="{{ line }}"</span>
      <CdsList :items="items" :lines="line" />
    </div>
  </div>
</template>
```

### Structure

Items with `type: 'subheader'` and `type: 'divider'` split the list into
sections: a subheader names a group of records, a divider separates blocks
without a heading.

**Example — `SubheaderAndDivider.vue`:**

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

const items = [
  { type: 'subheader', title: 'Сегодня' },
  { title: 'Договор поставки № 42', value: 'supply', props: { prependIcon: 'file' } },
  { title: 'Счёт на оплату № 5512', value: 'invoice', props: { prependIcon: 'file' } },
  { type: 'divider' },
  { type: 'subheader', title: 'На прошлой неделе' },
  { title: 'Акт сверки за март', value: 'act', props: { prependIcon: 'file' } },
  { title: 'Договор аренды № 17', value: 'rent', props: { prependIcon: 'file' } },
  { title: 'Спецификация № 3', value: 'spec', props: { prependIcon: 'file' } }
];
</script>

<template>
  <CdsList class="m-auto w-[250px]" :items="items" />
</template>
```

A `children` array inside an item turns it into an expandable group — the list
manages its state on its own, and `v-model:opened` lets you manage it from the
outside. Nesting is not limited to a single level.

**Example — `Nested.vue`:**

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

const opened = ref(['contracts']);

const items = [
  { title: 'Все документы', value: 'all', props: { prependIcon: 'folder' } },
  {
    title: 'Договоры',
    value: 'contracts',
    props: { prependIcon: 'folder' },
    children: [
      { title: 'Поставка', value: 'supply', props: { prependIcon: 'file' } },
      { title: 'Аренда', value: 'rent', props: { prependIcon: 'file' } },
      {
        title: 'Услуги',
        value: 'services',
        props: { prependIcon: 'folder' },
        children: [
          { title: 'Разовые', value: 'services-single', props: { prependIcon: 'file' } },
          { title: 'Абонентские', value: 'services-regular', props: { prependIcon: 'file' } }
        ]
      }
    ]
  },
  {
    title: 'Бухгалтерия',
    value: 'accounting',
    props: { prependIcon: 'folder' },
    children: [
      { title: 'Счета', value: 'invoices', props: { prependIcon: 'file' } },
      { title: 'Акты сверки', value: 'acts', props: { prependIcon: 'file' } }
    ]
  }
];
</script>

<template>
  <CdsList v-model:opened="opened" class="m-auto w-[250px]" :items="items" />
</template>
```

### Selection and activation

The `activatable` prop highlights one item as the current one — this is about
navigation: "you are here". `selectable` turns on picking records — this is
about data: "send these ones". Both states are read through
`v-model:activated` and `v-model:selected`, and `select-strategy` sets how many
items can be picked at once: `single-leaf` (the default) — one,
`independent` — as many as you like.

**Example — `Selection.vue`:**

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

const items = [
  { title: 'Договоры', value: 'contracts' },
  { title: 'Счета', value: 'invoices' },
  { title: 'Акты сверки', value: 'acts' },
  { title: 'Отчёты', value: 'reports' }
];

const activated = ref(['contracts']);
const selected = ref(['invoices', 'acts']);
</script>

<template>
  <div class="m-auto flex flex-wrap justify-center gap-4">
    <div class="flex w-[260px] flex-col gap-1">
      <span class="text-100 text-content-secondary">activatable — один активный элемент</span>
      <CdsList v-model:activated="activated" activatable :items="items" />
      <span class="text-100 text-content-secondary">activated: {{ activated }}</span>
    </div>

    <div class="flex w-[260px] flex-col gap-1">
      <span class="text-100 text-content-secondary">selectable + select-strategy="independent"</span>
      <CdsList v-model:selected="selected" selectable select-strategy="independent" :items="items" />
      <span class="text-100 text-content-secondary">selected: {{ selected }}</span>
    </div>
  </div>
</template>
```

### Appearance

`nav` rounds the corners of active items — the look of a side menu. `slim`
removes the inner paddings when the list sits in a narrow panel or a dropdown.
`color` sets the color of active items, `bg-color` — the background of the list.

**Example — `Appearance.vue`:**

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

const items = [
  { title: 'Профиль', value: 'profile', props: { prependIcon: 'user' } },
  { title: 'Организация', value: 'company', props: { prependIcon: 'company', active: true } },
  { title: 'Настройки', value: 'settings', props: { prependIcon: 'settings' } }
];
</script>

<template>
  <div class="m-auto flex flex-wrap justify-center gap-4">
    <div class="flex w-[240px] flex-col gap-1">
      <span class="text-100 text-content-secondary">по умолчанию</span>
      <CdsList :items="items" />
    </div>

    <div class="flex w-[240px] flex-col gap-1">
      <span class="text-100 text-content-secondary">nav</span>
      <CdsList nav :items="items" />
    </div>

    <div class="flex w-[240px] flex-col gap-1">
      <span class="text-100 text-content-secondary">slim</span>
      <CdsList slim :items="items" />
    </div>

    <div class="flex w-[240px] flex-col gap-1">
      <span class="text-100 text-content-secondary">color="brand-primary"</span>
      <CdsList color="brand-primary" :items="items" />
    </div>
  </div>
</template>
```

### Assembling from components

When a row is more than a title with an icon, assemble it from `CdsListItem` by
hand — the slots accept any components: tags, badges, avatars, buttons.

| Slot name     | Description                                         |
| :------------ | :-------------------------------------------------- |
| `prepend`     | Content of the area before the text                 |
| `title`       | Content of the heading (replaces `title`)           |
| `subtitle`    | Content of the subtitle (replaces `subtitle`)       |
| `description` | Content of the description (replaces `description`) |
| `append`      | Content of the area after the text                  |
| `default`     | Arbitrary markup inside the item, below the text    |

**Example — `Slots.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsBadge,
  CdsFunctionalButton,
  CdsIcon,
  CdsList,
  CdsListItem,
  CdsTag
} from '@central-design-system/components';
</script>

<template>
  <CdsList class="m-auto w-[300px]" lines="two">
    <CdsListItem value="supply">
      <template #prepend>
        <CdsIcon name="file" />
      </template>
      <template #title>Договор поставки № 42</template>
      <template #subtitle>ООО «Ромашка»</template>
      <template #append>
        <CdsTag size="sm" text="Подписан" color="green" />
      </template>
    </CdsListItem>

    <CdsListItem value="act">
      <template #prepend>
        <CdsIcon name="file" />
      </template>
      <template #title>Акт сверки за март</template>
      <template #subtitle>ООО «Василёк»</template>
      <template #append>
        <CdsBadge inline content="3" />
      </template>
    </CdsListItem>

    <CdsListItem value="manager">
      <template #prepend>
        <CdsAvatar size="sm" image="https://i.pravatar.cc/80?img=47" />
      </template>
      <template #title>Анна Смирнова</template>
      <template #subtitle>Ответственная за закупку</template>
      <template #append>
        <CdsFunctionalButton icon="more-vertical" aria-label="Ещё" />
      </template>
    </CdsListItem>
  </CdsList>
</template>
```

Nesting in this mode is assembled with `CdsListGroup`: the `activator` slot
gives the heading of the group, the default content — the nested items. The
`subgroup` prop marks a group of the third level and deeper — the expand arrow
moves to the start of the row.

The group passes the arrow to the activator as the default value for
`append-icon`, and the `append` slot replaces that area entirely — so with your
own content the arrow disappears. Bring it back with an empty `<CdsIcon />`
next to it: the icon picks up the direction of the arrow from the defaults of
the group and keeps toggling on expand.

**Example — `NestedSlots.vue`:**

```vue
<script setup lang="ts">
import { CdsBadge, CdsIcon, CdsList, CdsListGroup, CdsListItem } from '@central-design-system/components';
</script>

<template>
  <CdsList class="m-auto w-[250px]">
    <CdsListItem value="all">
      <template #prepend>
        <CdsIcon name="folder" />
      </template>
      <template #title>Все документы</template>
    </CdsListItem>

    <CdsListGroup value="contracts">
      <template #activator="{ props }">
        <CdsListItem v-bind="props" value="contracts">
          <template #prepend>
            <CdsIcon name="folder" />
          </template>
          <template #title>Договоры</template>
          <template #append>
            <CdsBadge class="mr-2" inline content="12" />
            <CdsIcon />
          </template>
        </CdsListItem>
      </template>

      <CdsListItem value="supply">
        <template #prepend>
          <CdsIcon name="file" />
        </template>
        <template #title>Поставка</template>
      </CdsListItem>

      <CdsListItem value="rent">
        <template #prepend>
          <CdsIcon name="file" />
        </template>
        <template #title>Аренда</template>
      </CdsListItem>

      <CdsListGroup value="services" subgroup>
        <template #activator="{ props }">
          <CdsListItem v-bind="props" value="services">
            <template #title>Услуги</template>
          </CdsListItem>
        </template>

        <CdsListItem value="services-single">
          <template #prepend>
            <CdsIcon name="file" />
          </template>
          <template #title>Разовые</template>
        </CdsListItem>

        <CdsListItem value="services-regular">
          <template #prepend>
            <CdsIcon name="file" />
          </template>
          <template #title>Абонентские</template>
        </CdsListItem>
      </CdsListGroup>
    </CdsListGroup>

    <CdsListGroup value="accounting">
      <template #activator="{ props }">
        <CdsListItem v-bind="props" value="accounting">
          <template #prepend>
            <CdsIcon name="folder" />
          </template>
          <template #title>Бухгалтерия</template>
        </CdsListItem>
      </template>

      <CdsListItem value="invoices">
        <template #prepend>
          <CdsIcon name="file" />
        </template>
        <template #title>Счета</template>
      </CdsListItem>

      <CdsListItem value="acts">
        <template #prepend>
          <CdsIcon name="file" />
        </template>
        <template #title>Акты сверки</template>
      </CdsListItem>
    </CdsListGroup>
  </CdsList>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A short title names the record — the eye compares items along a single trait. | A paragraph of text in a row turns the list into an article: scanning no longer finds anything. |
| A long enumeration is split by subheaders — it is clear where to look for the record you need. | A solid list with no grouping has to be read in full. |
| One action per row, the rest in a menu: the item as a whole stays clickable. | A row of buttons in every line overloads the list and makes the item itself hard to hit. |

## Scenarios

### Section menu

A side menu is `activatable` plus `nav`: exactly one entry is active,
`mandatory` forbids clearing the selection, and `v-model:activated` keeps the
current section in the application state. Subheaders split the entries into
meaningful blocks.

**Example — `NavigationMenu.vue`:**

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

const activated = ref(['contracts']);

const items: { type?: string; title: string; value?: string; props?: Record<string, unknown> }[] = [
  { type: 'subheader', title: 'Работа' },
  { title: 'Закупки', value: 'purchases', props: { prependIcon: 'shopping-cart' } },
  { title: 'Договоры', value: 'contracts', props: { prependIcon: 'file' } },
  { title: 'Поставщики', value: 'suppliers', props: { prependIcon: 'company' } },
  { type: 'subheader', title: 'Настройки' },
  { title: 'Сотрудники', value: 'employees', props: { prependIcon: 'user-group' } },
  { title: 'Уведомления', value: 'notifications', props: { prependIcon: 'notification' } }
];

const current = computed(() => items.find((item) => item.value === activated.value[0])?.title ?? 'ничего');
</script>

<template>
  <div class="m-auto flex w-[250px] flex-col gap-2">
    <CdsList v-model:activated="activated" activatable nav mandatory :items="items" />

    <span class="text-100 text-content-secondary">Открыт раздел: {{ current }}</span>
  </div>
</template>
```

### Document list with actions

The whole row stays clickable, and the action in the `append` area works on top
of it — that is why the button has `@click.stop`, otherwise the click would
reach the item and select it. The status next to the button is a regular
CdsTag.

**Example — `DocumentsList.vue`:**

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

const documents = ref([
  { id: 1, title: 'Договор поставки № 42', company: 'ООО «Ромашка»', status: 'Подписан' },
  { id: 2, title: 'Акт сверки за март', company: 'ООО «Василёк»', status: 'На согласовании' },
  { id: 3, title: 'Счёт на оплату № 5512', company: 'ООО «Ромашка»', status: 'Черновик' }
]);

const removed = ref<string[]>([]);

function remove(id: number) {
  const document = documents.value.find((item) => item.id === id);
  if (!document) return;

  removed.value = [...removed.value, document.title];
  documents.value = documents.value.filter((item) => item.id !== id);
}
</script>

<template>
  <div class="m-auto flex w-[380px] flex-col gap-2">
    <CdsList lines="two">
      <CdsListItem
        v-for="document of documents"
        :key="document.id"
        :value="document.id"
        prepend-icon="file"
        :title="document.title"
        :subtitle="document.company"
      >
        <template #append>
          <div class="flex items-center gap-2">
            <CdsTag size="sm" :text="document.status" />
            <CdsFunctionalButton icon="delete" aria-label="Удалить документ" @click.stop="remove(document.id)" />
          </div>
        </template>
      </CdsListItem>
    </CdsList>

    <span v-if="removed.length" class="text-100 text-content-secondary">Удалено: {{ removed.join(', ') }}</span>
  </div>
</template>
```

### Picking recipients

The `prepend` slot receives `isSelected` and `select` — the selection state and
the function that changes it. This lets you show a checkbox while keeping the
click on the whole row: `CdsListItemAction` aligns it to the grid of the item,
and `CdsAvatar` stands next to it.

**Example — `Recipients.vue`:**

```vue
<script setup lang="ts">
import { CdsAvatar, CdsCheckbox, CdsList, CdsListItem, CdsListItemAction } from '@central-design-system/components';
import { computed, 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' }
];

const selected = ref(['a.smirnova@example.com']);

const summary = computed(() =>
  selected.value.length ? `Выбрано получателей: ${selected.value.length}` : 'Получатели не выбраны'
);
</script>

<template>
  <div class="m-auto flex w-[300px] flex-col gap-2">
    <CdsList v-model:selected="selected" selectable select-strategy="independent" lines="two">
      <CdsListItem v-for="person of people" :key="person.email" :value="person.email" :title="person.name">
        <template #prepend="{ isSelected, select }">
          <CdsListItemAction start>
            <CdsCheckbox :model-value="isSelected" hide-details tabindex="-1" @update:model-value="select" />
          </CdsListItemAction>

          <CdsAvatar size="sm" :image="person.image" />
        </template>

        <template #subtitle>{{ person.email }}</template>
      </CdsListItem>
    </CdsList>

    <span class="text-100 text-content-secondary">{{ summary }}</span>
  </div>
</template>
```

### Searching through a list

The list is rebuilt from the filtered array — it needs no logic of its own.
When there are no matches, a CdsEmptyState is
shown instead of an empty list: the user understands that the reason is the
query, not the loading.

**Example — `SearchableList.vue`:**

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

const query = ref('');

const suppliers = [
  { title: 'ООО «Ромашка»', value: 'romashka', props: { prependIcon: 'company', subtitle: 'Канцелярия' } },
  { title: 'ООО «Василёк»', value: 'vasilek', props: { prependIcon: 'company', subtitle: 'Логистика' } },
  {
    title: 'АО «Северсталь-Комплект»',
    value: 'severstal',
    props: { prependIcon: 'company', subtitle: 'Металлопрокат' }
  },
  { title: 'ИП Кузнецов А. В.', value: 'kuznecov', props: { prependIcon: 'company', subtitle: 'Ремонт техники' } }
];

const filtered = computed(() =>
  suppliers.filter((supplier) => supplier.title.toLowerCase().includes(query.value.trim().toLowerCase()))
);
</script>

<template>
  <div class="m-auto flex w-[300px] flex-col gap-2">
    <CdsTextInput
      v-model="query"
      placeholder="Поиск по поставщикам"
      prepend-inner-icon="search"
      clearable
      hide-details
    />

    <CdsList v-if="filtered.length" :items="filtered" lines="two" />

    <CdsEmptyState v-else title="Ничего не найдено" description="Проверьте написание или очистите запрос" />
  </div>
</template>
```

## API

### CdsList

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activatable` | `boolean \| undefined` | — | no | Allows items to be activated (highlighting the current item without selection mode) |
| `activated` | `any` | — | no | Identifiers of the active items (supports v-model through `update:activated`) |
| `activeClass` | `string \| undefined` | — | no | Class applied to list items when they are in the active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `activeStrategy` | `ActiveStrategyProp \| undefined` | — | no | Activation strategy for items (single, multiple, and so on) |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `collapseIcon` | `IconValue \| undefined` | — | no | Icon shown on a collapsed group |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `expandIcon` | `IconValue \| undefined` | — | no | Icon shown on an expanded group |
| `filterable` | `boolean \| undefined` | — | no | **FOR INTERNAL USE ONLY** Turns on filtering mode: the space key does not select an item but is used for typing. Applies to the CdsCombobox and CdsAutocomplete components |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `indent` | `string \| number \| undefined` | — | no | Indent size for nested item groups |
| `itemChildren` | `SelectItemKey` | `'children'` | no | Object field that holds the child items, or a function that returns them |
| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
| `itemsRegistration` | `ItemsRegistrationType \| undefined` | `'render'` | no | Item registration strategy: `render` — as they are rendered, otherwise all at once |
| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
| `itemType` | `SelectItemKey` | `'type'` | no | Object field that defines the item type (`item`, `divider`, `subheader`), or a function that returns it |
| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
| `lines` | `false \| "one" \| "two" \| "three" \| undefined` | `'one'` | no | Number of lines in the list items; affects their height. `false` turns off the fixed height |
| `mandatory` | `boolean \| undefined` | — | no | Makes the selection mandatory: forbids clearing the selection of the last item |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `nav` | `boolean \| undefined` | — | no | Applies navigation list styles (rounded active items) |
| `navigationIndex` | `number \| undefined` | — | no | Index of the current item during keyboard navigation (supports v-model) |
| `navigationStrategy` | `"focus" \| "track" \| undefined` | `'focus'` | no | Keyboard navigation strategy: `focus` — moves the focus, `track` — a virtual cursor |
| `opened` | `any` | — | no | Identifiers of the expanded groups (supports v-model through `update:opened`) |
| `openStrategy` | `OpenStrategyProp \| undefined` | `'list'` | no | Expansion strategy for groups (`list`, `single`, `multiple`) |
| `prependGap` | `string \| number \| undefined` | — | no | Indent before the item content (reserves space for the prepend icon or avatar) |
| `required` | `boolean \| undefined` | — | no | Makes the selection mandatory: forbids clearing the selection of the last item |
| `returnObject` | `boolean \| undefined` | — | no | Return an object in the model value instead of an array |
| `selectable` | `boolean \| undefined` | — | no | Allows items to be selected |
| `selected` | `any` | — | no | Identifiers of the selected items (supports v-model through `update:selected`) |
| `selectStrategy` | `SelectStrategyProp \| undefined` | `'single-leaf'` | no | Selection strategy for items (`single-leaf`, `leaf`, `independent`, `classic`, and so on) |
| `slim` | `boolean \| undefined` | — | no | Removes the inner paddings of the list and of the menu container: the list fills the available area completely |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:activate` | `[value: { id: unknown; value: boolean; path: unknown[]; }]` | Fires when an item is activated. `value` — the id of the item, its new state and its path |
| `click:open` | `[value: { id: unknown; value: boolean; path: unknown[]; }]` | Fires on a click on the group activator. `value` — the id of the group, its new state and its path |
| `click:select` | `[value: { id: unknown; value: boolean; path: unknown[]; }]` | Fires when an item is selected. `value` — the id of the item, its new state and its path |
| `update:activated` | `[value: unknown]` | Fires when the set of active items changes. `value` — identifiers of the active items |
| `update:navigationIndex` | `[value: unknown]` | Fires when the keyboard navigation index changes. `value` — the new index |
| `update:opened` | `[value: unknown]` | Fires when the set of expanded groups changes. `value` — identifiers of the expanded groups |
| `update:selected` | `[value: unknown]` | Fires when the set of selected items changes. `value` — identifiers of the selected items |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `ListItemSlot & { item: unknown; }` | Content after the item text (in place of the append icon or avatar) |
| `default` | `ListItemSlot & { item: unknown; }` | Default content. Overrides the automatic rendering of items from `items` |
| `description` | `ListItemDescriptionSlot & { item: unknown; }` | Content of the item description (shown below the title and the subtitle) |
| `divider` | `{ props: { [key: string]: any; title: string; value: any; }; }` | Custom rendering of a divider when `items` is used |
| `header` | `{ props: { [key: string]: any; title: string; value: any; }; }` | Custom rendering of the group activator (its heading) when `items` is used |
| `item` | `{ props: { [key: string]: any; title: string; value: any; } & { index: number; }; }` | Custom rendering of a list item when `items` is used |
| `prepend` | `ListItemSlot & { item: unknown; }` | Content before the item text (in place of the prepend icon or avatar) |
| `subheader` | `{ props: { [key: string]: any; title: string; value: any; }; }` | Custom rendering of a subheader when `items` is used |
| `subtitle` | `ListItemSubtitleSlot & { item: unknown; }` | Content of the item subtitle |
| `title` | `ListItemTitleSlot & { item: unknown; }` | Content of the item title |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `children` | `Map<unknown, unknown[]>` | Map of child items keyed by the identifiers of their parents |
| `focus` | `(location?: number \| "next" \| "prev" \| "first" \| "last" \| undefined) => void` | Moves the focus to a list item (by index or by a keyword: `next`, `prev`, `first`, `last`) |
| `getPath` | `(id: unknown) => unknown[]` | Returns the path (an array of identifiers) to an item by its id |
| `open` | `(id: unknown, value: boolean, event?: Event \| undefined) => void` | Expands or collapses a group by its identifier |
| `parents` | `Map<unknown, unknown>` | Map of parent items keyed by the identifiers of their children |
| `select` | `(id: unknown, value: boolean, event?: Event \| undefined) => void` | Selects or deselects an item by its identifier |

### CdsListGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon shown after the group title |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `collapseIcon` | `IconValue \| undefined` | `'chevron-up'` | no | Icon shown when the group is collapsed |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `expandIcon` | `IconValue \| undefined` | `'chevron-down'` | no | Icon shown when the group is expanded |
| `fluid` | `boolean \| undefined` | — | no | Removes the indent of the group activator, aligning it to the edge of the list |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon shown before the group title |
| `rawId` | `string \| number \| undefined` | — | no | Original identifier of the group; used to build the id of the DOM element |
| `subgroup` | `boolean \| undefined` | — | no | Marks the component as a group of nested lists (a subgroup) |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `title` | `string \| undefined` | — | no | Title of the group shown in the default activator |
| `value` | `any` | — | no | Value of the group used in the expansion and selection logic |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `activator` | `CdsListGroupActivatorSlot` | Activator of the group — the heading that expands and collapses the group on click |
| `default` | `any` | Content of the group (the nested list items) |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isOpen` | `boolean` | Whether the group is expanded |

### CdsListItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Forces the active state of the item |
| `activeClass` | `string \| undefined` | — | no | Class applied to list items when they are in the active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendAvatar` | `string \| undefined` | — | no | Avatar (image URL) shown after the item content |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon shown after the item content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `description` | `string \| number \| boolean \| undefined` | — | no | Description of the list item shown below the title and the subtitle |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `index` | `number \| undefined` | — | no | Index of the item; used for keyboard navigation |
| `lines` | `false \| "one" \| "two" \| "three" \| undefined` | `'one'` | no | Number of lines in the list items; affects their height. `false` turns off the fixed height |
| `link` | `boolean \| undefined` | — | no | Turns the item into a clickable link. Detected automatically when `href` or `to` is set |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `nav` | `boolean \| undefined` | — | no | Applies navigation list styles (rounded active items) |
| `prependAvatar` | `string \| undefined` | — | no | Avatar (image URL) shown before the item content |
| `prependGap` | `string \| number \| undefined` | — | no | Indent before the item content (reserves space for the prepend icon or avatar) |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon shown before the item content |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `slim` | `boolean \| undefined` | — | no | Removes the inner paddings of the list and of the menu container: the list fills the available area completely |
| `subtitle` | `string \| number \| boolean \| undefined` | — | no | Subtitle of the item shown below the title |
| `tabindex` | `string \| number \| undefined` | — | no | Value of the element `tabindex` attribute |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| number \| boolean \| undefined` | — | no | Title of the item shown in the component |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `value` | `any` | — | no | Value of the item used for selection and activation in the list |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click` | `[value: MouseEvent \| KeyboardEvent]` | Fires on a click on the list item |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `ListItemSlot` | Content after the item text (in place of the append icon or avatar) |
| `default` | `ListItemSlot` | Default content inside the item |
| `description` | `ListItemDescriptionSlot` | Content of the item description (shown below the title and the subtitle) |
| `prepend` | `ListItemSlot` | Content before the item text (in place of the prepend icon or avatar) |
| `subtitle` | `ListItemSubtitleSlot` | Content of the item subtitle |
| `title` | `ListItemTitleSlot` | Content of the item title |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activate` | `(activated: boolean, e?: Event \| undefined) => void` | Activates or deactivates the item |
| `isActivated` | `boolean` | Whether the item is in the active state |
| `isGroupActivator` | `boolean \| undefined` | Whether the item is a group activator |
| `isSelected` | `boolean` | Whether the item is selected |
| `list` | `{ filterable: MaybeRefOrGetter<boolean>; hasPrepend: Ref<boolean, boolean>; updateHasPrepend: (value: boolean) => void; trackingIndex: Ref<number, number>; navigationStrategy: Ref<"focus" \| "track", "focus" \| "track">; uid: string; } \| null` | Context of the parent list (CdsList) |
| `root` | `NestedRoot` | Root nesting context of the parent list |
| `select` | `(selected: boolean, e?: Event \| undefined) => void` | Selects or deselects the item |

### CdsListItemAction

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `end` | `boolean \| undefined` | — | no | Places the action at the end of the list item (after the content) |
| `start` | `boolean \| undefined` | — | no | Places the action at the start of the list item (before the content) |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default content of the action |

### CdsListItemDescription

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

### CdsListItemDivider

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Color of the divider. |
| `contentOffset` | `string \| number \| (string \| number)[] \| undefined` | — | no | Increases the spacing between the content and the lines. When passed as an array, the second value shifts the slot content down (or right when vertical = true). |
| `gradient` | `boolean \| undefined` | — | no | Adds a fade-out effect on both ends. |
| `inset` | `boolean \| undefined` | — | no | Adds an indent to horizontal dividers and reduces the maximum height of vertical ones. |
| `length` | `string \| number \| undefined` | — | no | Length of the divider. Defaults to pixels. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the divider. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `thickness` | `string \| number \| undefined` | — | no | Thickness of the divider. Defaults to pixels. |
| `variant` | `"solid" \| "dotted" \| "dashed" \| "double" \| undefined` | `'solid'` | no | Visual variant of the divider |
| `vertical` | `boolean \| undefined` | — | no | Renders the divider vertically |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Text or content placed in the gap of the divider |

### CdsListItemImage

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

### CdsListItemMedia

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `end` | `boolean \| undefined` | — | no | Places the media at the end of the list item (after the content) |
| `start` | `boolean \| undefined` | — | no | Places the media at the start of the list item (before the content) |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default content of the media |

### CdsListItemSubtitle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

### CdsListItemTitle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

### CdsListSubheader

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Color of the subheader text |
| `inset` | `boolean \| undefined` | — | no | Adds a left indent, aligning the text with the content of the list items |
| `sticky` | `boolean \| undefined` | — | no | Pins the subheader to the top while the list scrolls |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `title` | `string \| undefined` | — | no | Text of the subheader |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Default content of the subheader (overrides the `title` prop) |

---

# CdsLoader

_Category: Feedback · since 4.0.0 · status: deprecated_

_Tests: API 5/5 · 8 unit · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A circular indeterminate loading indicator — a spinning ring without progress. It shows that the data is still loading: as an inline element, as an overlay above a container or above the whole page.

**See also:** The component is deprecated and will be removed in future versions. Use CdsProgressCircle: it covers both indeterminate loading and progress.

## Variations

### Sizes

The `size` prop sets the diameter of the indicator: from `xs` to `xl` or a
number in pixels. The default size is `md`.

**Example — `Sizes.vue`:**

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

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsLoader v-for="size of sizes" :key="size" :size="size" />
  </div>
</template>
```

### Overlay

The `overlay` prop expands the indicator to the full screen and dims the content
underneath. Add `fixed` so that the overlay takes the nearest container with
`position: relative` instead of the whole page. The `description` prop describes
what is going on for screen readers (aria-label).

**Example — `Overlay.vue`:**

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

const loading = ref(false);

function refresh() {
  loading.value = true;
  setTimeout(() => {
    loading.value = false;
  }, 2000);
}
</script>

<template>
  <div class="relative m-auto flex w-[320px] flex-col gap-2 rounded-200 bg-surface-secondary p-4">
    <span class="text-content-primary">Список товаров</span>
    <span class="text-content-secondary">Ноутбук, монитор, клавиатура, мышь</span>

    <CdsButton text="Обновить" variant="soft" color="brand" @click="refresh" />

    <CdsLoader v-if="loading" overlay fixed description="Список обновляется" />
  </div>
</template>
```

## API

### CdsLoader

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `description` | `string \| undefined` | — | no | Description that best explains the loading state (aria-label) |
| `fixed` | `boolean \| undefined` | — | no | Pins the loader to the current container |
| `overlay` | `boolean \| undefined` | — | no | Renders a fixed full-screen loader |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `theme` | `string \| undefined` | — | no | Component theme |

---

# CdsMain

_Category: Layouts · since 4.0.0_

_Tests: API 1/1 · 4 unit · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

The main area of the application: `CdsMain` is the place where the content of the page lands. Inside `CdsLayout` it indents itself by the height of the header and the footer and by the width of the side drawers, so the content never has to be moved by hand.

**See also:** Put the content into CdsPage — it calculates the minimum height of the page. `CdsMain` works only inside CdsLayout: outside the layout it renders nothing and warns about it in the console.

## Scenarios

### The main area of the application

`CdsMain` renders as a `main` tag — one semantic content area per page. The
paddings are recalculated on the fly: minify a drawer, hide the header — and the
content immediately takes the freed space.

**Example — `Offsets.vue`:**

```vue
<script setup lang="ts">
import {
  CdsDrawer,
  CdsFooter,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsDrawer permanent border>
        <CdsList>
          <CdsListItem title="Закупки" href="#" prepend-icon="shopping-cart" active />
          <CdsListItem title="Договоры" href="#" prepend-icon="file" />
        </CdsList>
      </CdsDrawer>

      <CdsMain class="bg-surface-secondary">
        <CdsPage padding>
          <div class="rounded-200 bg-surface-primary p-4 text-content-primary">
            Подсвеченная область — CdsMain. Её отступы сверху, снизу и слева равны размерам шапки, подвала и панели.
          </div>
        </CdsPage>
      </CdsMain>

      <CdsFooter bordered>
        <div class="flex h-[40px] items-center px-4 text-content-secondary">Подвал</div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsMain

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Main content of the application (`CdsPage`). |

---

# CdsMenu

_Category: Content · since 4.0.0_

_Tests: API 56/56 · 51 unit · 8 e2e · 5 known bugs · lines 87% (v4.0.0-alpha.13) · a11y: 7 axe recommendations (v4.0.0-alpha.11)_

A menu pops up next to an activator element and shows a list of actions or sections: the "more" button in a table row, the user menu in the header, a context menu on right click. It positions itself — it opens towards the free space and sticks to the activator while the page scrolls.

**See also:** To pick a value in a form, take CdsSelect — it stays visible and gets submitted. For a short hint on hover use CdsTooltip, and for a dialog that demands an answer use CdsModal. The content of a menu is usually built from CdsList.

## Variations

### Activators

A menu is opened by an activator element — you can set it in three ways:

1. **Through the `activator` slot** — the props from the slot (`v-bind="props"`)
   attach the handlers and the aria attributes to the element. This is the
   default way: the activator sits next to the menu.
2. **Through the parent** — `activator="parent"` takes the element that contains
   the `CdsMenu`. Handy when the activator is already built and you do not want
   to wrap it.
3. **Through a selector** — `activator="#id"` links the menu to any element on
   the page, even a distant one in the markup.

**Example — `Activators.vue`:**

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

const items = [
  { title: 'Скачать', value: 'download' },
  { title: 'Дублировать', value: 'duplicate' },
  { title: 'Переименовать', value: 'rename' }
];
</script>

<template>
  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
    <CdsMenu>
      <template #activator="{ props }">
        <CdsButton v-bind="props">Активатор в слоте</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>

    <CdsButton>
      Родительский элемент

      <CdsMenu activator="parent">
        <CdsList :items="items" />
      </CdsMenu>
    </CdsButton>

    <CdsButton id="menu-activator">Соседний элемент</CdsButton>

    <CdsMenu activator="#menu-activator">
      <CdsList :items="items" />
    </CdsMenu>
  </div>
</template>
```

### Opening

By default the menu opens on click. The `open-on-hover` prop switches it to
hover — this is how navigation menus behave; a click then does not open the
panel. The `open-delay` and `close-delay` delays (300 and 250 ms) keep the menu
from flickering when the cursor just passes by. Together with `open-on-hover`,
opening on focus is enabled as well — turn it off with `:open-on-focus="false"`
if the menu should react to the mouse only.

**Example — `OpenOnHover.vue`:**

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

const items = [
  { title: 'Профиль', value: 'profile' },
  { title: 'Уведомления', value: 'notifications' },
  { title: 'Выйти', value: 'logout' }
];
</script>

<template>
  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
    <CdsMenu open-on-hover>
      <template #activator="{ props }">
        <CdsButton v-bind="props">Наведите курсор</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>

    <CdsMenu open-on-hover :open-delay="0" :close-delay="0">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand">Без задержек</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>

    <CdsMenu open-on-hover :open-on-focus="false">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand">Только наведение</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>
  </div>
</template>
```

### Position

The `location` prop sets the side of the activator the menu appears on: `bottom`
by default, `top`, `end`, `bottom end` — the side and the alignment. If there is
not enough room, the menu flips to the opposite edge on its own. The `offset`
prop tunes the distance to the activator, and `viewport-margin` sets the minimum
gap to the edge of the screen.

**Example — `Location.vue`:**

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

const items = [
  { title: 'Скачать', value: 'download' },
  { title: 'Дублировать', value: 'duplicate' },
  { title: 'Переименовать', value: 'rename' }
];

const locations = ['bottom', 'top', 'end', 'bottom end'] as const;
</script>

<template>
  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
    <CdsMenu v-for="location in locations" :key="location" :location="location">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral">{{ location }}</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>

    <CdsMenu :offset="16">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral">offset 16</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>
  </div>
</template>
```

### Sizes

The width of the menu equals the width of its content. The `min-width`,
`max-width` and `max-height` props set the bounds: the minimum width keeps the
panel from collapsing on short items, and a limited height turns on scrolling
instead of a full-screen menu.

**Example — `MenuSize.vue`:**

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

const items = Array.from({ length: 12 }, (_, index) => ({
  title: `Организация № ${index + 1}`,
  value: index + 1
}));
</script>

<template>
  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
    <CdsMenu :min-width="280">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Минимальная ширина</CdsButton>
      </template>

      <CdsList :items="items.slice(0, 3)" />
    </CdsMenu>

    <CdsMenu :max-height="220">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand">Ограниченная высота</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>
  </div>
</template>
```

### Closing

The menu closes on a click inside the content, on a click outside and on `Esc`.
The `:close-on-content-click="false"` prop keeps the panel open — you need that
when it holds checkboxes, fields or several steps in a row. The `persistent`
prop ignores the outside click and `Esc`: then the menu can only be closed by
your own button through `v-model`.

**Example — `CloseBehavior.vue`:**

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

const items = [
  { title: 'Скачать', value: 'download' },
  { title: 'Дублировать', value: 'duplicate' },
  { title: 'Переименовать', value: 'rename' }
];

const columns = ref(['name']);
const persistent = ref(false);
</script>

<template>
  <div class="m-auto flex flex-wrap items-center justify-center gap-2">
    <CdsMenu>
      <template #activator="{ props }">
        <CdsButton v-bind="props">Закроется по клику</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>

    <CdsMenu :close-on-content-click="false">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand">Останется открытым</CdsButton>
      </template>

      <CdsSurface class="flex w-[220px] flex-col gap-1">
        <CdsCheckbox v-model="columns" value="name" label="Название" hide-details />
        <CdsCheckbox v-model="columns" value="date" label="Дата" hide-details />
        <CdsCheckbox v-model="columns" value="status" label="Статус" hide-details />
      </CdsSurface>
    </CdsMenu>

    <CdsMenu v-model="persistent" persistent :close-on-content-click="false">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand">Только своей кнопкой</CdsButton>
      </template>

      <CdsSurface class="flex w-[240px] flex-col gap-1 p-2">
        <span class="text-100 text-content-secondary">Клик мимо меню его не закроет.</span>

        <CdsButton size="sm" variant="soft" color="neutral" @click="persistent = false">Закрыть</CdsButton>
      </CdsSurface>
    </CdsMenu>
  </div>
</template>
```

### Nested menus

Menus can be nested into each other: every list item becomes an activator
(`activator="parent"`) for a child `CdsMenu` with the `submenu` prop — it shifts
the panel sideways and moves the navigation to the left and right arrow keys.
The `open-on-hover` prop opens the submenu on hover, and `:open-on-focus="false"`
keeps it from opening while tabbing through.

**Example — `NestedMenu.vue`:**

```vue
<script setup lang="ts">
import { CdsButton, CdsIcon, CdsList, CdsListItem, CdsMenu } from '@central-design-system/components';

const sections = [
  { title: 'Закупки', children: ['Черновики', 'Опубликованные', 'Завершённые'] },
  { title: 'Договоры', children: ['На согласовании', 'Подписанные', 'Архив'] },
  { title: 'Отчёты', children: ['По поставщикам', 'По срокам', 'По суммам'] }
];

const periods = ['За неделю', 'За месяц', 'За квартал'];
</script>

<template>
  <div class="m-auto flex justify-center">
    <CdsButton>
      Открыть меню

      <CdsMenu activator="parent">
        <CdsList>
          <CdsListItem v-for="section in sections" :key="section.title" link :title="section.title">
            <template #append>
              <CdsIcon name="chevron-right" size="xs" />
            </template>

            <CdsMenu activator="parent" submenu open-on-hover :open-on-focus="false">
              <CdsList>
                <CdsListItem v-for="child in section.children" :key="child" link :title="child">
                  <template #append>
                    <CdsIcon name="chevron-right" size="xs" />
                  </template>

                  <CdsMenu activator="parent" submenu open-on-hover :open-on-focus="false">
                    <CdsList>
                      <CdsListItem v-for="period in periods" :key="period" link :title="period" />
                    </CdsList>
                  </CdsMenu>
                </CdsListItem>
              </CdsList>
            </CdsMenu>
          </CdsListItem>
        </CdsList>
      </CdsMenu>
    </CdsButton>
  </div>
</template>
```

### Animation

The `transition` prop changes the animation the panel appears with.

**Example — `Transition.vue`:**

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

const items = [
  { title: 'Скачать', value: 'download' },
  { title: 'Дублировать', value: 'duplicate' },
  { title: 'Переименовать', value: 'rename' }
];

const transitions = ['fade-transition', 'scale-transition', 'slide-transition-y', 'slide-transition-x'];
</script>

<template>
  <div class="m-auto flex flex-wrap items-center justify-center gap-4">
    <CdsMenu v-for="transition in transitions" :key="transition" :transition="transition">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral">{{ transition }}</CdsButton>
      </template>

      <CdsList :items="items" />
    </CdsMenu>
  </div>
</template>
```

### Slots

| Slot        | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `activator` | The element that opens the menu. The slot props (`props`) attach the handlers to it |
| `default`   | The content of the panel. Usually `CdsList`, `CdsCard` or `CdsSurface`              |

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The activator names what is inside the menu: a label or the well-known «⋮» icon makes it clear that a list of actions will open. | An icon with no label and no aria-label promises nothing — the menu gets opened at random. |
| A menu triggers actions. A field value is picked in a select — it stays visible and takes part in the form submission. | A menu used instead of a field hides the selected value and drops out of the form validation. |
| Rare actions on a record are collected in a single menu behind the «⋮» button — press it to see the list. The row stays readable. | A row of equally weighted buttons in every line overloads the table and hides the main action. |

## Scenarios

### Actions on a record

Rare actions on a table row or a card are collected in a menu behind the "⋮"
button: the row stays clean, and the actions do not compete with the main
button. `location="bottom end"` pins the panel to the right edge of the
activator, `slim` on the list removes the extra paddings, and `aria-label` names
the record the menu belongs to.

**Example — `RowActions.vue`:**

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

const documents = [
  { id: 1, title: 'Договор поставки № 42' },
  { id: 2, title: 'Счёт на оплату № 5512' },
  { id: 3, title: 'Акт сверки за март' }
];

const actions = [
  { title: 'Скачать', icon: 'download' },
  { title: 'Дублировать', icon: 'copy' },
  { title: 'Переименовать', icon: 'edit' }
];

const lastAction = ref('');
</script>

<template>
  <div class="m-auto flex w-[300px] flex-col gap-1">
    <div v-for="doc in documents" :key="doc.id" class="flex items-center justify-between gap-2">
      <span class="text-100">{{ doc.title }}</span>

      <CdsMenu location="bottom end">
        <template #activator="{ props }">
          <CdsButton
            v-bind="props"
            size="sm"
            variant="soft"
            color="neutral"
            icon="more-vertical"
            :aria-label="`Действия: ${doc.title}`"
          />
        </template>

        <CdsList slim>
          <CdsListItem
            v-for="action in actions"
            :key="action.title"
            link
            :title="action.title"
            :prepend-icon="action.icon"
            @click="lastAction = `${action.title}: ${doc.title}`"
          />

          <CdsListItemDivider />

          <CdsListItem link title="Удалить" prepend-icon="delete" @click="lastAction = `Удалить: ${doc.title}`" />
        </CdsList>
      </CdsMenu>
    </div>

    <p class="text-100 text-content-secondary">{{ lastAction || 'Выберите действие в меню строки' }}</p>
  </div>
</template>
```

### Context menu

A menu can open at the point of the click: the `contextmenu` handler puts the
cursor coordinates into `target`, and `v-model` controls the visibility — no
activator is needed here. A new click moves the open panel to the new spot. The
default animation is meant for an element activator, so for a menu placed by
coordinates set a CSS animation — for example, `transition="scale-transition"`.

**Example — `ContextMenu.vue`:**

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

const isOpen = ref(false);
const coordinates = ref<[number, number]>([0, 0]);
const lastAction = ref('');

const openContextMenu = (event: MouseEvent) => {
  coordinates.value = [event.clientX, event.clientY];
  isOpen.value = true;
};
</script>

<template>
  <div class="m-auto flex w-[380px] flex-col gap-1">
    <CdsSurface
      class="flex h-[140px] cursor-context-menu items-center justify-center rounded border border-dashed"
      @contextmenu.prevent="openContextMenu"
    >
      <span class="text-100 text-content-secondary">Кликните правой кнопкой мыши</span>
    </CdsSurface>

    <CdsMenu v-model="isOpen" :target="coordinates" transition="scale-transition">
      <CdsList slim>
        <CdsListItem link title="Вырезать" prepend-icon="copy" @click="lastAction = 'Вырезать'" />
        <CdsListItem link title="Копировать" prepend-icon="copy" @click="lastAction = 'Копировать'" />
        <CdsListItem link title="Вставить" prepend-icon="paste" @click="lastAction = 'Вставить'" />
      </CdsList>
    </CdsMenu>

    <p class="text-100 text-content-secondary">{{ lastAction || 'Действие не выбрано' }}</p>
  </div>
</template>
```

### Menu in the header

In the application header a menu solves two tasks: it expands the navigation
sections and collects everything about the account behind the avatar. The
activator of the user menu is a `CdsAvatar` inside a button with an
`aria-label`, `location="bottom end"` pins the panel to the right edge, and
`min-width` keeps it from jumping in width. The first list item shows whose
account it is, and `CdsListItemDivider` separates the sections from signing out.

**Example — `UserMenu.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsButton,
  CdsHeader,
  CdsLayout,
  CdsList,
  CdsListItem,
  CdsListItemDivider,
  CdsMain,
  CdsMenu
} from '@central-design-system/components';
import { ref } from 'vue';

const sections = [
  { title: 'Закупки', items: ['Мои закупки', 'Черновики', 'Архив'] },
  { title: 'Договоры', items: ['Действующие', 'На согласовании'] }
];

const opened = ref('');
</script>

<template>
  <div class="m-auto h-[220px] w-full max-w-[560px]">
    <CdsLayout container>
      <CdsHeader elevated>
        <div class="flex h-[56px] items-center gap-2 px-4">
          <span class="text-100 font-bold text-content-primary">B2B-Center</span>

          <nav class="flex items-center gap-1">
            <CdsMenu v-for="section in sections" :key="section.title" :min-width="180">
              <template #activator="{ props }">
                <CdsButton
                  v-bind="props"
                  size="sm"
                  variant="soft"
                  color="neutral"
                  append-icon="chevron-down"
                  :text="section.title"
                />
              </template>

              <CdsList slim>
                <CdsListItem
                  v-for="item in section.items"
                  :key="item"
                  link
                  :title="item"
                  @click="opened = `${section.title} → ${item}`"
                />
              </CdsList>
            </CdsMenu>
          </nav>

          <div class="ml-auto">
            <CdsMenu location="bottom end" :min-width="240">
              <template #activator="{ props }">
                <CdsButton v-bind="props" variant="soft" color="neutral" aria-label="Меню пользователя">
                  <CdsAvatar size="sm" text="ИП" />
                </CdsButton>
              </template>

              <CdsList slim>
                <CdsListItem lines="two" title="Иван Петров" subtitle="i.petrov@example.com">
                  <template #prepend>
                    <CdsAvatar size="sm" text="ИП" start />
                  </template>
                </CdsListItem>

                <CdsListItemDivider />

                <CdsListItem link title="Профиль" prepend-icon="user" @click="opened = 'Профиль'" />
                <CdsListItem link title="Организация" prepend-icon="company" @click="opened = 'Организация'" />
                <CdsListItem link title="Настройки" prepend-icon="settings" @click="opened = 'Настройки'" />

                <CdsListItemDivider />

                <CdsListItem link title="Выйти" prepend-icon="logout" @click="opened = 'Выход из аккаунта'" />
              </CdsList>
            </CdsMenu>
          </div>
        </div>
      </CdsHeader>

      <CdsMain>
        <p class="p-4 text-100 text-content-secondary">{{ opened || 'Выберите пункт в меню шапки' }}</p>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

### Filter with several values

When several values are picked inside a menu, the panel must not close on the
very first click: `:close-on-content-click="false"` keeps it open, and `v-model`
lets the "Apply" button close the menu. The selection piles up in a draft and is
applied as a whole — until the button is pressed, the list of records does not
change.

**Example — `FilterMenu.vue`:**

```vue
<script setup lang="ts">
import { CdsButton, CdsCheckbox, CdsMenu, CdsSurface } from '@central-design-system/components';
import { computed, ref, watch } from 'vue';

const statuses = [
  { title: 'Черновик', value: 'draft' },
  { title: 'На согласовании', value: 'review' },
  { title: 'Подписан', value: 'signed' },
  { title: 'Отклонён', value: 'rejected' }
];

const isOpen = ref(false);
const draft = ref<string[]>(['review']);
const applied = ref<string[]>(['review']);

const appliedTitles = computed(() =>
  statuses.filter((status) => applied.value.includes(status.value)).map((status) => status.title)
);

const apply = () => {
  applied.value = [...draft.value];
  isOpen.value = false;
};

const reset = () => {
  draft.value = [];
};

watch(isOpen, (value) => {
  if (value) draft.value = [...applied.value];
});
</script>

<template>
  <div class="m-auto flex w-[380px] flex-col items-center gap-1">
    <CdsMenu v-model="isOpen" :close-on-content-click="false" :min-width="240">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" prepend-icon="adjust">
          Статус<template v-if="applied.length">: {{ applied.length }}</template>
        </CdsButton>
      </template>

      <CdsSurface class="flex flex-col gap-2 p-2">
        <CdsCheckbox
          v-for="status in statuses"
          :key="status.value"
          v-model="draft"
          :value="status.value"
          :label="status.title"
          hide-details
        />

        <div class="flex justify-between gap-2">
          <CdsButton size="sm" variant="soft" color="neutral" text="Сбросить" @click="reset" />
          <CdsButton size="sm" text="Применить" @click="apply" />
        </div>
      </CdsSurface>
    </CdsMenu>

    <p class="text-100 text-content-secondary">
      {{ appliedTitles.length ? `Показаны: ${appliedTitles.join(', ')}` : 'Фильтр не выбран' }}
    </p>
  </div>
</template>
```

## API

### CdsMenu

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `captureFocus` | `boolean \| undefined` | `true` | no | Returns the focus back into the content if it has left it — for example on Tab from the end of the page. A mouse click does not steal the focus. |
| `closeDelay` | `string \| number \| undefined` | `250` | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeOnBack` | `boolean \| undefined` | `true` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | `true` | no | Hide the component on a click on the content |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `id` | `string \| undefined` | — | no | Unique identifier that links the menu to its activator. If it is not set, it is generated automatically. |
| `location` | `Anchor \| undefined` | `'bottom'` | no | Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'connected'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | — | no | The v-model value of the component. If the component supports the **multiple** prop, an empty array is used by default. |
| `noClickAnimation` | `boolean \| undefined` | — | no | Disables the bounce effect on a click outside the content element when `persistent` is set. |
| `offset` | `string \| number \| number[] \| undefined` | `4` | no | Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | `300` | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | — | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | — | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'auto'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `persistent` | `boolean \| undefined` | — | no | A click outside the element or the Esc key does not close it. |
| `retainFocus` | `boolean \| undefined` | — | no | Traps Tab navigation inside the content: from the last focusable element the focus moves to the first one and back. |
| `scrim` | `string \| boolean \| undefined` | `false` | no | Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color. |
| `scrollStrategy` | `"none" \| "close" \| "block" \| "reposition" \| ScrollStrategyFunction \| undefined` | `'none'` | no | Strategy applied when the component is active and the user scrolls the page. |
| `stickToTarget` | `boolean \| undefined` | — | no | Lets the overlay content go off screen while scrolling. |
| `submenu` | `boolean \| undefined` | — | no | Opens and closes the menu with the left/right arrow keys instead of up/down (for nested menus). |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; } \| null \| undefined` | `{ component: CdsModalTransition }` | no | Transition animation |
| `viewportMargin` | `string \| number \| undefined` | `12` | no | Sets a custom viewport margin for the overlay content |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2000` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `afterEnter` | `[]` | Fired after the opening animation of the menu has finished |
| `afterLeave` | `[]` | Fired after the closing animation of the menu has finished |
| `update:modelValue` | `[value: boolean]` | Fired when the menu is opened or closed. Passes the new visibility state |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `activator` | `{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }` | Slot for the element that acts as the activator of the overlay. |
| `default` | `{ isActive: Ref<boolean, boolean>; }` | Slot for the overlay content. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activatorEl` | `HTMLElement \| undefined` | The DOM element of the activator. |
| `activatorRef` | `TemplateRef` | Template ref for assigning the activator manually. |
| `animateClick` | `() => void` | Runs the bounce animation of the content — the same as on a click outside a `persistent` overlay. |
| `contentEl` | `HTMLElement \| undefined` | The DOM element of the overlay content. |
| `globalTop` | `boolean` | Whether the overlay is the top one in the global stack of open overlays. |
| `rootEl` | `HTMLElement \| undefined` | The root DOM element of the overlay. |
| `scrimEl` | `HTMLElement \| undefined` | The DOM element of the scrim that dims the page. |
| `targetEl` | `HTMLElement \| undefined` | The DOM element of the positioning target. |
| `targetRef` | `TemplateRef` | Template ref for assigning the positioning target manually. |
| `updateLocation` | `((e: Event) => void) \| undefined` | Recalculates the position of the content relative to the target. |

---

# CdsMessages

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 11/11 · 18 unit · 7 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 0 axe recommendations (v4.0.0-alpha.11)_

The block of messages under an input: a hint, an explanation or a validation error. The messages appear and disappear with an animation, so the line under the field does not jerk the layout.

**See also:** The ready-made fields already have the block of messages built in — the `messages`, `hint` and `error-messages` props of CdsTextInput and the other controls. A standalone `CdsMessages` is needed for groups of fields and for your own controls. For a noticeable notification on the page take CdsNotification.

## Variations

### Messages

The `messages` prop accepts a string or an array of strings — every string
becomes a separate line, they are not glued together.

**Example — `Messages.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsMessages active messages="Введите номер договора" />

    <CdsMessages active :messages="['Минимум 8 символов', 'Хотя бы одна цифра']" />
  </div>
</template>
```

### Color

The `color` prop sets the color of the text — take the status tokens
(`status-danger-content` for an error, `status-success-content` for a
confirmation). Without a color the messages are muted, like supporting text.

**Example — `Colors.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsMessages active messages="Обычное сообщение" />
    <CdsMessages active color="status-danger-content" messages="Номер договора не найден" />
    <CdsMessages active color="status-success-content" messages="Договор подтверждён" />
  </div>
</template>
```

### Appearance

The messages are visible only with `active`. Showing and hiding are animated,
and the animation is set by the `transition` prop.

**Example — `Active.vue`:**

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

const active = ref(true);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsMessages :active="active" messages="Сообщение появляется и исчезает с анимацией" />

    <CdsButton size="sm" variant="soft" color="brand" text="Показать / скрыть" @click="active = !active" />
  </div>
</template>
```

### Slot

The `message` slot overrides a single message and receives its text — you can
add an icon or a link. The `default` slot adds content after all the messages.

**Example — `Slot.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsMessages } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsMessages active color="status-danger-content" :messages="['Файл больше 10 МБ', 'Формат не поддерживается']">
      <template #message="{ message }">
        <CdsIcon icon="error-fill" size="sm" start />
        {{ message }}
      </template>
    </CdsMessages>
  </div>
</template>
```

## Scenarios

### An error for a group of fields

A group of checkboxes has no validation of its own: assemble it yourself and
show the result through `active`. While the selection is empty, the red message
hangs under the group and disappears with the very first checkbox.

**Example — `GroupValidation.vue`:**

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

const channels = ref<string[]>([]);
const isEmpty = computed(() => channels.value.length === 0);
</script>

<template>
  <div class="flex flex-col gap-1 w-[350px] m-auto">
    <CdsLabel text="Способы связи" />

    <CdsCheckbox v-model="channels" value="email" label="Электронная почта" multiple hide-details />
    <CdsCheckbox v-model="channels" value="phone" label="Телефон" multiple hide-details />

    <CdsMessages :active="isEmpty" color="status-danger-content" messages="Выберите хотя бы один способ связи" />
  </div>
</template>
```

## API

### CdsMessages

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; leaveAbsolute: boolean; group: boolean; } \| null \| undefined` | `{ component: slide-transition-y, leaveAbsolute: true, group: true }` | no | Transition animation |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Your own look for the whole list of messages instead of the default one |
| `message` | `CdsMessageSlot` | Template for a single message. The slot props carry the text of the message |

---

# CdsModal

_Category: Content · since 4.0.0_

_Tests: API 58/58 · 45 unit · 4 e2e · 2 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 9 axe recommendations (v4.0.0-alpha.11)_

A modal opens on top of the page and keeps the focus on a single task: confirm an action, fill in a short form, look at the details — without taking you away from the current screen. While the modal is open, the page behind it is dimmed, does not scroll and does not accept clicks.

**See also:** For a list of actions on an element take CdsMenu, for a short hint — CdsTooltip, for a notification about the result — CdsToast. Complex modal content — a header, scrollable text and a row of buttons — is assembled from CdsCard.

## Variations

### Activators

The modal is opened by an activator element — you can set it in three ways:

1. **Through the `activator` slot** — the props from the slot (`v-bind="props"`)
   attach the handlers and the aria attributes to the element. The default way.
2. **Through the parent** — `activator="parent"` takes the element that
   `CdsModal` is placed inside of.
3. **Through a selector** — `activator="#id"` links the modal to any element on
   the page, even a distant one in the markup.

**Example — `Activators.vue`:**

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

const slotModal = ref(false);
const parentModal = ref(false);
const siblingModal = ref(false);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsModal v-model="slotModal">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Активатор в слоте</CdsButton>
      </template>

      <span class="h4">Заголовок</span>
      <p>Модальное окно открыто активатором из слота</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="slotModal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>

    <CdsButton>
      Родительский элемент

      <CdsModal v-model="parentModal" activator="parent">
        <span class="h4">Заголовок</span>
        <p>Модальное окно открыто родительским элементом</p>

        <div class="mt-4 flex justify-end">
          <CdsButton @click="parentModal = false">Закрыть</CdsButton>
        </div>
      </CdsModal>
    </CdsButton>

    <CdsButton id="modal-activator">Соседний элемент</CdsButton>
    <CdsModal v-model="siblingModal" activator="#modal-activator">
      <span class="h4">Заголовок</span>
      <p>Модальное окно открыто соседним элементом по CSS-селектору</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="siblingModal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>
```

### Using v-model

The state of the modal can be controlled directly through `v-model` — without an
activator. This is how you open a modal from code: on a server response, from a
handler in a table, from a store.

**Example — `VModel.vue`:**

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

const modal = ref(false);
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsButton @click="modal = true">Открыть модальное окно</CdsButton>

    <CdsModal v-model="modal">
      <div class="flex items-center justify-between">
        <span class="h4">Заголовок</span>
        <CdsFunctionalButton icon="remove" aria-label="Закрыть" @click="modal = false" />
      </div>

      <p>Модальное окно без активатора: состоянием управляет v-model</p>
    </CdsModal>

    <div class="text-content-primary"><strong>v-model:</strong> {{ modal }}</div>
  </div>
</template>
```

### Sizes

The `size` prop sets the width of the modal: `xs` (250), `sm` (350), `md` (500,
the default), `lg` (700), `xl` — almost the full width of the screen. A number
instead of an alias is an exact width in pixels. The height always adapts to the
content, and `width` and `max-width` override the size when you need a
non-standard grid.

**Example — `Sizes.vue`:**

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

const sizes: Size[] = ['xs', 'sm', 'md', 'lg', 'xl'];

const size = ref<Size>('md');
const modal = ref(false);

const open = (value: Size) => {
  size.value = value;
  modal.value = true;
};
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton v-for="item in sizes" :key="item" variant="soft" color="brand" @click="open(item)">
      {{ item }}
    </CdsButton>

    <CdsModal v-model="modal" :size="size">
      <span class="h4">Размер {{ size }}</span>
      <p>Ширина окна задана пропом <code>size</code></p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="modal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>
```

### Persistent modals

The `persistent` prop turns off closing by a click outside the modal and by the
`Esc` key — the modal can only be closed with the buttons inside it. A click
outside shakes the modal, hinting that an answer is still required; the
animation is removed by `no-click-animation`. Take `persistent` when closing
would lose data or when the user has to make a choice.

**Example — `Persistent.vue`:**

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

const modal = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" persistent size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Открыть модальное окно</CdsButton>
      </template>

      <span class="h4">Подтвердите действие</span>
      <p>Клик мимо окна и клавиша <code>Esc</code> его не закроют — ответьте одной из кнопок.</p>

      <div class="mt-4 flex justify-end gap-3">
        <CdsButton variant="soft" color="neutral" @click="modal = false">Отменить</CdsButton>
        <CdsButton @click="modal = false">Подтвердить</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>
```

### Scrolling inside the modal

By default long content scrolls together with the whole modal. The `scrollable`
prop pins the header and the buttons and scrolls only the middle — for that the
content is assembled from CdsCard: the card becomes
the surface of the modal, and the scrolling area is its `CdsCardText`.

**Example — `Scrollable.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardText,
  CdsDivider,
  CdsModal,
  CdsRadio,
  CdsRadioGroup
} from '@central-design-system/components';
import { ref } from 'vue';

const modal = ref(false);
const country = ref(null);

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

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" scrollable size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Выбрать страну</CdsButton>
      </template>

      <template #default="{ isActive }">
        <CdsCard prepend-icon="search" title="Выберите страну">
          <CdsDivider />

          <CdsCardText class="h-[300px]">
            <CdsRadioGroup v-model="country">
              <CdsRadio v-for="item of countries" :key="item" :label="item" :value="item" />
            </CdsRadioGroup>
          </CdsCardText>

          <CdsDivider />

          <CdsCardActions class="justify-end gap-2">
            <CdsButton text="Сохранить" @click="isActive.value = false" />
          </CdsCardActions>
        </CdsCard>
      </template>
    </CdsModal>
  </div>
</template>
```

### Fullscreen

The `fullscreen` prop expands the modal to the whole screen: the size props are
ignored, the paddings and the rounded corners are removed. It fits document
viewing and complex forms on small screens.

**Example — `Fullscreen.vue`:**

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

const modal = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" fullscreen>
      <template #activator="{ props }">
        <CdsButton v-bind="props">Открыть на весь экран</CdsButton>
      </template>

      <div class="flex items-center justify-between">
        <span class="h4">Окно на весь экран</span>
        <CdsFunctionalButton icon="remove" aria-label="Закрыть" @click="modal = false" />
      </div>

      <p class="mt-2">
        Проп <code>fullscreen</code> разворачивает окно на весь экран: пропсы размеров игнорируются, скругления и
        отступы от краёв убираются. Такой режим подходит для просмотра документов и сложных форм на небольших экранах.
      </p>

      <div class="mt-auto flex justify-end">
        <CdsButton @click="modal = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>
```

### Animations

By default the modal grows out of the activator and shrinks back — so you can
see where it came from. The `transition` prop changes the animation: the ready
`modal-transition-top` and `modal-transition-bottom` slide the modal in from the
edge of the screen, and any custom CSS animation works too.

**Example — `Transition.vue`:**

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

const modalTop = ref(false);
const modalBottom = ref(false);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsModal v-model="modalTop" transition="modal-transition-top" size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Сверху</CdsButton>
      </template>

      <span class="h4">Заголовок</span>
      <p>Окно выезжает сверху</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="modalTop = false">Закрыть</CdsButton>
      </div>
    </CdsModal>

    <CdsModal v-model="modalBottom" transition="modal-transition-bottom" size="sm">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Снизу</CdsButton>
      </template>

      <span class="h4">Заголовок</span>
      <p>Окно выезжает снизу</p>

      <div class="mt-4 flex justify-end">
        <CdsButton @click="modalBottom = false">Закрыть</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>
```

### Slots

| Slot        | Description                                                                                                    |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| `activator` | The element that opens the modal. The slot props (`props`) attach the handlers to it                           |
| `default`   | The content of the modal. The slot exposes `isActive` — use it to close the modal without an external variable |

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The title names the action and the buttons answer it — you decide without rereading the text. | “Are you sure?” with “Yes / No” forces you to read the text closely to understand what will happen. |
| There is always a way back from the modal: a cancel button next to the main action and a close icon in the corner. | A single “Accept” button leaves no choice — the user is locked inside the modal. |
| The size of the modal matches its content: a short confirmation lives in a compact modal. | In a wide modal a single line of text gets lost and the eye wanders between the text and the buttons. |

## Scenarios

### Delete confirmation

An irreversible action is confirmed with a compact `size="sm"` modal: the title
names the action, the text specifies what exactly will be deleted, the main
button repeats the verb from the title. One modal serves the whole list — the
selected record is put into it right before opening.

**Example — `ConfirmDelete.vue`:**

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

const initial = ['Договор поставки № 42', 'Смета на монтаж', 'Акт сверки за июнь'];

const drafts = ref([...initial]);
const modal = ref(false);
const pending = ref('');

const askDelete = (draft: string) => {
  pending.value = draft;
  modal.value = true;
};

const confirmDelete = () => {
  drafts.value = drafts.value.filter((draft) => draft !== pending.value);
  modal.value = false;
};
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col items-center gap-2">
    <CdsList v-if="drafts.length" class="w-full">
      <CdsListItem v-for="draft in drafts" :key="draft" :title="draft">
        <template #append>
          <CdsFunctionalButton icon="delete" :aria-label="`Удалить: ${draft}`" @click="askDelete(draft)" />
        </template>
      </CdsListItem>
    </CdsList>

    <CdsButton v-else variant="soft" color="brand" @click="drafts = [...initial]">Восстановить список</CdsButton>

    <CdsModal v-model="modal" size="sm">
      <span class="h4">Удалить черновик?</span>
      <p class="mt-2">«{{ pending }}» будет удалён без возможности восстановления.</p>

      <div class="mt-4 flex justify-end gap-3">
        <CdsButton variant="soft" color="neutral" @click="modal = false">Отмена</CdsButton>
        <CdsButton @click="confirmDelete">Удалить</CdsButton>
      </div>
    </CdsModal>
  </div>
</template>
```

### A form in a modal

A short form is opened on top of the list so that the user is not taken away to
a separate page. `persistent` protects what has been typed from an accidental
click outside, the submit button shows `loading`, and "Cancel" is blocked while
the request is running. The fields are reset in the `after-leave` event — after
the closing animation, so that the values do not flash in a still visible modal.

**Example — `FormModal.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardText,
  CdsDivider,
  CdsForm,
  CdsModal,
  CdsTextInput
} from '@central-design-system/components';
import { ref } from 'vue';

const modal = ref(false);
const loading = ref(false);
const name = ref('');
const email = ref('');

const submit = async () => {
  loading.value = true;

  // Имитация запроса к серверу
  await new Promise((resolve) => setTimeout(resolve, 1500));

  loading.value = false;
  modal.value = false;
};

const reset = () => {
  name.value = '';
  email.value = '';
};
</script>

<template>
  <div class="flex justify-center">
    <CdsModal v-model="modal" persistent size="sm" @after-leave="reset">
      <template #activator="{ props }">
        <CdsButton v-bind="props">Пригласить сотрудника</CdsButton>
      </template>

      <CdsForm @submit.prevent="submit">
        <CdsCard title="Пригласить сотрудника">
          <CdsDivider />

          <CdsCardText class="flex flex-col gap-2">
            <CdsTextInput v-model="name" label="Имя" />
            <CdsTextInput v-model="email" label="Рабочая почта" placeholder="name@company.ru" />
          </CdsCardText>

          <CdsDivider />

          <CdsCardActions class="justify-end gap-2">
            <CdsButton variant="soft" color="neutral" :disabled="loading" @click="modal = false">Отмена</CdsButton>
            <CdsButton type="submit" :loading="loading">Отправить приглашение</CdsButton>
          </CdsCardActions>
        </CdsCard>
      </CdsForm>
    </CdsModal>
  </div>
</template>
```

### An agreement with scrolling

A document that requires an explicit answer is shown in a modal with `persistent`
and `scrollable`: the text scrolls, and the "Accept" and "Decline" buttons are
always in sight. Closing the modal without answering is not possible — the
decision is recorded only with the buttons.

**Example — `TermsAgreement.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardText,
  CdsDivider,
  CdsModal
} from '@central-design-system/components';
import { ref } from 'vue';

const modal = ref(false);
const accepted = ref<boolean | null>(null);

const answer = (value: boolean) => {
  accepted.value = value;
  modal.value = false;
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsButton @click="modal = true">Открыть условия</CdsButton>

    <div v-if="accepted !== null" class="text-content-primary">
      {{ accepted ? 'Условия приняты' : 'Условия отклонены' }}
    </div>

    <CdsModal v-model="modal" persistent scrollable size="sm">
      <CdsCard title="Условия использования">
        <CdsDivider />

        <CdsCardText class="h-[300px]">
          <p v-for="n in 6" :key="n" class="mb-2">
            {{ n }}. Стороны признают юридическую силу документов, подписанных в системе, и обязуются соблюдать
            конфиденциальность учётных данных. Оператор вправе обновлять условия, уведомив пользователей заранее.
          </p>
        </CdsCardText>

        <CdsDivider />

        <CdsCardActions class="justify-end gap-2">
          <CdsButton variant="soft" color="neutral" @click="answer(false)">Отклонить</CdsButton>
          <CdsButton @click="answer(true)">Принять</CdsButton>
        </CdsCardActions>
      </CdsCard>
    </CdsModal>
  </div>
</template>
```

## API

### CdsModal

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the element absolutely instead of fixed. This is useful for overlays that must stay inside a certain area, for example inside a container with `position: relative`. |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `captureFocus` | `boolean \| undefined` | `true` | no | Returns the focus back into the content if it has left it — for example on Tab from the end of the page. A mouse click does not steal the focus. |
| `closeDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeOnBack` | `boolean \| undefined` | `true` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | — | no | Hide the component on a click on the content |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `fullscreen` | `boolean \| undefined` | — | no | Expands the modal to the whole screen. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `location` | `Anchor \| undefined` | `'center center'` | no | Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'static'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | — | no | The v-model value of the component. If the component supports the **multiple** prop, an empty array is used by default. |
| `noClickAnimation` | `boolean \| undefined` | — | no | Disables the bounce effect on a click outside the content element when `persistent` is set. |
| `offset` | `string \| number \| number[] \| undefined` | — | no | Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | — | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | — | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'center center'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `persistent` | `boolean \| undefined` | — | no | A click outside the element or the Esc key does not close it. |
| `retainFocus` | `boolean \| undefined` | `true` | no | Traps Tab navigation inside the content: from the last focusable element the focus moves to the first one and back. |
| `scrim` | `string \| boolean \| undefined` | `true` | no | Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color. |
| `scrollable` | `boolean \| undefined` | — | no | Enables scrolling of the content inside the modal. |
| `scrollStrategy` | `"none" \| "close" \| "block" \| "reposition" \| ScrollStrategyFunction \| undefined` | `'block'` | no | Strategy applied when the component is active and the user scrolls the page. |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `stickToTarget` | `boolean \| undefined` | — | no | Lets the overlay content go off screen while scrolling. |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| { component: Component; } \| null \| undefined` | `{ component: CdsModalTransition }` | no | Transition animation |
| `viewportMargin` | `string \| number \| undefined` | `12` | no | Sets a custom viewport margin for the overlay content |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2400` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `afterEnter` | `[]` | Fired after the opening animation of the modal has finished. |
| `afterLeave` | `[]` | Fired after the closing animation of the modal has finished. |
| `update:modelValue` | `[value: boolean]` | Fired when the state of the modal changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `activator` | `{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }` | Slot for the element that acts as the activator of the overlay. |
| `default` | `{ isActive: Ref<boolean, boolean>; }` | Slot for the overlay content. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activatorEl` | `HTMLElement \| undefined` | The DOM element of the activator. |
| `activatorRef` | `TemplateRef` | Template ref for assigning the activator manually. |
| `animateClick` | `() => void` | Runs the bounce animation of the content — the same as on a click outside a `persistent` overlay. |
| `contentEl` | `HTMLElement \| undefined` | The DOM element of the overlay content. |
| `globalTop` | `boolean` | Whether the overlay is the top one in the global stack of open overlays. |
| `rootEl` | `HTMLElement \| undefined` | The root DOM element of the overlay. |
| `scrimEl` | `HTMLElement \| undefined` | The DOM element of the scrim that dims the page. |
| `targetEl` | `HTMLElement \| undefined` | The DOM element of the positioning target. |
| `targetRef` | `TemplateRef` | Template ref for assigning the positioning target manually. |
| `updateLocation` | `((e: Event) => void) \| undefined` | Recalculates the position of the content relative to the target. |

---

# CdsNotification

_Category: Feedback · since 4.0.0_

_Tests: API 23/23 · 49 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 4 axe recommendations (v4.0.0-alpha.11)_

A notification is a block with a message about an event or a state: a successful save, a warning about a limit, a loading error. The semantic status sets the color and the icon, and the display modes let you embed the message into a form, a card or a list.

**See also:** For pop-up messages above the page that disappear on their own take CdsToast. For a short status label in a row or a card — CdsTag.

## Anatomy

A notification consists of a status icon, a content column — heading, text and
actions — and a close button. Every part can be replaced by the slot of the same
name.

## Variations

### Statuses

The `status` prop sets the semantics of the message — its color and its icon.
The default status is `info`.

**Example — `Statuses.vue`:**

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

const statuses = CdsNotification.constants.statuses;
</script>

<template>
  <div class="flex flex-col gap-2 max-w-[640px] m-auto">
    <CdsNotification
      v-for="status in statuses"
      :key="status"
      :status="status"
      title="Заголовок уведомления"
      text="Описание события, на которое стоит обратить внимание"
    />
  </div>
</template>
```

### Display modes

The `variant` prop changes the styling: `default` — with a border, `flat` —
without a border, `compact` — a single line, `important` — a neutral background
and a shadow for showing above the content.

**Example — `Variants.vue`:**

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

const variants = CdsNotification.constants.variants;
</script>

<template>
  <div class="flex flex-col gap-4 max-w-[720px] m-auto">
    <div v-for="variant in variants" :key="variant" class="flex items-center gap-2">
      <span class="w-[96px] text-content-secondary text-100">{{ variant }}</span>
      <CdsNotification
        :variant="variant"
        title="Заголовок уведомления"
        text="Описание события, на которое стоит обратить внимание"
        closable
        class="flex-1"
      />
    </div>
  </div>
</template>
```

`variant="compact"` puts the icon, the text and the actions on one line and
hides the heading. It fits tight places: a filter panel, a table row, the footer
of a card.

**Example — `Compact.vue`:**

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

const statuses = CdsNotification.constants.statuses;
</script>

<template>
  <div class="flex flex-col gap-2 w-[415px] m-auto">
    <CdsNotification
      v-for="status in statuses"
      :key="status"
      :status="status"
      variant="compact"
      text="Текст уведомления"
      closable
    >
      <template #actions>
        <CdsButton size="sm" text="Кнопка" />
      </template>
    </CdsNotification>
  </div>
</template>
```

### Icons

By default the icon matches the status. The `icon` prop replaces it with any
icon from the pack, and the value `false` removes it altogether.

**Example — `Icons.vue`:**

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

<template>
  <div class="flex flex-col gap-2 max-w-[640px] m-auto">
    <CdsNotification
      status="success"
      icon="trophy"
      title="Вы выиграли торги"
      text="Иконка задана пропом icon вместо иконки статуса"
    />
    <CdsNotification :icon="false" title="Без иконки" text="Значение icon: false скрывает иконку статуса" />
  </div>
</template>
```

### Closing

The `closable` prop adds a close button; the visibility of the notification is
controlled through `v-model`. A click on the button also emits `click:close`.

The notification appears and leaves smoothly: it fades out first, then collapses
in height, so neighbouring blocks slide without a jump. `click:close` is emitted
right at the click, while `update:modelValue` arrives after the leave has finished,
so you can remove the item from a list in the handler without cutting the animation
short. Set the spacing between notifications in a list with `margin`: it collapses
together with the block, unlike `gap`, which makes a jump on leave. Under
`prefers-reduced-motion` only opacity changes.

**Example — `Closable.vue`:**

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

const initial = [
  { id: 1, title: 'Черновик сохранён', text: 'Изменения доступны только вам' },
  { id: 2, title: 'Лимит почти исчерпан', text: 'Осталось 2 из 10 запросов' },
  { id: 3, title: 'Документы загружены', text: 'Файлы проходят проверку' }
];

const items = ref(initial.map((item) => ({ ...item })));

function remove(id: number) {
  items.value = items.value.filter((item) => item.id !== id);
}
</script>

<template>
  <div class="max-w-[640px] m-auto">
    <CdsNotification
      v-for="item in items"
      :key="item.id"
      class="mb-2"
      :title="item.title"
      :text="item.text"
      closable
      @update:model-value="remove(item.id)"
    />
    <CdsButton v-if="!items.length" text="Вернуть уведомления" @click="items = initial.map((item) => ({ ...item }))" />
  </div>
</template>
```

### Slots

Slots replace the content coming from props when you need your own markup.

| Slot      | Description                                                |
| --------- | ---------------------------------------------------------- |
| `prepend` | Content before the text. Replaces the status icon          |
| `title`   | Heading. Replaces the text from `title`                    |
| `text`    | Message text. Replaces the text from `text`                |
| `default` | Arbitrary content after the text                           |
| `actions` | Actions (buttons, links) below the text                    |
| `append`  | Content after the content column                           |
| `close`   | Close button. Receives `props` to bind to your own element |

**Example — `Slots.vue`:**

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

<template>
  <CdsNotification class="max-w-[640px] m-auto">
    <template #title> Заголовок уведомления </template>
    <template #text> Описание уведомления, на которое пользователь <strong>должен обратить внимание</strong> </template>
    <template #actions>
      <CdsButton text="Опубликовать" />
    </template>
    <template #close="{ props }">
      <CdsFunctionalButton v-bind="props" />
    </template>
  </CdsNotification>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The status matches the meaning of the message: success — the action went through. | Danger for neutral news is alarming: the reader looks for an error that is not there. |
| The heading names the event briefly, the details go into the text. | A long heading with no text is hard to read, and the event gets lost. |
| One or two secondary actions help the user react to the event. | Primary buttons inside a notification compete with the main action of the screen. |

## Scenarios

### Form submission result

After a successful request a notification with the `success` status appears
through `v-model` and confirms the result. The `closable` prop lets the user
dismiss the message once it is read.

**Example — `FormResult.vue`:**

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

const email = ref('');
const loading = ref(false);
const sent = ref(false);

async function submit() {
  loading.value = true;
  sent.value = false;

  // Имитация запроса к серверу
  await new Promise((resolve) => setTimeout(resolve, 1200));

  loading.value = false;
  sent.value = true;
}
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsNotification
      v-model="sent"
      status="success"
      title="Приглашение отправлено"
      :text="`Письмо со ссылкой ушло на ${email || 'указанную почту'}`"
      closable
    />

    <CdsTextInput v-model="email" label="Рабочая почта" placeholder="name@company.ru" />

    <CdsButton class="self-start" type="submit" text="Отправить приглашение" :loading="loading" />
  </CdsForm>
</template>
```

### A warning with an action

A `warning` notification does not just report a problem — it offers a solution
right away with a button in the `actions` slot. On click the status changes to
`progress`, and after the server responds — to `success`: the user sees the
whole course of the operation in a single block.

**Example — `EmailConfirmation.vue`:**

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

type Step = 'warning' | 'progress' | 'success';

const step = ref<Step>('warning');

const content: Record<Step, { title: string; text: string }> = {
  warning: {
    title: 'Почта не подтверждена',
    text: 'Подтвердите почту, чтобы получать уведомления о ходе торгов'
  },
  progress: {
    title: 'Отправляем письмо…',
    text: 'Обычно это занимает меньше минуты'
  },
  success: {
    title: 'Письмо отправлено',
    text: 'Проверьте входящие на name@company.ru и перейдите по ссылке'
  }
};

async function resend() {
  step.value = 'progress';

  // Имитация запроса к серверу
  await new Promise((resolve) => setTimeout(resolve, 1500));

  step.value = 'success';
}
</script>

<template>
  <div class="max-w-[640px] m-auto">
    <CdsNotification :status="step" :title="content[step].title" :text="content[step].text">
      <template v-if="step === 'warning'" #actions>
        <CdsButton size="sm" variant="soft" color="brand" text="Отправить письмо ещё раз" @click="resend" />
      </template>
    </CdsNotification>
  </div>
</template>
```

### Loading error with a retry

If the data failed to load, a `danger` notification explains what happened and
offers to repeat the request. The `progress` status shows that the retry is
already running.

**Example — `LoadError.vue`:**

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

type Step = 'danger' | 'progress' | 'success';

const step = ref<Step>('danger');

const content: Record<Step, { title: string; text: string }> = {
  danger: {
    title: 'Не удалось загрузить список закупок',
    text: 'Сервер не ответил вовремя — данные могли устареть'
  },
  progress: {
    title: 'Обновляем данные…',
    text: 'Запрашиваем актуальный список закупок'
  },
  success: {
    title: 'Данные обновлены',
    text: 'Список закупок актуален'
  }
};

async function retry() {
  step.value = 'progress';

  // Имитация повторного запроса
  await new Promise((resolve) => setTimeout(resolve, 1500));

  step.value = 'success';
}
</script>

<template>
  <div class="max-w-[640px] m-auto">
    <CdsNotification :status="step" :title="content[step].title" :text="content[step].text">
      <template v-if="step === 'danger'" #actions>
        <CdsButton size="sm" variant="soft" color="brand" text="Повторить" @click="retry" />
      </template>
    </CdsNotification>
  </div>
</template>
```

## API

### CdsNotification

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `closable` | `boolean \| undefined` | — | no | Adds a close button that hides the notification. |
| `closeIcon` | `IconValue \| undefined` | `'close'` | no | Icon of the close button. |
| `closeLabel` | `string \| undefined` | `'$cds.close'` | no | Accessible label (aria-label) for the close button. |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `icon` | `false \| IconValue \| undefined` | `null` | no | Icon before the content. Taken from `status` by default; `false` hides the icon. |
| `modelValue` | `boolean \| undefined` | `true` | no | Visibility of the notification (v-model). When `false`, the notification is not rendered. |
| `status` | `"progress" \| "danger" \| "success" \| "warning" \| "info" \| undefined` | `'info'` | no | Semantic status — drives the color and the default icon. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `title` | `string \| undefined` | — | no | Notification heading. |
| `variant` | `"default" \| "flat" \| "compact" \| "important" \| undefined` | `'default'` | no | Display mode: `default` — regular; `flat` — borderless; `compact` — single line without a heading; `important` — neutral background and a shadow, where the status only drives the content colors. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:close` | `[event: MouseEvent]` | Click on the close button. |
| `update:modelValue` | `[value: boolean]` | The visibility of the notification changed. On close by the button it arrives after the leave animation ends, not at the click. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `any` | Slot for actions (buttons, links) below the text. |
| `append` | `any` | Slot after the content. |
| `close` | `{ props: Record<string, any>; }` | Close button slot; receives `props` to bind to your own element. |
| `default` | `any` | Main content of the notification (complements `text`). |
| `prepend` | `any` | Slot before the content (the status icon by default). |
| `text` | `any` | Text slot (instead of the `text` prop). |
| `title` | `any` | Heading slot (instead of the `title` prop). |

---

# CdsNotificationAlert

_Category: Feedback · since 4.0.0 · status: deprecated_

_Tests: API 65/65 · 46 unit · 1 e2e · 6 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 4 axe recommendations (v4.0.0-alpha.11)_

A pop-up notification above the page — the counterpart of `CdsNotificationAlert` from CDS 3. It is assembled from CdsOverlay and CdsNotification in the `important` variant; it hides automatically after `timeout`, while hovering the cursor or focusing inside pauses the timer.

**See also:** The component exists only for a smooth migration from CDS 3 and will be removed. For new scenarios use CdsToast.

## Variations

### Controlling the display

Visibility is controlled through `v-model` or the `activator` slot — the element
inside the slot opens the notification on click. The text comes from the `text`
prop.

**Example — `Default.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsNotificationAlert text="Изменения сохранены">
      <template #activator="{ props }">
        <CdsButton text="Показать уведомление" v-bind="props" />
      </template>
    </CdsNotificationAlert>
  </div>
</template>
```

### Statuses

The `status` prop sets the color of the content and the icon: `info`, `success`,
`warning`, `danger`, `progress`. The icon can be replaced by the `icon` prop or
hidden with the value `false`.

**Example — `Statuses.vue`:**

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

const statuses = CdsNotificationAlert.constants.statuses;
</script>

<template>
  <div class="flex justify-center gap-2">
    <CdsButton v-for="status in statuses" :key="status" :color="'status-' + status + '-surface'" variant="solid">
      {{ status }}
      <CdsNotificationAlert activator="parent" :status="status" :text="'Уведомление со статусом ' + status" />
    </CdsButton>
  </div>
</template>
```

### Positions

The `location` prop sets the position on the screen: the side (`top`, `bottom`)
and the alignment (`left`, `center`, `right`).

**Example — `Positions.vue`:**

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

const locations = ['top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'] as const;
</script>

<template>
  <div class="grid grid-cols-3 justify-items-center gap-2">
    <CdsButton v-for="location in locations" :key="location" variant="soft" color="neutral">
      {{ location }}
      <CdsNotificationAlert activator="parent" :location="location" :text="'Уведомление в позиции ' + location" />
    </CdsButton>
  </div>
</template>
```

### Auto-closing

The `timeout` prop controls the auto-close delay in milliseconds, 5000 by
default. The values `-1` and `0` turn auto-closing off — the notification stays
until the user closes it (`closable`). Hovering the cursor and focusing inside
pause the countdown.

**Example — `Timeout.vue`:**

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

<template>
  <div class="flex justify-center gap-2">
    <CdsNotificationAlert :timeout="4000" text="Уведомление закроется через 4 секунды">
      <template #activator="{ props }">
        <CdsButton text="Закроется через 4 секунды" v-bind="props" />
      </template>
    </CdsNotificationAlert>
    <CdsNotificationAlert :timeout="-1" closable status="info" text="Останется до закрытия вручную">
      <template #activator="{ props }">
        <CdsButton text="Без автозакрытия" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsNotificationAlert>
  </div>
</template>
```

## Scenarios

### Undoing an action

After an irreversible operation the notification gives a short window to undo
it: the button in the `actions` slot closes it through `v-model`, and an
increased `timeout` leaves time to change one's mind.

**Example — `WithActions.vue`:**

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

const isActive = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Удалить черновик" variant="soft" color="brand" @click="isActive = true" />
    <CdsNotificationAlert
      v-model="isActive"
      title="Черновик удалён"
      text="Черновик заявки №42 удалён без возможности восстановления"
      status="warning"
      closable
      :timeout="8000"
    >
      <template #actions>
        <CdsButton text="Отменить" variant="soft" color="neutral" @click="isActive = false" />
      </template>
    </CdsNotificationAlert>
  </div>
</template>
```

### A stack of notifications

Every instance is an independent overlay: notifications sharing a position pile
up into a vertical stack. On close (`update:model-value` → `false`) remove the
item from the list.

**Example — `Cascade.vue`:**

```vue
<script setup lang="ts">
import type { Anchor } from '@central-design-system/components';
import { CdsButton, CdsNotificationAlert } from '@central-design-system/components';
import { reactive } from 'vue';

const statuses = CdsNotificationAlert.constants.statuses;

type Notification = {
  id: string;
  modelValue: boolean;
  status: (typeof statuses)[number];
  text: string;
  location: Anchor;
  closable: boolean;
};

const notifications = reactive<Notification[]>([]);
let uid = 0;

function addNotification(text: string, location: Anchor) {
  notifications.push({
    id: String(uid++),
    modelValue: true,
    status: statuses[Math.floor(Math.random() * statuses.length)],
    text,
    location,
    closable: true
  });
}

function onUpdateModelValue(value: boolean, id: string) {
  if (value) return;

  const index = notifications.findIndex((notification) => notification.id === id);
  if (index !== -1) notifications.splice(index, 1);
}
</script>

<template>
  <div class="flex gap-4 justify-around">
    <CdsButton text="Сверху слева" @click="addNotification('Тестовое уведомление', 'top left')" />
    <CdsButton
      text="Снизу справа"
      variant="soft"
      color="brand"
      @click="addNotification('Тестовое уведомление', 'bottom right')"
    />
    <CdsNotificationAlert
      v-for="notification in notifications"
      :key="notification.id"
      title="Заголовок"
      v-bind="notification"
      @update:model-value="(value) => onUpdateModelValue(value, notification.id)"
    >
      <template #actions>
        <CdsButton text="Кнопка" variant="soft" color="neutral" />
      </template>
    </CdsNotificationAlert>
  </div>
</template>
```

## API

### CdsNotificationAlert

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the element absolutely instead of fixed. This is useful for overlays that must stay inside a certain area, for example inside a container with `position: relative`. |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `closable` | `boolean \| undefined` | — | no | Adds a close button that hides the notification. |
| `closeDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeIcon` | `IconValue \| undefined` | `'close'` | no | Icon of the close button. |
| `closeLabel` | `string \| undefined` | `'$cds.close'` | no | Accessible label (aria-label) for the close button. |
| `closeOnBack` | `boolean \| undefined` | `false` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | — | no | Hide the component on a click on the content |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `icon` | `false \| IconValue \| undefined` | `null` | no | Icon before the content. Taken from `status` by default; `false` hides the icon. |
| `location` | `Anchor \| null \| undefined` | `'top center'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'static'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | — | no | The v-model value of the component. If the component supports the **multiple** prop, an empty array is used by default. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | — | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | — | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'auto'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
| `status` | `"progress" \| "danger" \| "success" \| "warning" \| "info" \| undefined` | `'info'` | no | Semantic status — drives the color and the default icon. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `timeout` | `string \| number \| undefined` | `5000` | no | Delay in milliseconds before the notification hides automatically. The values `-1` and `0` turn auto-closing off. |
| `title` | `string \| undefined` | — | no | Notification heading. |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'notification-transition'` | no | Transition animation |
| `variant` | `"default" \| "flat" \| "compact" \| "important" \| undefined` | `'important'` | no | Appearance of the notification. `important` by default — an elevated surface with a shadow (the CdsNotificationAlert look). |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2000` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:close` | `[event: MouseEvent]` | Click on the close button. |
| `update:modelValue` | `[value: boolean]` | The visibility of the notification changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `any` | Slot for actions (buttons, links) below the text. |
| `activator` | `{ isActive: boolean; props: Record<string, any>; }` | Activator slot that controls the display of the notification. |
| `append` | `any` | Slot after the content. |
| `close` | `{ props: Record<string, any>; }` | Close button slot; receives `props` to bind to your own element. |
| `default` | `any` | Main content of the notification (complements `text`). |
| `prepend` | `any` | Slot before the content (the status icon by default). |
| `text` | `any` | Text slot (instead of the `text` prop). |
| `title` | `any` | Heading slot (instead of the `title` prop). |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activatorEl` | `HTMLElement \| undefined` | The DOM element of the activator. |
| `activatorRef` | `TemplateRef` | Template ref for assigning the activator manually. |
| `animateClick` | `() => void` | Runs the bounce animation of the content — the same as on a click outside a `persistent` overlay. |
| `contentEl` | `HTMLElement \| undefined` | The DOM element of the overlay content. |
| `globalTop` | `boolean` | Whether the overlay is the top one in the global stack of open overlays. |
| `rootEl` | `HTMLElement \| undefined` | The root DOM element of the overlay. |
| `scrimEl` | `HTMLElement \| undefined` | The DOM element of the scrim that dims the page. |
| `targetEl` | `HTMLElement \| undefined` | The DOM element of the positioning target. |
| `targetRef` | `TemplateRef` | Template ref for assigning the positioning target manually. |
| `updateLocation` | `((e: Event) => void) \| undefined` | Recalculates the position of the content relative to the target. |

---

# CdsOtpInput

_Category: Controls · since 4.0.0 · status: new_

_Tests: API 44/44 · 78 unit · 3 e2e · 5 known bugs · lines 93.4% (v4.0.0-alpha.13) · a11y: 3 axe recommendations (v4.0.0-alpha.11)_

A field for entering a one-time code — from an SMS, an email or an authenticator app. It looks like a row of separate cells, but the input is taken by a single hidden `input`: that is why the SMS autofill, pasting a whole string from the clipboard, selection and the arrow keys all work, and the focus does not have to be jumped between the cells by hand.

**See also:** For an ordinary short text or number take CdsTextInput: `CdsOtpInput` is needed where the length of the input is known upfront and every character is shown in its own cell.

## Anatomy

The cells (`CdsOtpField`) only draw the code — the entered character, the
placeholder or the blinking caret. The real input is taken by a hidden `input`:
it is pressed to the bottom edge of the component, so the SMS autofill suggestion
appears under the cells and covers nothing. A separator (`CdsOtpSeparator`) may
stand between the cells, and in the merged look the cells are gathered into a
group (`CdsOtpGroup`).

## Variations

### Length and type of the code

The `length` prop sets the number of cells, `type` — what may be entered:
`number` (the default) accepts digits only and opens the numeric keyboard on
mobile, `text` — any characters, `password` additionally hides what is entered
behind dots. The same effect without changing the type is given by `masked`.

**Example — `LengthAndType.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput :length="4" model-value="1234" />
    <CdsOtpInput type="text" model-value="AB12CD" />
    <CdsOtpInput type="password" model-value="123456" />
  </div>
</template>
```

### Allowed characters

The `pattern` prop narrows the set of characters: the name of a ready set
(`numeric`, `alpha`, `alphanumeric`, `unicode-alpha`, `unicode-alphanumeric`) or
your own regular expression. The check goes character by character — the extra
ones will not get into the field, neither from the keyboard nor from the
clipboard.

**Example — `Pattern.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput type="text" pattern="alpha" :length="4" placeholder="A" />
    <CdsOtpInput type="text" pattern="alphanumeric" placeholder="X" />
    <CdsOtpInput type="text" :pattern="/[0-9A-F]/" placeholder="F" />
  </div>
</template>
```

### Separator

The `divider` prop puts a character between the cells — a hyphen in a code like
`123-456`, for example. The `divider` slot gives full freedom of markup and
receives `index` — the number of the cell to the left of the separator, so the
separator can be placed only where it is needed.

**Example — `Divider.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsOtpInput } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput divider="-" model-value="123456" />

    <CdsOtpInput model-value="123456">
      <template #divider="{ index }">
        <CdsIcon v-if="index === 2" name="minus" size="sm" />
      </template>
    </CdsOtpInput>
  </div>
</template>
```

### Merged look

The `merged` prop removes the gaps: the cells become a single field with a common
border. This look is more compact and breaks the form up less.

**Example — `Merged.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsOtpInput merged model-value="1234" />
  </div>
</template>
```

### Placeholder

The `placeholder` prop shows a character in the empty cells — a hint about the
format or simply a dot, so that the row does not look empty.

**Example — `Placeholder.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput placeholder="0" />
    <CdsOtpInput placeholder="•" />
  </div>
</template>
```

### Sizes

The `size` prop changes the height of the cells and the font size. The default
size is `md`.

**Example — `Sizes.vue`:**

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

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput v-for="size of sizes" :key="size" :size="size" :length="4" model-value="1234" />
  </div>
</template>
```

### States

`disabled` blocks the input, `error` highlights the whole row with the error
color, `loading` shows an indicator on top of the cells and does not erase the
entered code. `focus-all` highlights the whole row while the field is focused,
not just the active cell.

**Example — `States.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsOtpInput :length="4" model-value="12" disabled />
    <CdsOtpInput :length="4" model-value="1234" error />
    <CdsOtpInput :length="4" model-value="1234" loading />
    <CdsOtpInput :length="4" model-value="12" focus-all />
  </div>
</template>
```

### Slots

| Slot      | Description                                                                                    |
| :-------- | :--------------------------------------------------------------------------------------------- |
| `fields`  | The whole row of cells — your own markup of `CdsOtpGroup`, `CdsOtpField` and `CdsOtpSeparator` |
| `divider` | The separator between the cells, `index` is the number of the cell to its left                 |
| `loader`  | Your own loading indicator (with `loading`)                                                    |
| `default` | Arbitrary content on top of the cells                                                          |

The `fields` slot is needed when the cells are gathered into groups: every
`CdsOtpField` receives its own `index`, and `CdsOtpGroup` joins the neighboring
cells into a common border.

**Example — `CustomFields.vue`:**

```vue
<script setup lang="ts">
import { CdsOtpField, CdsOtpGroup, CdsOtpInput, CdsOtpSeparator } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsOtpInput model-value="123456">
      <template #fields>
        <CdsOtpGroup merged>
          <CdsOtpField v-for="index of [0, 1, 2]" :key="index" :index="index" />
        </CdsOtpGroup>

        <CdsOtpSeparator>—</CdsOtpSeparator>

        <CdsOtpGroup merged>
          <CdsOtpField v-for="index of [3, 4, 5]" :key="index" :index="index" />
        </CdsOtpGroup>
      </template>
    </CdsOtpInput>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The number of cells equals the length of the code — the user sees at once how many characters to enter. | Extra cells make the user guess whether the whole code has been entered. |
| The whole code is entered in one field: pasting from the clipboard and SMS autofill both work. | Separate text fields break code pasting and force the user to move the focus by hand. |
| On an error the field stays available, and the text next to it says what to do next. | A blocked field with no explanation makes it impossible to fix the code. |

## Scenarios

### Confirmation by SMS

The `finish` event fires as soon as the whole code is entered — send the request
on it, a separate button is not needed. Turn on `loading` for the duration of the
check: the code stays on the screen and the field does not look broken. If the
server did not accept the code, `error` highlights the row, and the `reset()` and
`focus()` methods called through a ref clear the field and bring the cursor back
into it.

**Example — `SmsConfirmation.vue`:**

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

const otpRef = ref<InstanceType<typeof CdsOtpInput>>();

const code = ref('');
const loading = ref(false);
const status = ref<'idle' | 'success' | 'error'>('idle');

// Имитация проверки кода на сервере: верный код — 123456
function onFinish(value: string) {
  loading.value = true;
  status.value = 'idle';

  setTimeout(() => {
    loading.value = false;
    status.value = value === '123456' ? 'success' : 'error';

    if (status.value === 'error') {
      otpRef.value?.reset();
      otpRef.value?.focus();
    }
  }, 1000);
}
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <p class="text-200 text-content-secondary">Код отправлен на +7 999 000-00-00</p>

    <CdsOtpInput
      ref="otpRef"
      v-model="code"
      :loading="loading"
      :error="status === 'error'"
      @finish="onFinish"
      @update:model-value="status = 'idle'"
    />

    <p v-if="status === 'success'" class="text-200 text-status-success-content">Код подтверждён</p>
    <p v-else-if="status === 'error'" class="text-200 text-status-danger-content">
      Код неверный — введите последние цифры из SMS ещё раз
    </p>
    <p v-else class="text-200 text-content-tertiary">Введите 123456, чтобы увидеть подтверждение</p>
  </div>
</template>
```

### Resending the code

The "Send again" button opens on a timer — that way the user does not flood the
gateway with requests. Reset the field together with the new code: `reset()`
clears the cells, `focus()` puts the cursor into the first one, and the old code
does not mix with the new one.

**Example — `ResendCode.vue`:**

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

const otpRef = ref<InstanceType<typeof CdsOtpInput>>();

const code = ref('');
const seconds = ref(15);

let timer: ReturnType<typeof setInterval> | undefined;

function countdown() {
  clearInterval(timer);

  timer = setInterval(() => {
    seconds.value -= 1;

    if (seconds.value <= 0) clearInterval(timer);
  }, 1000);
}

function resend() {
  seconds.value = 15;
  countdown();

  otpRef.value?.reset();
  otpRef.value?.focus();
}

countdown();
onScopeDispose(() => clearInterval(timer));
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsOtpInput ref="otpRef" v-model="code" placeholder="•" />

    <CdsButton
      variant="soft"
      color="neutral"
      size="sm"
      :disabled="seconds > 0"
      :text="seconds > 0 ? `Отправить снова через ${seconds} с` : 'Отправить код снова'"
      @click="resend"
    />
  </div>
</template>
```

### A code inside a form

When the code is a part of the sign-in form, keep the confirmation button: it
gives an explicit moment of submission. The button waits until all the characters
are entered — the length of the code is visible from `v-model`, and `disabled` on
the field freezes the code that has already been confirmed.

**Example — `TwoFactorForm.vue`:**

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

const code = ref('');
const loading = ref(false);
const confirmed = ref(false);

const isComplete = computed(() => code.value.length === 6);

function submit() {
  loading.value = true;

  setTimeout(() => {
    loading.value = false;
    confirmed.value = true;
  }, 1000);
}
</script>

<template>
  <CdsForm class="flex flex-col items-center gap-3 w-[350px] m-auto" @submit.prevent="submit">
    <p class="text-200 text-content-secondary">Введите код из приложения-аутентификатора</p>

    <CdsOtpInput v-model="code" :disabled="confirmed" divider="-" />

    <CdsButton type="submit" text="Подтвердить вход" :disabled="!isComplete || confirmed" :loading="loading" block />

    <p v-if="confirmed" class="text-200 text-status-success-content">Вход подтверждён</p>
  </CdsForm>
</template>
```

## API

### CdsOtpInput

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `autofocus` | `boolean \| undefined` | — | no | Enables autofocus |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `divider` | `string \| undefined` | — | no | Separator character placed between the code cells |
| `error` | `boolean \| undefined` | — | no | Error state |
| `focusAll` | `boolean \| undefined` | — | no | Highlight all the cells while the field is focused, not only the active one |
| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `label` | `string \| undefined` | `'$cds.input.otp'` | no | Accessible name of the field (`aria-label`). Accepts a localization key such as `$cds.input.otp` |
| `length` | `string \| number \| undefined` | `6` | no | Number of code cells |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `masked` | `boolean \| undefined` | — | no | Hide the entered characters behind dots |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `merged` | `boolean \| undefined` | — | no | Merged look: the cells are joined into a single field with no gaps between them |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `string \| number \| undefined` | — | no | Value of the component (v-model) |
| `pattern` | `RegExp \| "numeric" \| "alpha" \| "alphanumeric" \| "unicode-alpha" \| "unicode-alphanumeric" \| undefined` | — | no | Allowed characters: the name of a ready pattern (`numeric`, `alpha`, `alphanumeric`, `unicode-alpha`, `unicode-alphanumeric`) or your own regular expression |
| `placeholder` | `string \| undefined` | — | no | Placeholder character shown in an empty cell |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `type` | `CdsOtpInputType \| undefined` | `'number'` | no | Type of the code being entered. `number` limits the input to digits, `password` hides the characters |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `finish` | `[value: string]` | Fires when the whole code has been entered |
| `update:focused` | `[focused: boolean]` | Fires when the field gains or loses focus |
| `update:modelValue` | `[value: string]` | Fires when the value of the component changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Arbitrary content on top of the code cells |
| `divider` | `{ index: number; }` | Separator between the cells. `index` is the number of the cell to the left of it |
| `fields` | `any` | Fully replaces the row of cells with your own markup made of `CdsOtpGroup`, `CdsOtpField` and `CdsOtpSeparator` |
| `loader` | `any` | Custom loading indicator |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `blur` | `() => void` | Remove the focus from the field |
| `focus` | `() => void` | Set the focus on the field |
| `inputRef` | `HTMLInputElement \| undefined` | Ref to the hidden input that receives the code |
| `isFocused` | `boolean \| undefined` | Focus state of the field |
| `reset` | `() => void` | Clear the entered code |

### CdsOtpField

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `index` | `number` | — | yes | Zero-based index of the cell |

### CdsOtpGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `merged` | `boolean \| null \| undefined` | `null` | no | Merged look of the group. Inherited from the parent `CdsOtpInput` by default |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | The code cells of the group |

### CdsOtpSeparator

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the separator |

---

# CdsOverlay

_Category: Content · since 4.0.0_

_Tests: API 57/57 · 96 unit · 10 e2e · 4 known bugs · lines 83.5% (v4.0.0-alpha.13) · a11y: 4 axe recommendations (v4.0.0-alpha.11)_

An overlay shows content on top of the page: it dims the page with a scrim, computes the position relative to an activator and manages the stacking order of the open layers. It is the base mechanism behind CdsModal, CdsMenu and CdsTooltip — take it when you need a popup of your own that is not among the ready-made ones.

**See also:** For common tasks there are ready-made components built on the overlay: a dialog — CdsModal, a list of actions next to an activator — CdsMenu, a hint on hover — CdsTooltip, notifications — CdsToast. CdsOverlay is for when none of them fits.

## Anatomy

An overlay consists of two parts: the scrim, which dims the page and intercepts
clicks, and the content — the contents of the `default` slot. The content is
moved to the end of `body`, so the overlay does not depend on the `overflow` and
`z-index` of the parent blocks.

## Variations

### Opening and closing

`v-model` controls the visibility. An open overlay closes on a click outside the
content and on the `Esc` key.

**Example — `Default.vue`:**

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

const overlay = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Показать оверлей" @click="overlay = true" />

    <CdsOverlay v-model="overlay" location="center center">
      <div class="w-[320px] rounded-200 bg-surface-primary p-4">
        <p>Оверлей открыт. Кликните мимо контента или нажмите <code>Esc</code>, чтобы закрыть его.</p>
      </div>
    </CdsOverlay>
  </div>
</template>
```

The `persistent` prop turns both ways off: the overlay closes only through
`v-model` — for example, by a button inside the content. On a click outside, the
content answers with a light "shake"; remove it with the `no-click-animation`
prop if you do not need the animation.

**Example — `Persistent.vue`:**

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

const overlay = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Открыть persistent-оверлей" @click="overlay = true" />

    <CdsOverlay v-model="overlay" persistent location="center center">
      <div class="flex w-[320px] flex-col gap-2 rounded-200 bg-surface-primary p-4">
        <p>Клик мимо и <code>Esc</code> не закрывают оверлей — контент отвечает лёгким «покачиванием».</p>
        <CdsButton class="self-end" variant="soft" color="brand" text="Закрыть" @click="overlay = false" />
      </div>
    </CdsOverlay>
  </div>
</template>
```

### Activator

The `activator` slot saves you from a manual `v-model`: pass the slot props
(`v-bind="props"`) to an element — and a click on it will open the overlay. The
`open-on-hover` and `open-on-focus` props switch the opening to hover or focus,
and `activator="parent"` makes the parent element the activator.

**Example — `Activator.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsOverlay location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Открыть через активатор" />
      </template>

      <div class="w-[320px] rounded-200 bg-surface-primary p-4">
        <p>Оверлей открылся кликом по активатору — <code>v-model</code> и свой обработчик не понадобились.</p>
      </div>
    </CdsOverlay>
  </div>
</template>
```

### Scrim

The scrim is on by default: it dims the page and shows that the interface under
the overlay is unavailable. The `:scrim="false"` prop removes it — a click
outside still closes the overlay. The `opacity` prop tunes the dimming density,
and a string in `scrim` sets a custom color for the scrim.

**Example — `Scrim.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Обычная подложка" />
      </template>
      <div class="w-[280px] rounded-200 bg-surface-primary p-4">Подложка по умолчанию.</div>
    </CdsOverlay>

    <CdsOverlay :scrim="false" location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Без подложки" />
      </template>
      <div class="w-[280px] rounded-200 border bg-surface-primary p-4">
        Страница под оверлеем не затемнена, клик мимо всё равно закрывает контент.
      </div>
    </CdsOverlay>

    <CdsOverlay opacity="0.9" location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" text="Плотная подложка" />
      </template>
      <div class="w-[280px] rounded-200 bg-surface-primary p-4">
        <code>opacity="0.9"</code> почти полностью скрывает страницу.
      </div>
    </CdsOverlay>
  </div>
</template>
```

### Limiting to a container

The `contained` prop locks the overlay inside the parent block: the scrim and
the content do not leave its bounds, and the rest of the page keeps working. The
parent must have `position: relative`. To center the content inside the block
rather than relative to the screen, pass the container to `target` and turn on
`location-strategy="connected"`.

**Example — `Contained.vue`:**

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

const container = ref<HTMLElement>();
const overlay = ref(false);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <div ref="container" class="relative h-[180px] overflow-hidden rounded-200 bg-surface-secondary p-4">
      <p>Оверлей появится поверх этого блока, а остальная страница продолжит работать.</p>

      <CdsOverlay
        v-model="overlay"
        contained
        location-strategy="connected"
        :target="container"
        location="center center"
        scroll-strategy="none"
      >
        <div class="rounded-200 bg-surface-primary p-4">Контент внутри блока</div>
      </CdsOverlay>
    </div>

    <CdsButton class="self-center" variant="soft" color="brand" text="Показать оверлей" @click="overlay = !overlay" />
  </div>
</template>
```

### Positioning

By default the content is centered relative to the screen — this is what the
`static` strategy and the `location` prop are responsible for. The
`location-strategy="connected"` strategy attaches the content to the activator:
`location` sets the side, `offset` — the distance to it. If there is not enough
room near the screen edge, the content flips to the opposite side — that is how
CdsMenu works.

**Example — `Connected.vue`:**

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

const locations = ['top', 'bottom', 'end'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay
      v-for="location in locations"
      :key="location"
      location-strategy="connected"
      :location="location"
      :offset="8"
      :scrim="false"
      scroll-strategy="reposition"
    >
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" :text="`location=&quot;${location}&quot;`" />
      </template>

      <div class="rounded-200 border bg-surface-primary px-4 py-2">Панель у активатора</div>
    </CdsOverlay>
  </div>
</template>
```

### Behavior on scroll

The `scroll-strategy` prop decides what happens to the page and the overlay on
scroll: `block` (the default) blocks the page scroll, `close` closes the
overlay, `reposition` recomputes the position of the content following the
target, `none` does nothing.

**Example — `ScrollStrategies.vue`:**

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

const strategies = ['block', 'close', 'reposition', 'none'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay
      v-for="strategy in strategies"
      :key="strategy"
      location-strategy="connected"
      location="bottom"
      :offset="8"
      :scrim="false"
      :scroll-strategy="strategy"
    >
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" :text="strategy" />
      </template>

      <div class="w-[260px] rounded-200 border bg-surface-primary px-4 py-2">
        Панель открыта — покрутите страницу и посмотрите, что произойдёт.
      </div>
    </CdsOverlay>
  </div>
</template>
```

### Animation

The `transition` prop changes the animation of showing and hiding the content.

**Example — `Transition.vue`:**

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

const transitions = ['fade-transition', 'scale-transition', 'slide-transition-y'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsOverlay v-for="transition in transitions" :key="transition" :transition="transition" location="center center">
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral" :text="transition" />
      </template>

      <div class="w-[280px] rounded-200 bg-surface-primary p-4">
        <code>{{ transition }}</code>
      </div>
    </CdsOverlay>
  </div>
</template>
```

### Slots

| Slot        | Description                                                                        |
| ----------- | ---------------------------------------------------------------------------------- |
| `activator` | The element that opens the overlay. Bind the slot props (`props`) to it            |
| `default`   | The overlay content. Receives `isActive` — use it to close the overlay from inside |

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A persistent overlay has an explicit button — the user can always close it. | The overlay closes neither by a click outside, nor by Esc, nor by a button — the user is trapped. |
| The loading state covers only the block being updated — the rest of the interface keeps working. | An overlay over the whole area for the sake of a single block stops work with the entire page. |

## Scenarios

### Loading on top of a block

While the data of a block is being updated, a `contained` overlay with
CdsProgressCircle covers only that block:
the user sees that loading is in progress and keeps working with the rest of the
page. `persistent` prevents closing the overlay by an accidental click, and
`scroll-strategy="none"` does not block the page scroll.

**Example — `LoadingBlock.vue`:**

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

const snapshots = [
  [
    { label: 'Выручка', value: '1 240 500 ₽' },
    { label: 'Заказы', value: '318' },
    { label: 'Конверсия', value: '4,2%' }
  ],
  [
    { label: 'Выручка', value: '1 262 300 ₽' },
    { label: 'Заказы', value: '327' },
    { label: 'Конверсия', value: '4,4%' }
  ]
];

const card = ref<HTMLElement>();
const loading = ref(false);
const index = ref(0);

const refresh = () => {
  loading.value = true;

  setTimeout(() => {
    index.value = (index.value + 1) % snapshots.length;
    loading.value = false;
  }, 1600);
};
</script>

<template>
  <div ref="card" class="relative m-auto w-[360px] overflow-hidden rounded-200 bg-surface-secondary p-4">
    <div class="flex items-center justify-between">
      <span class="h4">Продажи за сегодня</span>
      <CdsButton variant="soft" color="neutral" size="sm" icon="refresh" aria-label="Обновить" @click="refresh" />
    </div>

    <div class="mt-2 flex flex-col gap-1">
      <div v-for="row in snapshots[index]" :key="row.label" class="flex justify-between">
        <span class="text-content-secondary">{{ row.label }}</span>
        <span>{{ row.value }}</span>
      </div>
    </div>

    <CdsOverlay
      v-model="loading"
      contained
      persistent
      no-click-animation
      location-strategy="connected"
      :target="card"
      location="center center"
      scroll-strategy="none"
    >
      <CdsProgressCircle indeterminate :size="40" />
    </CdsOverlay>
  </div>
</template>
```

### Image preview

A click on a thumbnail opens the image at full size on top of the dimmed page. A
dense scrim (`opacity="0.85"`) removes the visual noise, and the preview closes
the usual way — by a click outside or the `Esc` key, no separate button needed.

**Example — `ImagePreview.vue`:**

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

const preview = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <button type="button" class="w-[220px] cursor-pointer" aria-label="Открыть изображение" @click="preview = true">
      <CdsImage src="/images/temp/city.webp" class="rounded-200" cover :aspect-ratio="16 / 10" alt="Вид на город" />
    </button>

    <CdsOverlay v-model="preview" location="center center" opacity="0.85">
      <figure class="flex flex-col items-center gap-2">
        <CdsImage
          src="/images/temp/city.webp"
          class="max-h-[70vh] w-[min(800px,90vw)] rounded-200"
          alt="Вид на город"
        />
        <figcaption class="text-100 text-content-on-dark">
          Кликните мимо изображения или нажмите Esc, чтобы закрыть
        </figcaption>
      </figure>
    </CdsOverlay>
  </div>
</template>
```

### Onboarding hint

A hint about a new feature is a panel attached to an element by the `connected`
strategy; in a real interface you open it programmatically, for example by a
first-visit flag, here — by a click on a button. Without a scrim
(`:scrim="false"`) the hint does not get in the way of working with the page,
`persistent` protects it from an accidental close — it disappears only by the
"Понятно" button, and `scroll-strategy="reposition"` keeps it next to the
activator on scroll.

**Example — `OnboardingHint.vue`:**

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

const hint = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsOverlay
      v-model="hint"
      location-strategy="connected"
      location="bottom"
      :offset="8"
      :scrim="false"
      persistent
      no-click-animation
      :close-on-back="false"
      scroll-strategy="reposition"
    >
      <template #activator="{ props }">
        <CdsButton v-bind="props" variant="soft" color="brand" prepend-icon="adjust" text="Фильтры" />
      </template>

      <div class="flex w-[260px] flex-col gap-2 rounded-200 border bg-surface-primary p-4">
        <p class="text-100">
          Теперь фильтры можно сохранять: настройте условия один раз и возвращайтесь к ним в один клик.
        </p>
        <CdsButton class="self-end" size="sm" variant="soft" color="brand" text="Понятно" @click="hint = false" />
      </div>
    </CdsOverlay>
  </div>
</template>
```

## API

### CdsOverlay

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the element absolutely instead of fixed. This is useful for overlays that must stay inside a certain area, for example inside a container with `position: relative`. |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `captureFocus` | `boolean \| undefined` | — | no | Returns the focus back into the content if it has left it — for example on Tab from the end of the page. A mouse click does not steal the focus. |
| `closeDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeOnBack` | `boolean \| undefined` | `true` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | — | no | Hide the component on a click on the content |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `location` | `Anchor \| undefined` | `'bottom'` | no | Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'static'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | — | no | The v-model value of the component. If the component supports the **multiple** prop, an empty array is used by default. |
| `noClickAnimation` | `boolean \| undefined` | — | no | Disables the bounce effect on a click outside the content element when `persistent` is set. |
| `offset` | `string \| number \| number[] \| undefined` | — | no | Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | — | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | — | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'auto'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `persistent` | `boolean \| undefined` | — | no | A click outside the element or the Esc key does not close it. |
| `retainFocus` | `boolean \| undefined` | — | no | Traps Tab navigation inside the content: from the last focusable element the focus moves to the first one and back. |
| `scrim` | `string \| boolean \| undefined` | `true` | no | Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color. |
| `scrollStrategy` | `"none" \| "close" \| "block" \| "reposition" \| ScrollStrategyFunction \| undefined` | `'block'` | no | Strategy applied when the component is active and the user scrolls the page. |
| `stickToTarget` | `boolean \| undefined` | — | no | Lets the overlay content go off screen while scrolling. |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'fade-transition'` | no | Transition animation |
| `viewportMargin` | `string \| number \| undefined` | `12` | no | Sets a custom viewport margin for the overlay content |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2000` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `afterEnter` | `[]` | Fires after the opening animation has finished. |
| `afterLeave` | `[]` | Fires after the closing animation has finished. |
| `click:outside` | `[value: MouseEvent]` | Fires on a click outside the overlay. |
| `keydown` | `[value: KeyboardEvent]` | Fires on a key press while the overlay is open. |
| `update:modelValue` | `[value: boolean]` | Fires when the overlay opens or closes. Passes the new visibility state. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `activator` | `{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }` | Slot for the element that acts as the activator of the overlay. |
| `default` | `{ isActive: Ref<boolean, boolean>; }` | Slot for the overlay content. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activatorEl` | `HTMLElement \| undefined` | The DOM element of the activator. |
| `activatorRef` | `TemplateRef` | Template ref for assigning the activator manually. |
| `animateClick` | `() => void` | Runs the bounce animation of the content — the same as on a click outside a `persistent` overlay. |
| `contentEl` | `HTMLElement \| undefined` | The DOM element of the overlay content. |
| `globalTop` | `boolean` | Whether the overlay is the top one in the global stack of open overlays. |
| `rootEl` | `HTMLElement \| undefined` | The root DOM element of the overlay. |
| `scrimEl` | `HTMLElement \| undefined` | The DOM element of the scrim that dims the page. |
| `targetEl` | `HTMLElement \| undefined` | The DOM element of the positioning target. |
| `targetRef` | `TemplateRef` | Template ref for assigning the positioning target manually. |
| `updateLocation` | `((e: Event) => void) \| undefined` | Recalculates the position of the content relative to the target. |

---

# CdsPage

_Category: Layouts · since 4.0.0_

_Tests: API 3/3 · 10 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A page inside the layout: `CdsPage` gives the content a minimum height that accounts for the header and the footer, so a short page fills the whole screen instead of hanging as a narrow strip at the top.

**See also:** `CdsPage` lives inside CdsMain — outside it renders nothing and warns about it in the console. The paddings around the whole content area are calculated by CdsLayout.

## Variations

### Paddings

The `padding` prop adds inner paddings to the page — the usual layout for
content screens. Without it the content sticks to the edges: that is how tables
and maps that need the full width are laid out.

**Example — `Padding.vue`:**

```vue
<script setup lang="ts">
import { CdsLayout, CdsMain, CdsPage, CdsToggle } from '@central-design-system/components';
import { ref } from 'vue';

const padding = ref(true);
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsToggle v-model="padding" label="Внутренние отступы страницы" hide-details />

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsMain>
          <CdsPage :padding="padding">
            <div class="h-full rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>
```

### Custom height

The `style-fn` prop replaces the minimum height calculation with your own. The
function receives the total height of the header and the footer and the height
of the layout area, and returns a style string. This is how a page can be fixed
in height and give the scrolling to an inner list or table.

**Example — `StyleFn.vue`:**

```vue
<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';

// Вместо минимальной высоты фиксируем высоту страницы: внутренний список
// получает свой скролл, а страница не растягивает макет.
const styleFn = (offset: number, height: number) => `height: ${height - offset}px; overflow: hidden;`;
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsToolbarTitle>Реестр закупок</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding :style-fn="styleFn" class="flex flex-col">
          <div class="mb-2 text-content-secondary">Шапка страницы остаётся на месте</div>
          <div class="flex-1 overflow-auto rounded-200 border border-line-primary">
            <div v-for="n in 30" :key="n" class="border-b border-line-primary p-2 text-content-primary">
              Закупка №{{ 2400 + n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>
```

## Scenarios

### A full-screen empty state

The minimum height accounts for the header and the footer, so the centering
works against the real height of the page — the placeholder ends up exactly in
the middle instead of right under the header.

**Example — `FullHeight.vue`:**

```vue
<script setup lang="ts">
import {
  CdsEmptyState,
  CdsFooter,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsHeader bordered>
        <CdsToolbar>
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding class="flex items-center justify-center">
          <CdsEmptyState
            icon="shopping-cart"
            title="Закупок пока нет"
            text="Создайте первую закупку, чтобы она появилась здесь"
          />
        </CdsPage>
      </CdsMain>

      <CdsFooter bordered>
        <div class="flex h-[40px] items-center px-4 text-content-secondary">Подвал</div>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsPage

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `padding` | `boolean \| undefined` | `false` | no | Adds paddings to the page. |
| `styleFn` | `((offset: number, height: number) => string) \| undefined` | — | no | Function that computes the styles of the page. It receives the total offset (header + footer) and the height of the area, and returns a style string. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the page. |

---

# CdsPagination

_Category: Navigation · since 4.0.0_

_Tests: API 39/39 · 54 unit · 5 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 8 axe recommendations (v4.0.0-alpha.11)_

Pagination splits a large data set into pages and helps you jump to the one you need: numbered buttons, "back" and "forward" arrows, jumps to the first and the last page, and a quick jump field. Extra numbers collapse into an ellipsis, and without an explicit limit the number of buttons adapts to the width of the container.

**See also:** Pagination pages through homogeneous data — a list or a table. To switch between sections of the interface use CdsTabs, and to navigate the hierarchy of pages use CdsBreadcrumbs.

## Anatomy

Pagination is a row of page buttons with arrows on the sides. The first and last
page buttons appear with `show-first-last-page`, the quick jump field with
`quick-jumper`, and the pages between the edges and the neighbors of the current
one collapse into an ellipsis.

## Variations

### Number of pages

The `length` prop sets the number of pages, `v-model` holds the number of the
current one. While the focus is inside the pagination, the ← and → keys page
through.

**Example — `Default.vue`:**

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

const page = ref(1);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="10" />
  </div>
</template>
```

### Visible buttons

The `total-visible` prop limits how many buttons are visible at once — the
remaining pages collapse into an ellipsis (its text is changed by the `ellipsis`
prop). Without `total-visible` the component counts how many buttons fit into
the container itself and collapses the extra ones.

**Example — `TotalVisible.vue`:**

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

const page = ref(5);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="20" total-visible="5" />
  </div>
</template>
```

### Edge pages

The `show-first-last-page` prop adds buttons that jump to the first and the last
page. The `only-first` value keeps just the first page button — handy when the
total number of pages is unknown or only approximate.

**Example — `FirstLastPage.vue`:**

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

const page = ref(5);
const pageOnlyFirst = ref(5);
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsPagination v-model="page" length="10" total-visible="5" show-first-last-page />
    <CdsPagination v-model="pageOnlyFirst" length="10" total-visible="5" show-first-last-page="only-first" />
  </div>
</template>
```

### Quick jump

The `quick-jumper` prop adds a field where the user types a page number and gets
there on Enter or on blur. The label before the field is changed by the
`quick-jumper-label` prop.

**Example — `QuickJumper.vue`:**

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

const page = ref(1);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="20" total-visible="5" quick-jumper />
  </div>
</template>
```

### Disabled state

The `disabled` prop blocks the whole navigation — while the current page is
loading, for example.

**Example — `Disabled.vue`:**

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

const page = ref(3);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="10" disabled />
  </div>
</template>
```

### Slots

Slots replace the default buttons while keeping the switching logic: every slot
receives a ready `onClick` handler and the `disabled` state.

| Slot    | Description                                                    |
| ------- | -------------------------------------------------------------- |
| `item`  | A single page button; `props` carries everything to pass to it |
| `first` | Button that jumps to the first page                            |
| `prev`  | Button that jumps to the previous page                         |
| `next`  | Button that jumps to the next page                             |
| `last`  | Button that jumps to the last page                             |

**Example — `Slots.vue`:**

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

const page = ref(1);
</script>

<template>
  <div class="flex justify-center">
    <CdsPagination v-model="page" length="8" total-visible="5">
      <template #prev="{ onClick, disabled }">
        <CdsButton
          variant="soft"
          color="neutral"
          size="sm"
          prepend-icon="chevron-left"
          text="Назад"
          :disabled="disabled"
          @click="onClick"
        />
      </template>

      <template #next="{ onClick, disabled }">
        <CdsButton
          variant="soft"
          color="neutral"
          size="sm"
          append-icon="chevron-right"
          text="Вперёд"
          :disabled="disabled"
          @click="onClick"
        />
      </template>
    </CdsPagination>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A long list of pages is collapsed: the edge pages, the neighbors of the current one and an ellipsis stay visible. | A row with every page takes the full width and forces the reader to hunt for the right number. |
| The quick jump field helps when there are dozens of pages and paging with arrows takes too long. | With three pages the field is redundant: every page is one click away. |
| Pagination appears only when there is more than one page. | A single-page pagination offers no actions — hide it. |

## Scenarios

### Paged list

The classic pairing: the list shows the slice of data for the current page, the
"Показано 1–4 из 23" caption gives a sense of the total, and `total-visible="3"`
keeps the pagination compact next to the counter.

**Example — `PagedList.vue`:**

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

const pageSize = 4;

const contracts = Array.from({ length: 23 }, (_, index) => ({
  id: index + 1,
  title: `Договор поставки №${1240 + index}`,
  date: `${String((index % 28) + 1).padStart(2, '0')}.06.2026`
}));

const page = ref(1);
const pages = Math.ceil(contracts.length / pageSize);

const visible = computed(() => contracts.slice((page.value - 1) * pageSize, page.value * pageSize));

const rangeLabel = computed(() => {
  const from = (page.value - 1) * pageSize + 1;
  const to = Math.min(page.value * pageSize, contracts.length);

  return `${from}–${to} из ${contracts.length}`;
});
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col gap-3">
    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="contract in visible" :key="contract.id" class="flex justify-between gap-3">
        <span>{{ contract.title }}</span>
        <span>{{ contract.date }}</span>
      </li>
    </ul>

    <div class="flex flex-wrap items-center justify-between gap-3">
      <span>Показано {{ rangeLabel }}</span>

      <CdsPagination v-model="page" :length="pages" total-visible="3" />
    </div>
  </div>
</template>
```

### Loading pages from the server

When the data comes from the server, watch `v-model` (or the `first` / `prev` /
`next` / `last` / `quickJump` events) and fire the request on a page change.
While the request is in flight, `disabled` blocks the pagination and guards
against extra switches.

**Example — `ServerLoading.vue`:**

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

const pageSize = 3;
const total = 27;

const page = ref(1);
const loading = ref(false);
const items = ref<string[]>([]);

async function load() {
  loading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 800));

  items.value = Array.from(
    { length: Math.min(pageSize, total - (page.value - 1) * pageSize) },
    (_, index) => `Заявка №${(page.value - 1) * pageSize + index + 1} — согласование договора`
  );

  loading.value = false;
}

watch(page, load);
onMounted(load);
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col items-center gap-3">
    <div class="flex min-h-[72px] w-full items-center justify-center">
      <CdsProgressCircle v-if="loading" indeterminate aria-label="Загружаем страницу" />

      <ul v-else class="m-0 flex w-full list-none flex-col gap-1 p-0">
        <li v-for="item in items" :key="item">{{ item }}</li>
      </ul>
    </div>

    <CdsPagination v-model="page" :length="total / pageSize" total-visible="5" :disabled="loading" />
  </div>
</template>
```

### Search with a page reset

Filtering recalculates the number of pages and resets the current page to the
first one — otherwise the user may end up on a page that no longer exists. When
the results fit on a single page, the pagination hides.

**Example — `SearchReset.vue`:**

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

const pageSize = 4;

const companies = [
  'Альфа Логистика',
  'Вектор Строй',
  'Гранит Сервис',
  'Дельта Транс',
  'Звезда Ритейл',
  'Импульс Энерго',
  'Квант Технологии',
  'Ладога Снаб',
  'Меркурий Опт',
  'Нева Комплект',
  'Орион Металл',
  'Прогресс Авто',
  'Ресурс Групп',
  'Салют Пром',
  'Титан Инжиниринг',
  'Урал Механика',
  'Фотон Электро',
  'Эталон Сталь'
];

const query = ref('');
const page = ref(1);

const filtered = computed(() =>
  companies.filter((company) => company.toLowerCase().includes(query.value.trim().toLowerCase()))
);

const pages = computed(() => Math.ceil(filtered.value.length / pageSize));

const visible = computed(() => filtered.value.slice((page.value - 1) * pageSize, page.value * pageSize));

watch(query, () => (page.value = 1));
</script>

<template>
  <div class="m-auto flex w-full max-w-md flex-col gap-3">
    <CdsTextInput v-model="query" placeholder="Поиск по контрагентам" prepend-inner-icon="search" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="company in visible" :key="company">{{ company }}</li>
      <li v-if="filtered.length === 0">Ничего не найдено</li>
    </ul>

    <div v-if="pages > 1" class="flex justify-center">
      <CdsPagination v-model="page" :length="pages" total-visible="5" />
    </div>
  </div>
</template>
```

## API

### CdsPagination

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the active page button |
| `ariaLabel` | `string \| undefined` | `'Навигация по страницам'` | no | ARIA label of the root navigation element |
| `color` | `string \| undefined` | — | no | Color of the page buttons |
| `currentPageAriaLabel` | `string \| undefined` | `'Текущая страница, страница {0}'` | no | ARIA label of the current (active) page. `{0}` is replaced with the page number |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `ellipsis` | `string \| undefined` | `'...'` | no | Text displayed between pages when they are collapsed |
| `firstAriaLabel` | `string \| undefined` | `'Первая страница'` | no | ARIA label of the first page button |
| `firstIcon` | `IconValue \| undefined` | `'first-page'` | no | Icon of the first page button |
| `lastAriaLabel` | `string \| undefined` | `'Последняя страница'` | no | ARIA label of the last page button |
| `lastIcon` | `IconValue \| undefined` | `'last-page'` | no | Icon of the last page button |
| `length` | `string \| number \| undefined` | `1` | no | Number of pages |
| `modelValue` | `number \| undefined` | `(props) => props.start` | no | The v-model value — the number of the current page |
| `nextAriaLabel` | `string \| undefined` | `'Следующая страница'` | no | ARIA label of the next page button |
| `nextIcon` | `IconValue \| undefined` | `'chevron-right'` | no | Icon of the next page button |
| `pageAriaLabel` | `string \| undefined` | `'Перейти к странице {0}'` | no | ARIA label of a page button. `{0}` is replaced with the page number |
| `prevIcon` | `IconValue \| undefined` | `'chevron-left'` | no | Icon of the previous page button |
| `previousAriaLabel` | `string \| undefined` | `'Предыдущая страница'` | no | ARIA label of the previous page button |
| `quickJumper` | `boolean \| undefined` | `false` | no | Shows the quick jump field |
| `quickJumperLabel` | `string \| undefined` | `'Перейти к странице'` | no | Caption text before the quick jump field |
| `showFirstLastPage` | `boolean \| "only-first" \| undefined` | `false` | no | Shows the first/last page buttons. `'only-first'` shows only the first page button |
| `start` | `string \| number \| undefined` | `1` | no | Initial page |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'nav'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `totalVisible` | `string \| number \| undefined` | — | no | Number of page buttons visible at once |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `first` | `[value: number]` | Fired on a jump to the first page |
| `last` | `[value: number]` | Fired on a jump to the last page |
| `next` | `[value: number]` | Fired on a jump to the next page |
| `prev` | `[value: number]` | Fired on a jump to the previous page |
| `quickJump` | `[value: number]` | Fired on a jump made through the quick jump field |
| `update:modelValue` | `[value: number]` | Fired when the v-model value changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `first` | `CdsPaginationControlSlot` | Slot of the first page button |
| `item` | `CdsPaginationItemSlot` | Slot of a single page button |
| `last` | `CdsPaginationControlSlot` | Slot of the last page button |
| `next` | `CdsPaginationControlSlot` | Slot of the next page button |
| `prev` | `CdsPaginationControlSlot` | Slot of the previous page button |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `setFirst` | `() => void` | Jumps to the first page. |
| `setLast` | `() => void` | Jumps to the last page. |
| `setNext` | `() => void` | Jumps to the next page. |
| `setPrev` | `() => void` | Jumps to the previous page. |

---

# CdsProgressBar

_Category: Feedback · since 4.0.0_

_Tests: API 30/30 · 53 unit · 4 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 19 axe recommendations (v4.0.0-alpha.11)_

A linear progress indicator — a horizontal bar for the course of an operation: a file upload, the steps of a wizard, media playback. The value comes from `model-value`, and when the course of the operation is unknown, the `indeterminate` mode turns on a running waiting animation.

**See also:** For progress shown as a ring take CdsProgressCircle, and to dim a container while it loads — CdsOverlay.

## Anatomy

The bar is built from three layers: the indicator of the current value, the
buffer and the background. The content of the `default` slot is drawn on top of
the layers. By default the background and the buffer are tinted with the color
of the indicator at a high transparency — the intensity is tuned by the
`bg-opacity` and `buffer-opacity` props.

## Variations

### Value

The `model-value` prop is the current progress. The bar counts from 0 to `max`
(100 by default), so you can pass raw values — seconds or megabytes — without
converting them into percent. A change of the value is animated with a smooth
transition, and `reverse` fills the bar from right to left.

**Example — `Value.vue`:**

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

const values = [15, 40, 75, 100];
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar v-for="value in values" :key="value" :model-value="value" />
  </div>
</template>
```

### Indeterminate progress

The `indeterminate` prop turns on the running animation — use it when the course
of the operation is unknown and there is no percentage to show.

**Example — `Indeterminate.vue`:**

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar indeterminate color="brand-primary" />
  </div>
</template>
```

### Buffer

The `buffer-value` prop is a second bar between the indicator and the
background: the part that is already prepared but not passed yet — a preloaded
fragment of a video, for example. To make the buffer readable against the bar,
raise `buffer-opacity`; a separate color comes from `buffer-color`.

**Example — `Buffer.vue`:**

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar :model-value="30" :buffer-value="65" buffer-opacity="0.3" color="brand-primary" />
  </div>
</template>
```

The `stream` prop adds a dashed animation from the edge of the buffer to the end
of the bar — a signal that the data keeps coming. The edge of the stream is set
by `buffer-value`, and the background is hidden.

**Example — `Stream.vue`:**

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar :model-value="25" :buffer-value="60" buffer-opacity="0.3" stream color="brand-primary" />
  </div>
</template>
```

### Height

The `height` prop sets the height of the bar in pixels. The default is 4.

**Example — `Height.vue`:**

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" :height="2" />
    <CdsProgressBar :model-value="60" />
    <CdsProgressBar :model-value="60" :height="8" />
    <CdsProgressBar :model-value="60" :height="16" />
  </div>
</template>
```

### Rounding

The `rounded-bar` prop rounds the leading edge of the indicator. The start stays
straight — the bar reads as continuous from the zero mark.

**Example — `RoundedBar.vue`:**

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" :height="8" color="brand-primary" />
    <CdsProgressBar :model-value="60" :height="8" color="brand-primary" rounded-bar />
  </div>
</template>
```

### Colors

The `color` prop paints the indicator and — as long as separate colors are not
set — the buffer and the background too. Your own background color comes from
`bg-color`, and the transparency of the layers from `opacity` for the indicator
and `bg-opacity` for the background.

**Example — `Colors.vue`:**

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" color="green" />
    <CdsProgressBar :model-value="60" color="lemon" />
    <CdsProgressBar :model-value="60" color="red" />
    <CdsProgressBar :model-value="60" color="brand-primary" bg-color="red" />
  </div>
</template>
```

### Stripes

The `striped` prop lays running diagonal stripes over the indicator — they bring
long operations with a known course to life.

**Example — `Striped.vue`:**

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="45" striped color="brand-primary" :height="12" />
    <CdsProgressBar :model-value="70" striped color="green" :height="12" />
  </div>
</template>
```

### Segments

The `chunk-count` prop splits the bar into equal segments — by the number of
steps, for example — while `chunk-width` builds segments of a fixed width. The
gap between them comes from `chunk-gap`. The indicator fills segments whole: the
value snaps to the edge of the nearest segment.

**Example — `Chunks.vue`:**

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar :model-value="60" :chunk-count="10" :height="8" color="brand-primary" />
    <CdsProgressBar :model-value="60" :chunk-width="12" :height="8" color="brand-primary" />
    <CdsProgressBar :model-value="60" :chunk-count="10" :chunk-gap="8" :height="8" color="brand-primary" />
  </div>
</template>
```

The `variant="split"` option does not cut the bar into pieces but separates the
filled part from the rest with a single gap — the indicator and the background
read as two independent segments.

**Example — `Split.vue`:**

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

<template>
  <div class="m-auto flex w-[400px] flex-col gap-4">
    <CdsProgressBar variant="split" :model-value="40" :height="8" color="brand-primary" />
    <CdsProgressBar
      variant="split"
      :model-value="40"
      :buffer-value="70"
      buffer-opacity="0.4"
      :height="8"
      color="brand-primary"
    />
  </div>
</template>
```

### Content

The `default` slot renders content in the center of the bar and receives the
`value` and `buffer` slot props — normalized percentages. Increase `height` so
that the content fits.

**Example — `Content.vue`:**

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

<template>
  <div class="m-auto w-[400px]">
    <CdsProgressBar :model-value="64" :height="20" color="green">
      <template #default="{ value }">{{ Math.round(value) }}%</template>
    </CdsProgressBar>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| When the course of the operation is known, show the value: the user sees how much is left. | An indeterminate animation over known progress hides how long the wait will be. |
| A caption next to the bar explains what is happening and what to expect. | Шкала без подписи не отвечает на вопрос «что сейчас загружается?». |
| Content inside the bar needs room — increase height so that the text fits. | At the default height the text does not fit and runs over the neighboring content. |

## Scenarios

### File upload

The button starts the upload: the bar grows as the data arrives, and the caption
above it shows the file and the percentage. The `green` color supports the
positive scenario, and once it is done the button offers to upload again.

**Example — `FileUpload.vue`:**

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

const progress = ref(0);
const uploading = ref(false);

let timer: ReturnType<typeof setInterval> | undefined;

const upload = () => {
  clearInterval(timer);
  progress.value = 0;
  uploading.value = true;

  timer = setInterval(() => {
    progress.value = Math.min(progress.value + Math.random() * 18, 100);

    if (progress.value === 100) {
      clearInterval(timer);
      uploading.value = false;
    }
  }, 300);
};
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col items-center gap-3">
    <div class="flex w-full items-center justify-between">
      <span>report.xlsx</span>
      <span>{{ Math.round(progress) }}%</span>
    </div>

    <CdsProgressBar :model-value="progress" :height="8" color="green" />

    <CdsButton
      prepend-icon="upload"
      :text="progress === 100 ? 'Загрузить ещё раз' : 'Загрузить файл'"
      :disabled="uploading"
      @click="upload"
    />
  </div>
</template>
```

### Wizard steps

`chunk-count` set to the number of steps turns the bar into a wizard indicator:
filled segments are the steps behind, semi-transparent ones are the steps ahead.
The value is the share of the current step out of the total.

**Example — `WizardSteps.vue`:**

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

const steps = ['Данные компании', 'Контакты', 'Реквизиты', 'Подтверждение'];
const step = ref(1);

const progress = computed(() => (step.value / steps.length) * 100);
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-3">
    <span>Шаг {{ step }} из {{ steps.length }}: {{ steps[step - 1] }}</span>

    <CdsProgressBar :model-value="progress" :chunk-count="steps.length" :height="8" color="brand-primary" />

    <div class="flex justify-between">
      <CdsButton text="Назад" variant="soft" color="brand" :disabled="step === 1" @click="step--" />
      <CdsButton text="Далее" :disabled="step === steps.length" @click="step++" />
    </div>
  </div>
</template>
```

### Seeking a video

The `clickable` prop turns the bar into a control: a click writes the new value
into `v-model`. The buffer shows the preloaded fragment, `stream` shows that the
loading continues, and the captions compute the time from the percentages.

**Example — `VideoSeek.vue`:**

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

const duration = 225;
const position = ref(35);
const buffered = ref(60);

const seek = (value: number) => {
  buffered.value = Math.min(100, value + 25);
};

const format = (percent: number) => {
  const seconds = Math.round((percent / 100) * duration);

  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
};
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-2">
    <CdsProgressBar
      v-model="position"
      clickable
      :buffer-value="buffered"
      buffer-opacity="0.3"
      stream
      :height="8"
      color="brand-primary"
      @update:model-value="seek"
    />

    <div class="flex justify-between">
      <span>{{ format(position) }}</span>
      <span>{{ format(100) }}</span>
    </div>
  </div>
</template>
```

### Refreshing the data in a card

The `absolute` prop pins the bar to the top edge of a container with
`position: relative` — the indicator does not push the content around. The
`active` prop hides the bar by smoothly collapsing its height to zero, and
`indeterminate` spares you from measuring the progress of a background
operation.

**Example — `CardRefresh.vue`:**

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

const loading = ref(false);

let timer: ReturnType<typeof setTimeout> | undefined;

const refresh = () => {
  clearTimeout(timer);
  loading.value = true;
  timer = setTimeout(() => (loading.value = false), 2500);
};
</script>

<template>
  <CdsCard class="relative m-auto w-[320px] overflow-hidden">
    <CdsProgressBar absolute indeterminate :active="loading" color="brand-primary" />

    <CdsCardItem>
      <CdsCardTitle>Курсы валют</CdsCardTitle>
    </CdsCardItem>
    <CdsCardText>Доллар — 79,8 ₽, евро — 86,2 ₽. Данные обновляются раз в час.</CdsCardText>

    <CdsCardActions class="justify-end p-4 pt-0">
      <CdsButton
        text="Обновить"
        variant="soft"
        color="brand"
        prepend-icon="refresh"
        :loading="loading"
        @click="refresh"
      />
    </CdsCardActions>
  </CdsCard>
</template>
```

## API

### CdsProgressBar

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Absolute positioning of the component |
| `active` | `boolean \| undefined` | `true` | no | Controls the active state of the progress bar |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `bgOpacity` | `string \| number \| undefined` | — | no | Opacity of the progress bar background |
| `bufferColor` | `string \| undefined` | — | no | Color of the buffer part of the progress bar |
| `bufferOpacity` | `string \| number \| undefined` | — | no | Opacity of the buffer part of the progress bar |
| `bufferValue` | `string \| number \| undefined` | `0` | no | Buffer value of the progress |
| `chunkCount` | `string \| number \| undefined` | `null` | no | Number of segments the progress bar is split into |
| `chunkGap` | `string \| number \| undefined` | `4` | no | Gap between the segments of the progress bar |
| `chunkWidth` | `string \| number \| undefined` | `null` | no | Width of a single segment of the progress bar |
| `clickable` | `boolean \| undefined` | — | no | Makes the progress bar clickable |
| `color` | `string \| undefined` | — | no | Component color |
| `height` | `string \| number \| undefined` | `4` | no | Height of the progress bar |
| `indeterminate` | `boolean \| undefined` | — | no | Indeterminate progress state with no fixed value |
| `location` | `Anchor \| null \| undefined` | `'top'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `max` | `string \| number \| undefined` | `100` | no | Maximum progress value |
| `modelValue` | `string \| number \| undefined` | `0` | no | Current progress value |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the main progress indicator |
| `reverse` | `boolean \| undefined` | — | no | Fills the progress bar in the opposite direction |
| `roundedBar` | `boolean \| undefined` | — | no | Rounds the progress indicator |
| `stream` | `boolean \| undefined` | — | no | Shows a streaming animation over the progress indicator |
| `striped` | `boolean \| undefined` | — | no | Shows stripes on the progress indicator |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `variant` | `"split" \| undefined` | — | no | Display variant of the progress bar segments |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: number]` | Fires when the progress value changes — on a click on the bar in the `clickable` mode |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ value: number; buffer: number; }` | Content above the bar — a caption with the percentage, for example. The params carry the current value and the buffer value |

---

# CdsProgressCircle

_Category: Feedback · since 4.0.0 · status: new_

_Tests: API 12/12 · 27 unit · lines 100% (v4.0.0-alpha.13) · a11y: 14 axe recommendations (v4.0.0-alpha.11)_

A circular progress indicator shows the course of an operation: a file upload, data processing, a filling quota. The value is set in percent through `model-value`, and when the course of the operation is unknown, the `indeterminate` mode turns on an endless waiting animation.

**See also:** For progress shown as a horizontal bar take CdsProgressBar, and to dim a container while it loads — CdsOverlay.

## Variations

### Value

The `model-value` prop is the current progress in percent, from 0 to 100. A
change of the value is animated with a smooth transition of the arc.

**Example — `Value.vue`:**

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

const values = [15, 40, 75, 100];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="value in values" :key="value" :model-value="value" />
  </div>
</template>
```

The `rotate` prop turns the starting point of the arc by the given number of
degrees. By default the progress grows clockwise from "12 o'clock".

**Example — `Rotate.vue`:**

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

const rotations = [0, 90, 180, 270];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="rotate in rotations" :key="rotate" :model-value="25" :rotate="rotate" />
  </div>
</template>
```

### Indeterminate progress

The `indeterminate` prop turns on an endless animation — use it when the course
of the operation is unknown. The value `disable-shrink` leaves only the rotation
without the pulsation of the arc: this animation is simpler and does not load
the main thread. It is also enabled automatically for users with the
`prefers-reduced-motion` setting.

**Example — `Indeterminate.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle indeterminate />
    <CdsProgressCircle indeterminate="disable-shrink" />
  </div>
</template>
```

### Sizes

The `size` prop sets the diameter: from `xs` to `xl` or a number in pixels. The
default size is `md`.

**Example — `Sizes.vue`:**

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

const { sizes } = CdsProgressCircle.constants;
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="size of sizes" :key="size" :size="size" :model-value="65" />
    <CdsProgressCircle :size="72" :model-value="65" />
  </div>
</template>
```

### Stroke

The `width` prop sets the thickness of the stroke in pixels regardless of the
diameter.

**Example — `Width.vue`:**

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

const widths = [2, 4, 8];
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle v-for="width in widths" :key="width" :model-value="65" :width="width" size="lg" />
  </div>
</template>
```

The `rounded` prop rounds the ends of the arc.

**Example — `Rounded.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle :model-value="65" :width="6" size="lg" />
    <CdsProgressCircle :model-value="65" :width="6" size="lg" rounded />
  </div>
</template>
```

### Colors

The `color` prop paints the progress arc, `bg-color` paints the background ring
underneath. Both accept color tokens of the design system.

**Example — `Colors.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsProgressCircle :model-value="65" color="green" />
    <CdsProgressCircle :model-value="65" color="lemon" />
    <CdsProgressCircle :model-value="65" color="red" />
    <CdsProgressCircle :model-value="65" color="brand-primary" bg-color="red" />
  </div>
</template>
```

### Content

The `default` slot renders content in the center of the ring and receives the
current value through the `value` slot prop — a handy way to show the percentage
next to the arc.

**Example — `Content.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsProgressCircle :model-value="68" :size="64">
      <template #default="{ value }">{{ Math.round(value) }}%</template>
    </CdsProgressCircle>
  </div>
</template>
```

### Reveal animation

The `reveal` prop animates the arc from zero to the current value when the
component appears. The duration is configured with an object:
`:reveal="{ duration: 1500 }"`.

**Example — `Reveal.vue`:**

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

const key = ref(0);
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsProgressCircle :key="key" :model-value="75" :size="64" reveal />
    <CdsButton variant="soft" color="brand" size="sm" text="Повторить" @click="key++" />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| When the course of the operation is known, show the value: the user sees how much is left. | An indeterminate animation over known progress leaves the user guessing how long the wait will be. |
| A caption next to the indicator explains what is happening and what to expect. | Кольцо без подписи не отвечает на вопрос «что сейчас загружается?». |
| For waiting inside a line of text xs is enough — the indicator does not compete with the content. | A large indicator in a line pulls attention away and breaks the vertical rhythm. |

## Scenarios

### File upload

The upload progress is visible in the center of the ring through the `default`
slot, and once it is done the percentage turns into a success icon. The
`rounded` prop softens the arc, and `color` supports the positive scenario.

**Example — `FileUpload.vue`:**

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

const progress = ref(0);
const uploading = ref(false);

let timer: ReturnType<typeof setInterval> | undefined;

const upload = () => {
  clearInterval(timer);
  progress.value = 0;
  uploading.value = true;

  timer = setInterval(() => {
    progress.value = Math.min(progress.value + Math.random() * 18, 100);

    if (progress.value === 100) {
      clearInterval(timer);
      uploading.value = false;
    }
  }, 300);
};
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsProgressCircle :model-value="progress" :size="72" :width="6" rounded color="green">
      <template #default="{ value }">
        <CdsIcon v-if="value === 100" icon="success-fill" color="green" />
        <span v-else>{{ Math.round(value) }}%</span>
      </template>
    </CdsProgressCircle>

    <CdsButton
      prepend-icon="upload"
      :text="progress === 100 ? 'Загрузить ещё раз' : 'Загрузить файл'"
      :disabled="uploading"
      @click="upload"
    />
  </div>
</template>
```

### A filling quota

The ring shows not only a process but also a static value — the used storage
space, for example. A computed `color` switches the indicator from green to
yellow and red as the limit approaches.

**Example — `StorageQuota.vue`:**

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

const used = ref(52);

const color = computed(() => {
  if (used.value >= 90) return 'red';
  if (used.value >= 70) return 'lemon';
  return 'green';
});
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsProgressCircle :model-value="used" :size="80" :width="8" :color="color">
      <template #default="{ value }">
        <span class="text-content-secondary">{{ Math.round(value) }} ГБ</span>
      </template>
    </CdsProgressCircle>

    <div class="flex gap-2">
      <CdsButton
        variant="soft"
        color="brand"
        size="sm"
        text="Добавить файлы"
        :disabled="used >= 100"
        @click="used = Math.min(used + 15, 100)"
      />
      <CdsButton
        variant="soft"
        color="neutral"
        size="sm"
        text="Очистить"
        :disabled="used <= 0"
        @click="used = Math.max(used - 30, 0)"
      />
    </div>
  </div>
</template>
```

### A background operation

A compact `indeterminate` indicator of the `xs` size sits in a line with the
text and reports that the operation that was started is still running. The
caption next to it explains what to expect — without it a spinning ring says
nothing.

**Example — `ReportGeneration.vue`:**

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

const state = ref<'idle' | 'pending' | 'done'>('idle');

const generate = () => {
  state.value = 'pending';

  setTimeout(() => {
    state.value = 'done';
  }, 2500);
};
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsButton text="Сформировать отчёт" :disabled="state === 'pending'" @click="generate" />

    <div v-if="state === 'pending'" class="flex items-center gap-2 text-content-secondary">
      <CdsProgressCircle indeterminate size="xs" :width="2" />
      <span>Готовим отчёт — обычно это занимает меньше минуты</span>
    </div>

    <div v-else-if="state === 'done'" class="flex items-center gap-2">
      <CdsIcon icon="success-fill" color="green" />
      <span>Отчёт готов</span>
    </div>
  </div>
</template>
```

## API

### CdsProgressCircle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bgColor` | `string \| undefined` | — | no | Background color of the loader |
| `color` | `string \| undefined` | — | no | Color of the loader |
| `indeterminate` | `boolean \| "disable-shrink" \| undefined` | — | no | Shows the animation continuously; use it when the course of the loading is unknown. The string `disable-shrink` switches to a simpler animation that does not run on the main thread |
| `modelValue` | `string \| number \| undefined` | `0` | no | Current loading progress in percent |
| `reveal` | `boolean \| { duration?: number \| undefined; } \| undefined` | `false` | no | Animates the indicator from zero to the current value when the component appears. The `{ duration }` object sets the animation duration in milliseconds |
| `rotate` | `string \| number \| undefined` | `0` | no | Turns the starting point of the circle by the given number of degrees |
| `rounded` | `boolean \| undefined` | — | no | Rounds the ends of the progress arc |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `width` | `string \| number \| undefined` | `4` | no | Sets the thickness of the circle stroke in pixels |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ value: number; }` | Default slot. Carries the progress value of the loading indicator. |

---

# CdsRadio

_Category: Controls · since 4.0.0_

_Tests: API 29/29 · 30 unit · 5 known bugs · lines 100% (v4.0.0-alpha.13)_

A radio button is one option of a mutually exclusive choice. It is not used on its own: the buttons are joined by CdsRadioGroup — it keeps the selected value, captions the set and shows the messages. The button is left with `value` — the value of the option, `label` and `description` — its caption and details.

**See also:** Examples, guidelines and scenarios are on the CdsRadioGroup page. For an independent on/off option take CdsCheckbox.

## API

### CdsRadio

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `falseIcon` | `IconValue \| undefined` | `'radio-off'` | no | Icon of the unselected state |
| `falseValue` | `any` | — | no | Value for the false state. |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `trueIcon` | `IconValue \| undefined` | `'radio-on'` | no | Icon of the selected state |
| `trueValue` | `any` | — | no | Value for the true state. |
| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
| `value` | `any` | — | no | Value used when the component is selected inside a group. When it is not set, a unique identifier is used. |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }` | Default slot |
| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
| `input` | `SelectionControlSlot` | Slot for the default input element. |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |

---

# CdsRadioGroup

_Category: Controls · since 4.0.0_

_Tests: API 59/59 · 60 unit · 9 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 4 axe recommendations (v4.0.0-alpha.11)_

A radio group is a choice of one option out of a short mutually exclusive set: a payment method, a plan, a report period. The group keeps the selected value, captions the set with a heading and a description, shows messages and errors; the options themselves are CdsRadio components with their own `value`.

**See also:** For independent options that are turned on separately use CdsCheckbox, for an on/off setting that applies immediately — CdsToggle. If there are more than five options, fold the list into CdsSelect.

## Anatomy

The heading and the description caption the whole set, below them are the radio
buttons: each one has a control with a state icon, a label and an optional
description. At the bottom is the common messages block of the group. A click on
the label selects the button exactly like a click on the control.

## Variations

### Heading and description

The `label` prop names the group, `description` explains the choice. Every button
has its own `label` and `description`: name the option briefly in the label and
move the details — the price, the deadlines, the limits — into the description.

**Example — `LabelAndDescription.vue`:**

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

const delivery = ref('pickup');
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsRadioGroup v-model="delivery" label="Способ получения" description="Изменить способ можно до отправки заказа">
      <CdsRadio value="pickup" label="Самовывоз" description="Бесплатно, завтра из пункта выдачи" />
      <CdsRadio value="courier" label="Курьер" description="Завтра с 10:00 до 18:00, 300 ₽" />
      <CdsRadio value="post" label="Почта" description="5–7 дней, 250 ₽" />
    </CdsRadioGroup>
  </div>
</template>
```

### Direction

By default the buttons are stacked in a column. `direction="horizontal"` puts
them in a row — handy for short sets of two or three options such as a period or
a sort order.

**Example — `Direction.vue`:**

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

const vertical = ref('year');
const horizontal = ref('year');
</script>

<template>
  <div class="flex flex-col gap-6 w-[350px] m-auto">
    <CdsRadioGroup v-model="vertical" label="Вертикально — по умолчанию" hide-details>
      <CdsRadio value="year" label="Год" />
      <CdsRadio value="quarter" label="Квартал" />
      <CdsRadio value="month" label="Месяц" />
    </CdsRadioGroup>

    <CdsRadioGroup v-model="horizontal" label="Горизонтально" direction="horizontal" hide-details>
      <CdsRadio value="year" label="Год" />
      <CdsRadio value="quarter" label="Квартал" />
      <CdsRadio value="month" label="Месяц" />
    </CdsRadioGroup>
  </div>
</template>
```

### States

`disabled` blocks the whole group and lowers the contrast, `readonly` forbids
changing the choice but does not change the appearance. A single option is
blocked by the `disabled` prop of the button itself.

**Example — `States.vue`:**

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

const payment = ref('card');
</script>

<template>
  <div class="flex flex-col gap-6 w-[350px] m-auto">
    <CdsRadioGroup model-value="card" label="Disabled" disabled hide-details>
      <CdsRadio value="card" label="Картой онлайн" />
      <CdsRadio value="invoice" label="По счёту" />
    </CdsRadioGroup>

    <CdsRadioGroup model-value="card" label="Readonly" readonly hide-details>
      <CdsRadio value="card" label="Картой онлайн" />
      <CdsRadio value="invoice" label="По счёту" />
    </CdsRadioGroup>

    <CdsRadioGroup v-model="payment" label="Заблокирована одна кнопка" hide-details>
      <CdsRadio value="card" label="Картой онлайн" />
      <CdsRadio value="invoice" label="По счёту" />
      <CdsRadio value="cash" label="Наличными при получении" disabled />
    </CdsRadioGroup>
  </div>
</template>
```

### Messages and errors

`messages` shows a supporting text under the group, `error-messages` — a ready
error message (the one coming from the server, for example) together with the
error state on all the buttons. Validation rules through `rules` are in the
"Submitting a form" scenario. `hide-details` removes the bottom block entirely.

**Example — `Messages.vue`:**

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

const format = ref('pdf');
</script>

<template>
  <div class="flex flex-col gap-6 w-[350px] m-auto">
    <CdsRadioGroup v-model="format" label="Формат выгрузки" messages="Файл придёт на почту после формирования">
      <CdsRadio value="pdf" label="PDF" />
      <CdsRadio value="xlsx" label="Excel" />
    </CdsRadioGroup>

    <CdsRadioGroup label="Способ оплаты" error-messages="Выберите способ оплаты">
      <CdsRadio value="card" label="Картой онлайн" />
      <CdsRadio value="invoice" label="По счёту" />
    </CdsRadioGroup>
  </div>
</template>
```

### Colors

`color` sets the color of the selected button, `base-color` — of the unselected
ones. The values apply to all the buttons of the group at once.

**Example — `Colors.vue`:**

```vue
<script setup lang="ts">
import { CdsRadio, CdsRadioGroup } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col gap-6 w-[350px] m-auto">
    <CdsRadioGroup model-value="first" color="green" label="Зелёный при выборе (color)" hide-details>
      <CdsRadio value="first" label="Выбранный вариант" />
      <CdsRadio value="second" label="Невыбранный вариант" />
    </CdsRadioGroup>

    <CdsRadioGroup base-color="purple" label="Фиолетовый до выбора (base-color)" hide-details>
      <CdsRadio value="first" label="Первый вариант" />
      <CdsRadio value="second" label="Второй вариант" />
    </CdsRadioGroup>
  </div>
</template>
```

### Slots

When the text props are not enough, the content of the blocks is replaced by
slots — both on the group and on every button.

| Slot name     | Description                                               |
| :------------ | :-------------------------------------------------------- |
| `label`       | Content of the group heading (replaces `label`)           |
| `description` | Content of the group description (replaces `description`) |
| `prepend`     | Element before the set of buttons                         |
| `append`      | Element after the set of buttons                          |
| `messages`    | Content of the messages block                             |
| `details`     | The whole bottom block                                    |

`CdsRadio` has its own `label` and `description` slots — to highlight a part of
the text or add an icon, for example.

**Example — `Slots.vue`:**

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

const channel = ref('email');
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsRadioGroup v-model="channel">
      <template #label>
        <div>Уведомления о <span class="text-status-success-content font-bold">новых заказах</span></div>
      </template>
      <template #description>
        <div>Канал можно поменять в настройках <cds-icon name="settings" /></div>
      </template>
      <CdsRadio value="email">
        <template #label>Электронная почта</template>
      </CdsRadio>
      <CdsRadio value="telegram">
        <template #label>Telegram</template>
        <template #description>Сообщения приходят мгновенно</template>
      </CdsRadio>
    </CdsRadioGroup>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Radio buttons are for mutually exclusive options: exactly one can be selected. | Radio buttons do not fit independent options that are turned on together — use checkboxes. |
| Preselect a default option — usually the most common or the safest one. | A group with no selected value makes the user guess what the form will submit if nothing is picked. |
| Up to five options — radio buttons: the whole set is visible and the choice takes one click. | A long list bloats the form — fold it into CdsSelect. |

## Scenarios

### Submitting a form

The choice is required: a rule in `rules` returns the error text while no value
is selected. The button starts the check through the `validate()` of the
CdsForm.

**Example — `PaymentForm.vue`:**

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

const payment = ref<string | null>(null);
const sending = ref(false);
const formRef = ref<InstanceType<typeof CdsForm>>();

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

async function submit() {
  const form = unref(formRef);
  if (!form) return;

  const { valid } = await form.validate();
  if (!valid) return;

  sending.value = true;
  setTimeout(() => {
    sending.value = false;
  }, 1500);
}
</script>

<template>
  <CdsForm ref="formRef" class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsRadioGroup v-model="payment" :rules="rules" label="Способ оплаты">
      <CdsRadio value="card" label="Картой онлайн" />
      <CdsRadio value="invoice" label="По счёту" description="Для юридических лиц" />
      <CdsRadio value="cash" label="Наличными при получении" />
    </CdsRadioGroup>

    <CdsButton text="Оформить заказ" :loading="sending" @click="submit" />
  </CdsForm>
</template>
```

### Choosing a plan

The descriptions of the buttons state the conditions, and the computed total
under the group is updated on every choice — the user sees the consequences right
away.

**Example — `TariffChoice.vue`:**

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

const tariffs = [
  { value: 'start', label: 'Старт', description: '5 пользователей и базовые отчёты', price: 0 },
  { value: 'business', label: 'Бизнес', description: '50 пользователей, отчёты и интеграции', price: 4900 },
  { value: 'corp', label: 'Корпорация', description: 'Без ограничений, персональный менеджер', price: 19900 }
];

const selected = ref('business');

const total = computed(() => {
  const tariff = tariffs.find((item) => item.value === selected.value);
  return tariff && tariff.price > 0 ? `${tariff.price.toLocaleString('ru-RU')} ₽/мес` : 'бесплатно';
});
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsRadioGroup v-model="selected" label="Тариф" hide-details>
      <CdsRadio
        v-for="tariff in tariffs"
        :key="tariff.value"
        :value="tariff.value"
        :label="tariff.label"
        :description="tariff.description"
      />
    </CdsRadioGroup>

    <div>
      Итого: <span class="font-bold">{{ total }}</span>
    </div>
  </div>
</template>
```

### Sorting a list

A horizontal group with `hide-details` works as a sorting panel: the selected
value rebuilds the list on the fly through a computed.

**Example — `SortList.vue`:**

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

const products = [
  { name: 'Монитор', price: 25400, added: '2026-05-14' },
  { name: 'Ноутбук', price: 82000, added: '2026-07-02' },
  { name: 'Клавиатура', price: 4300, added: '2026-06-20' },
  { name: 'Док-станция', price: 11900, added: '2026-04-08' }
];

const sort = ref('new');

const items = computed(() =>
  [...products]
    .sort((a, b) => {
      if (sort.value === 'cheap') return a.price - b.price;
      if (sort.value === 'name') return a.name.localeCompare(b.name);
      return b.added.localeCompare(a.added);
    })
    .map((product) => ({ title: `${product.name} — ${product.price.toLocaleString('ru-RU')} ₽` }))
);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsRadioGroup v-model="sort" label="Сортировка" direction="horizontal" hide-details>
      <CdsRadio value="new" label="Сначала новые" />
      <CdsRadio value="cheap" label="Дешевле" />
      <CdsRadio value="name" label="По алфавиту" />
    </CdsRadioGroup>

    <CdsList :items="items" />
  </div>
</template>
```

## API

### CdsRadioGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'vertical'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `falseIcon` | `IconValue \| undefined` | `'radio-off'` | no | Icon of an unselected radio button |
| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
| `height` | `string \| number \| undefined` | `'auto'` | no | Height of the component |
| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `trueIcon` | `IconValue \| undefined` | `'radio-on'` | no | Icon of a selected radio button |
| `type` | `string \| undefined` | `'radio'` | no | Type of the native input element of the group buttons |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: any]` | Fires when the model of the component changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `default` | `any` | Default slot — the radio buttons of the group (`CdsRadio`) |
| `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 |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsResponsive

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 11/11 · 11 unit · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A frame with constant proportions. Set `aspect-ratio` and the height of the block is calculated from its width on any screen. Anything that needs a fixed shape goes inside: a video, a map, an `iframe`, a category tile. The space for the content is taken right away, so the layout does not jump while it loads.

**See also:** For photos take CdsImage — it is built on `CdsResponsive` and can also do lazy loading, a placeholder and cropping. If you need the columns of a page rather than the shape of a single block, take CdsGrid.

## Variations

### Aspect ratio

The `aspect-ratio` prop accepts a fraction (`16/9`) or a number (`1.7778`). The
width comes from the parent, the height is calculated by the component itself —
and recalculated on every change of the width. The calculated height works as a
minimum: content that does not fit into it stretches the frame and breaks the
proportions.

**Example — `AspectRatio.vue`:**

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

const ratios = ['16/9', '4/3', '1'];
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <div v-for="ratio in ratios" :key="ratio" class="w-[180px]">
      <CdsResponsive :aspect-ratio="ratio">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          {{ ratio }}
        </div>
      </CdsResponsive>
    </div>
  </div>
</template>
```

### Sizes

By default the frame takes the whole width of its parent. The `width`,
`max-width` and `min-width` props limit it, and `height`, `max-height` and
`min-height` limit its height; numbers turn into pixels, strings go into CSS as
they are.

**Example — `Sizes.vue`:**

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

<template>
  <div class="m-auto flex w-[420px] flex-col gap-4">
    <div>
      <CdsResponsive aspect-ratio="16/9">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          Во всю ширину родителя
        </div>
      </CdsResponsive>
    </div>

    <div>
      <CdsResponsive aspect-ratio="16/9" max-width="260">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          max-width 260
        </div>
      </CdsResponsive>
    </div>

    <div>
      <CdsResponsive aspect-ratio="16/9" width="160">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          width 160
        </div>
      </CdsResponsive>
    </div>
  </div>
</template>
```

### Layout

The `inline` prop turns the frame into `inline-flex` — it stops stretching and
stands in a row with its neighbors. Set the width yourself in this case: it will
not take it from the content.

**Example — `Inline.vue`:**

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

<template>
  <div class="m-auto flex w-[360px] flex-col gap-4">
    <div>
      <CdsResponsive aspect-ratio="4/1">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          Блочный
        </div>
      </CdsResponsive>
    </div>

    <div class="flex flex-wrap gap-4">
      <CdsResponsive inline aspect-ratio="4/1" width="160">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          inline
        </div>
      </CdsResponsive>

      <CdsResponsive inline aspect-ratio="4/1" width="120">
        <div class="flex h-full items-center justify-center rounded-200 bg-surface-secondary text-content-secondary">
          inline
        </div>
      </CdsResponsive>
    </div>
  </div>
</template>
```

### Slots

The height of the frame is held by an invisible spacer, and the content lies on
top of it. Hence two slots with different jobs.

| Slot         | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `default`    | The main content inside a wrapper — it takes the whole frame                        |
| `additional` | Content without a wrapper, on top of the spacer — for backdrops and absolute layers |

The `content-class` prop puts classes on the wrapper of the `default` slot —
that is how the inner paddings and the layout are set. The root of the component
is positioned (`position: relative`), so the elements from `additional` can be
placed absolutely relative to the frame.

**Example — `Slots.vue`:**

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

<template>
  <div class="m-auto w-[360px]">
    <CdsResponsive aspect-ratio="16/9" class="rounded-200" content-class="flex items-end p-3">
      <template #additional>
        <div class="absolute inset-0 bg-surface-secondary" />
        <span class="absolute right-3 top-3 rounded-200 bg-brand-primary px-2 py-1 text-xs text-content-on-dark">
          02:14
        </span>
      </template>

      <p class="text-content-primary">Подпись поверх подложки</p>
    </CdsResponsive>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The proportions are set in advance — the space for the widget is taken and the text below it is already in place. | A placeholder shorter than the future widget: when it arrives, everything below jumps down. |
| For images take CdsImage — it can do proportions, lazy loading and a placeholder. | An img tag inside CdsResponsive repeats CdsImage by hand and stays without lazy loading. |
| The content is stretched to the full height of the frame — the proportions hold. | Content taller than the frame stretches it: the set proportions are lost and the neighboring blocks stop lining up. |

## Scenarios

### An embedded map or video

Maps and video players arrive in an `iframe` with proportions of their own. Wrap
the `iframe` into a `CdsResponsive` with the right `aspect-ratio` and stretch it
with the `h-full w-full` classes — the player will look the same on a wide
monitor and on a phone.

**Example — `EmbeddedMap.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsResponsive } from '@central-design-system/components';
</script>

<template>
  <div class="m-auto w-full max-w-[480px]">
    <CdsResponsive aspect-ratio="16/9" class="rounded-200">
      <div
        class="flex h-full flex-col items-center justify-center gap-2 bg-surface-secondary text-content-secondary"
        role="img"
        aria-label="Карта офиса"
      >
        <CdsIcon icon="location" size="lg" />
        <span class="text-sm">Здесь будет карта — iframe на всю рамку</span>
      </div>
    </CdsResponsive>
  </div>
</template>
```

### A grid of tiles

In a grid of categories the tiles have to be square regardless of the length of
the caption. The `aspect-ratio="1"` value gives a square, and the width of every
tile comes from the grid column — the number of columns changes the size, not
the shape.

**Example — `TileGrid.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsResponsive } from '@central-design-system/components';

const categories = [
  { icon: 'delivery', title: 'Логистика' },
  { icon: 'tool', title: 'Оборудование' },
  { icon: 'file', title: 'Услуги' },
  { icon: 'education', title: 'Обучение' }
];
</script>

<template>
  <div class="m-auto grid w-full max-w-[480px] grid-cols-2 gap-4 sm:grid-cols-4">
    <CdsResponsive v-for="category in categories" :key="category.title" aspect-ratio="1" class="rounded-200">
      <button
        type="button"
        class="flex h-full w-full flex-col items-center justify-center gap-2 border-0 bg-surface-secondary text-content-secondary"
      >
        <CdsIcon :icon="category.icon" size="lg" />
        <span class="text-sm">{{ category.title }}</span>
      </button>
    </CdsResponsive>
  </div>
</template>
```

### Space for a widget while it loads

A report, a chart or a map arrives from the server a second or two later. A
frame with proportions takes their place right away: while the loader spins
inside, the caption and the buttons below the widget stay exactly where they
will end up after the loading.

**Example — `LoadingPlaceholder.vue`:**

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

const loading = ref(true);

const load = () => {
  loading.value = true;

  setTimeout(() => {
    loading.value = false;
  }, 2000);
};

onMounted(load);
</script>

<template>
  <div class="m-auto flex w-full max-w-[420px] flex-col gap-3">
    <CdsResponsive aspect-ratio="16/9" class="rounded-200">
      <div class="flex h-full items-center justify-center bg-surface-secondary text-content-secondary">
        <CdsLoader v-if="loading" description="Загружаем отчёт" />
        <span v-else class="text-sm">Отчёт за июль: 128 закупок</span>
      </div>
    </CdsResponsive>

    <p class="text-sm text-content-secondary">Подпись под виджетом остаётся на месте всё время загрузки.</p>

    <CdsButton
      class="self-start"
      variant="soft"
      color="neutral"
      text="Загрузить заново"
      :disabled="loading"
      @click="load"
    />
  </div>
</template>
```

### Switching the proportions

The `aspect-ratio` value is reactive and the change of the height is animated —
a crop switcher does not jerk the neighboring blocks.

**Example — `RatioSwitch.vue`:**

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

const ratios = ['16/9', '4/3', '1'];
const selected = ref(0);

const ratio = computed(() => ratios[selected.value]);
</script>

<template>
  <div class="m-auto flex w-full max-w-[420px] flex-col items-center gap-4">
    <CdsButtonToggle v-model="selected" variant="soft" color="neutral" mandatory>
      <CdsButton v-for="item in ratios" :key="item" :text="item" />
    </CdsButtonToggle>

    <div class="w-full">
      <CdsResponsive :aspect-ratio="ratio" class="rounded-200">
        <div class="flex h-full items-center justify-center bg-surface-secondary text-content-secondary">
          {{ ratio }}
        </div>
      </CdsResponsive>
    </div>
  </div>
</template>
```

## API

### CdsResponsive

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `aspectRatio` | `string \| number \| undefined` | — | no | Aspect ratio of the content. For example `1.7778` (16/9) or `'4/3'`. |
| `contentClass` | `any` | — | no | CSS class applied to the content wrapper. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `inline` | `boolean \| undefined` | — | no | Renders the component as an inline block (`inline-flex`) instead of a block one. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `additional` | `any` | Extra content rendered on top of the sizer, outside the content wrapper. |
| `default` | `any` | The main content of the component, wrapped so the aspect ratio is kept. |

---

# CdsSelect

_Category: Controls · since 4.0.0_

_Tests: API 127/127 · 80 unit · 10 e2e · 11 known bugs · lines 64.1% (v4.0.0-alpha.13) · a11y: 5 axe recommendations (v4.0.0-alpha.11)_

A select opens a dropdown list and lets you pick one or several values from a known set: a country, a status, a category. The field is built on CdsTextInput, so the label, the description, the messages, validation and the states work exactly as in a text field.

**See also:** 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.

## 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`.

**Example — `Default.vue`:**

```vue
<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.

**Example — `CustomItems.vue`:**

```vue
<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.

**Example — `Grouping.vue`:**

```vue
<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.

**Example — `Multiple.vue`:**

```vue
<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.

**Example — `SelectAll.vue`:**

```vue
<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.

**Example — `Chips.vue`:**

```vue
<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.

**Example — `NativeSelect.vue`:**

```vue
<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.

**Example — `ListProps.vue`:**

```vue
<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.

**Example — `ItemSlot.vue`:**

```vue
<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.

**Example — `SelectionSlot.vue`:**

```vue
<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`.

**Example — `PrependAppendSlot.vue`:**

```vue
<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`.

**Example — `MenuHeaderAndFooterSlots.vue`:**

```vue
<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

| ✅ Do | ❌ Don't |
| --- | --- |
| Show two or three options as radio buttons — every option is visible without a click. | A select hides a short list behind an extra click. |
| The label names the field and stays visible after the choice. | Without a label the selected value does not explain what the field is. |
| A select picks a value. Leave actions to buttons or to a menu. | Commands inside a select look like a field value: it is unclear what will happen after the choice. |

## 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.

**Example — `FormSubmit.vue`:**

```vue
<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.

**Example — `DependentSelects.vue`:**

```vue
<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.

**Example — `Assignees.vue`:**

```vue
<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.

**Example — `Sorting.vue`:**

```vue
<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

### CdsSelect

**Props**

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

---

# CdsSelectionControl

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 32/32 · 51 unit · 4 e2e · 5 known bugs · lines 98.4% (v4.0.0-alpha.13) · a11y: 2 axe recommendations (v4.0.0-alpha.11)_

The base of the selection controls: a native `input` with state icons, a label and a description. The component holds the value, can work with its own `true`/`false` values and with multiple selection, and picks up the settings of CdsSelectionControlGroup. The checkboxes, radio buttons and toggles of the design system are built on it.

**See also:** For regular selection take the ready-made controls — CdsCheckbox, CdsRadio, CdsToggle: they already have the icons, the sizes, the state colors and the block of messages. `CdsSelectionControl` is needed when the control you want is not in the library.

## Anatomy

On the left is the control: the state icon from `true-icon` / `false-icon` and
an invisible native `input` on top of it. On the right are the label
(CdsLabel) and the description
(CdsDescription); a click on the label toggles
the control.

The component has no sizes of its own: the area of the control is set by the
`--cds-selection-control-width` and `--cds-selection-control-height` CSS
variables, and the gap up to the label is the free space inside that area. In
the examples below the distance is added with the `gap-x-2` class.

## Variations

### Type and icons

The `type` prop sets the type of the native `input` — the behavior and the
accessibility depend on it: a `checkbox` is turned on and off, a `radio` is only
selected. The state icons come from `true-icon` and `false-icon`; without them
the control has no visible part.

**Example — `TypeAndIcons.vue`:**

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

const checkbox = ref(true);
const radio = ref(true);
const star = ref(true);
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsSelectionControl
      v-model="checkbox"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Чекбокс"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="radio"
      type="radio"
      true-icon="radio-on"
      false-icon="radio-off"
      label="Радиокнопка"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="star"
      type="checkbox"
      true-icon="star-fill"
      false-icon="star"
      label="Своя пара иконок"
      class="gap-x-2"
    />
  </div>
</template>
```

### Label and description

The `label` prop names the option, `description` explains it. Name the option
briefly in the label, and move the details — the price, the deadlines, the
limitations — into the description.

**Example — `LabelAndDescription.vue`:**

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

const digest = ref(true);
const report = ref(false);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-3">
    <CdsSelectionControl
      v-model="digest"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Еженедельный дайджест"
      description="Письмо с новыми закупками по понедельникам"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="report"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Отчёт по заявкам"
      class="gap-x-2"
    />
  </div>
</template>
```

### Values

By default the model holds `true` or `false`. The `true-value` and `false-value`
props replace them with your own values — handy when what goes to the server is
not a boolean.

**Example — `Values.vue`:**

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

const delivery = ref('pickup');
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="delivery"
      type="checkbox"
      true-value="courier"
      false-value="pickup"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Доставка курьером"
      class="gap-x-2"
    />

    <span class="text-content-secondary">Значение модели: {{ delivery }}</span>
  </div>
</template>
```

### Multiple selection

If the model is an array, the controls work in `multiple` mode: every control
adds its `value` to it and removes it when unchecked. The mode is turned on
automatically — the `multiple` prop is needed only to set it by hand. Comparing
the values is the job of `value-comparator`, a deep comparison by default.

**Example — `Multiple.vue`:**

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

const channels = [
  { value: 'email', label: 'Почта' },
  { value: 'sms', label: 'SMS' },
  { value: 'push', label: 'Push-уведомления' }
];

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

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-for="channel of channels"
      :key="channel.value"
      v-model="selected"
      type="checkbox"
      :value="channel.value"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      :label="channel.label"
      class="gap-x-2"
    />

    <span class="text-content-secondary">Значение модели: {{ selected }}</span>
  </div>
</template>
```

### States

`disabled` blocks the control and dims its color, `readonly` forbids changing
the value while keeping the look. `error` puts the `--error` modifier on the
root — the error color is drawn for it by the styles of the particular control,
the base component has none.

**Example — `States.vue`:**

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

const readonly = ref(true);
const error = ref(true);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      :model-value="true"
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Обычное состояние"
      class="gap-x-2"
    />

    <CdsSelectionControl
      :model-value="true"
      disabled
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Заблокирован (disabled)"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="readonly"
      readonly
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Только для чтения (readonly)"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="error"
      error
      color="green"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Ошибка (error)"
      class="gap-x-2"
    />
  </div>
</template>
```

### Colors

`color` sets the color of the selected control, `base-color` the color of an
unselected one. The values are the colors of the design system palette.

**Example — `Colors.vue`:**

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

const selected = ref(true);
const unselected = ref(false);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="selected"
      color="green"
      base-color="purple"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Выбран: цвет из color"
      class="gap-x-2"
    />

    <CdsSelectionControl
      v-model="unselected"
      color="green"
      base-color="purple"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      label="Не выбран: цвет из base-color"
      class="gap-x-2"
    />
  </div>
</template>
```

### Layout

Inside a flex container the control stretches together with its neighbors. The
`inline` prop leaves it the width of its content — that way the controls can
stand in a row without extra gaps.

**Example — `Inline.vue`:**

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

const stretched = ref(['first']);
const inline = ref(['first']);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">По умолчанию контролы делят ширину поровну</span>

      <div class="flex">
        <CdsSelectionControl
          v-model="stretched"
          value="first"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Да"
          class="gap-x-2"
        />

        <CdsSelectionControl
          v-model="stretched"
          value="second"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Нет"
          class="gap-x-2"
        />
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">С inline контрол занимает ширину своего содержимого</span>

      <div class="flex gap-3">
        <CdsSelectionControl
          v-model="inline"
          inline
          value="first"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Да"
          class="gap-x-2"
        />

        <CdsSelectionControl
          v-model="inline"
          inline
          value="second"
          type="checkbox"
          true-icon="checkbox-on"
          false-icon="checkbox-off"
          label="Нет"
          class="gap-x-2"
        />
      </div>
    </div>
  </div>
</template>
```

### Slots

Slots replace the content coming from the props and the markup of the control
itself.

| Slot          | Description                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `default`     | Content inside the control area, before the `input`. Receives the classes and the background color styles |
| `input`       | The whole markup of the control. Receives `model`, the ready `inputNode` and the current `icon`           |
| `label`       | Content of the label. Replaces `label`                                                                    |
| `description` | Content of the description. Replaces `description`                                                        |

**Example — `Slots.vue`:**

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

const beta = ref(true);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="beta"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      class="gap-x-2"
    >
      <template #label>
        <span class="flex items-center gap-1">
          Ранний доступ
          <CdsTag text="beta" size="sm" />
        </span>
      </template>

      <template #description> Новые возможности до общего релиза — <CdsLink href="#" text="что входит" /> </template>
    </CdsSelectionControl>
  </div>
</template>
```

## Scenarios

### A selection tile

The `input` slot replaces the icon with your own markup, and the native `input`
from `inputNode` stays on top of it and catches the clicks and the focus. The
size of the clickable area is set by the `--cds-selection-control-width` and
`--cds-selection-control-height` variables, and the state arrives in the slot
through `model`.

**Example — `Tile.vue`:**

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

const plans = [
  { value: 'base', title: 'Базовый', price: '0 ₽ в месяц' },
  { value: 'pro', title: 'Профи', price: '2 900 ₽ в месяц' }
];

const plan = ref('base');
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsSelectionControl
      v-for="item of plans"
      :key="item.value"
      v-model="plan"
      inline
      type="radio"
      :value="item.value"
      :aria-label="item.title"
      :style="{ '--cds-selection-control-width': '170px', '--cds-selection-control-height': '72px' }"
    >
      <template #input="{ inputNode, model }">
        <component :is="inputNode" />

        <div
          class="flex h-full w-full flex-col justify-center rounded-200 border px-3"
          :class="model.value ? 'border-line-selected ring-1 ring-line-selected' : 'border-line-primary'"
        >
          <span>{{ item.title }}</span>
          <span class="text-content-secondary">{{ item.price }}</span>
        </div>
      </template>
    </CdsSelectionControl>
  </div>
</template>
```

### Consent before submitting

The control does not show messages — that is the job of the
CdsInput wrapper. Without it, render the error text
next to the control and pass `error` to it: the modifier will come in handy for
your styles.

**Example — `Consent.vue`:**

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

const agreed = ref(false);
const touched = ref(false);
const sent = ref(false);

function submit() {
  touched.value = true;
  sent.value = agreed.value;
}
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControl
      v-model="agreed"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      :error="touched && !agreed"
      class="gap-x-2"
    >
      <template #label> Согласен с <CdsLink href="#" text="условиями обработки данных" /> </template>
    </CdsSelectionControl>

    <span v-if="touched && !agreed" class="text-status-danger-content">Без согласия заявку не отправить</span>
    <span v-else-if="sent" class="text-status-success-content">Заявка отправлена</span>

    <CdsButton text="Отправить заявку" class="self-start" @click="submit" />
  </div>
</template>
```

## API

### CdsSelectionControl

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `falseIcon` | `IconValue \| undefined` | — | no | Icon of the unselected state |
| `falseValue` | `any` | — | no | Value for the false state. |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `trueIcon` | `IconValue \| undefined` | — | no | Icon of the selected state |
| `trueValue` | `any` | — | no | Value for the true state. |
| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
| `value` | `any` | — | no | Value used when the component is selected inside a group. When it is not set, a unique identifier is used. |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: any]` | Fires when the model of the component changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }` | Default slot |
| `description` | `{ description: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsDescription component |
| `input` | `SelectionControlSlot` | Slot for the default input element. |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `input` | `HTMLInputElement \| undefined` | Ref to the native `input` element — a checkbox or a radio button. |
| `isFocused` | `boolean` | Whether the control is focused. |

---

# CdsSelectionControlGroup

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 22/22 · 36 unit · 4 known bugs · lines 97.1% (v4.0.0-alpha.13) · a11y: 2 axe recommendations (v4.0.0-alpha.11)_

A container for a set of selection controls: it holds the shared value, hands the nested CdsSelectionControl the type, the icons, the colors and the states, and ties them together with a single `name` attribute. The radio button group of the design system is built on it.

**See also:** For a ready group with a title, a description and messages take CdsRadioGroup: it is assembled from this group and the CdsInput wrapper. `CdsSelectionControlGroup` is needed when you build your own set of controls.

## Variations

### Shared model and type

The value of the selected control is held by the group: `v-model` is on it,
every nested control only has its own `value`. The `type`, `true-icon` and
`false-icon` props are handed by the group to all the controls, and the shared
`name` attribute for the native `input` elements is created by the group itself
— it can be overridden with the `name` prop.

**Example — `Model.vue`:**

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

const delivery = ref('courier');
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControlGroup v-model="delivery" type="radio" true-icon="radio-on" false-icon="radio-off">
      <CdsSelectionControl value="courier" label="Курьером" class="gap-x-2" />
      <CdsSelectionControl value="pickup" label="Самовывоз" class="gap-x-2" />
      <CdsSelectionControl value="post" label="Почтой" class="gap-x-2" />
    </CdsSelectionControlGroup>

    <span class="text-content-secondary">Значение модели: {{ delivery }}</span>
  </div>
</template>
```

### Multiple selection

An array in the model turns on `multiple` mode: every control adds its `value`
to it. The mode is turned on automatically — the `multiple` prop is needed only
to set it by hand.

**Example — `Multiple.vue`:**

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

const channels = ref(['email']);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControlGroup
      v-model="channels"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      direction="vertical"
    >
      <CdsSelectionControl value="email" label="Почта" class="gap-x-2" />
      <CdsSelectionControl value="sms" label="SMS" class="gap-x-2" />
      <CdsSelectionControl value="push" label="Push-уведомления" class="gap-x-2" />
    </CdsSelectionControlGroup>

    <span class="text-content-secondary">Значение модели: {{ channels }}</span>
  </div>
</template>
```

### Direction

By default the controls line up in a row and split the width of the group
evenly. `direction="vertical"` puts them in a column — handier for long captions
and for sets with descriptions.

**Example — `Direction.vue`:**

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

const horizontal = ref('year');
const vertical = ref('year');
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Горизонтально — по умолчанию</span>

      <CdsSelectionControlGroup v-model="horizontal" type="radio" true-icon="radio-on" false-icon="radio-off">
        <CdsSelectionControl value="year" label="Год" class="gap-x-2" />
        <CdsSelectionControl value="quarter" label="Квартал" class="gap-x-2" />
        <CdsSelectionControl value="month" label="Месяц" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Вертикально</span>

      <CdsSelectionControlGroup
        v-model="vertical"
        direction="vertical"
        type="radio"
        true-icon="radio-on"
        false-icon="radio-off"
      >
        <CdsSelectionControl value="year" label="Год" class="gap-x-2" />
        <CdsSelectionControl value="quarter" label="Квартал" class="gap-x-2" />
        <CdsSelectionControl value="month" label="Месяц" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>
  </div>
</template>
```

### States

`disabled` blocks the whole group, `readonly` forbids changing the selection
without changing the look, `error` puts every control into the error state. A
single option is blocked by the `disabled` prop of the control itself.

**Example — `States.vue`:**

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

const disabled = ref('courier');
const readonly = ref('courier');
const partly = ref('courier');
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">disabled — заблокирована вся группа</span>

      <CdsSelectionControlGroup
        v-model="disabled"
        disabled
        type="radio"
        color="green"
        true-icon="radio-on"
        false-icon="radio-off"
      >
        <CdsSelectionControl value="courier" label="Курьером" class="gap-x-2" />
        <CdsSelectionControl value="pickup" label="Самовывоз" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">readonly — вид прежний, выбор не меняется</span>

      <CdsSelectionControlGroup
        v-model="readonly"
        readonly
        type="radio"
        color="green"
        true-icon="radio-on"
        false-icon="radio-off"
      >
        <CdsSelectionControl value="courier" label="Курьером" class="gap-x-2" />
        <CdsSelectionControl value="pickup" label="Самовывоз" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Отдельный контрол блокируется своим disabled</span>

      <CdsSelectionControlGroup v-model="partly" type="radio" color="green" true-icon="radio-on" false-icon="radio-off">
        <CdsSelectionControl value="courier" label="Курьером" class="gap-x-2" />
        <CdsSelectionControl value="pickup" disabled label="Самовывоз" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>
  </div>
</template>
```

### Colors and icons

`color` sets the color of the selected control, `base-color` the color of the
unselected ones, `true-icon` and `false-icon` the pair of state icons. The
values apply to all the controls of the group at once.

**Example — `ColorsAndIcons.vue`:**

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

const plan = ref('pro');
const favorites = ref(['first']);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">color — выбранный, base-color — остальные</span>

      <CdsSelectionControlGroup
        v-model="plan"
        type="radio"
        color="green"
        base-color="purple"
        true-icon="radio-on"
        false-icon="radio-off"
      >
        <CdsSelectionControl value="base" label="Базовый" class="gap-x-2" />
        <CdsSelectionControl value="pro" label="Профи" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Своя пара иконок для всей группы</span>

      <CdsSelectionControlGroup v-model="favorites" type="checkbox" true-icon="star-fill" false-icon="star">
        <CdsSelectionControl value="first" label="Первый" class="gap-x-2" />
        <CdsSelectionControl value="second" label="Второй" class="gap-x-2" />
      </CdsSelectionControlGroup>
    </div>
  </div>
</template>
```

### Passing the settings through

The group gives its settings to the component whose name is set in
`defaults-target` — `CdsSelectionControl` by default. Put the name of a
ready-made control there and the group starts controlling it: that is how
CdsRadioGroup hands the settings to the radio
buttons.

**Example — `DefaultsTarget.vue`:**

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

const categories = ref(['office']);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControlGroup v-model="categories" defaults-target="CdsCheckbox" type="checkbox" direction="vertical">
      <CdsCheckbox value="office" label="Канцелярия" hide-details />
      <CdsCheckbox value="furniture" label="Мебель" hide-details />
      <CdsCheckbox value="tech" label="Техника" hide-details />
    </CdsSelectionControlGroup>

    <span class="text-content-secondary">Значение модели: {{ categories }}</span>
  </div>
</template>
```

## Scenarios

### Filtering by categories

An array model collects the checked categories, and the list is rebuilt on the
fly through a computed. `inline` leaves the controls the width of their
captions, so the filters go in a dense row.

**Example — `Filters.vue`:**

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

const categories = [
  { value: 'office', label: 'Канцелярия' },
  { value: 'furniture', label: 'Мебель' },
  { value: 'tech', label: 'Техника' }
];

const products = [
  { title: 'Бумага А4', category: 'office' },
  { title: 'Кресло офисное', category: 'furniture' },
  { title: 'Монитор 27"', category: 'tech' },
  { title: 'Стеллаж', category: 'furniture' }
];

const selected = ref<string[]>([]);

const items = computed(() =>
  products
    .filter((product) => !selected.value.length || selected.value.includes(product.category))
    .map((product) => ({ title: product.title }))
);
</script>

<template>
  <div class="m-auto flex w-[350px] flex-col gap-2">
    <CdsSelectionControlGroup
      v-model="selected"
      type="checkbox"
      true-icon="checkbox-on"
      false-icon="checkbox-off"
      class="gap-3"
    >
      <CdsSelectionControl
        v-for="category of categories"
        :key="category.value"
        inline
        :value="category.value"
        :label="category.label"
        class="gap-x-2"
      />
    </CdsSelectionControlGroup>

    <CdsList :items="items" />
  </div>
</template>
```

### Selection tiles

The group does not dictate the markup to the controls: in the `input` slot every
control draws its own tile, while the group still holds the selected value and
ties the native `input` elements together with a single `name`.

**Example — `Tiles.vue`:**

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

const slots = [
  { value: 'morning', title: 'Утро', time: '9:00 — 12:00' },
  { value: 'day', title: 'День', time: '12:00 — 17:00' },
  { value: 'evening', title: 'Вечер', time: '17:00 — 21:00' }
];

const slot = ref('day');
</script>

<template>
  <CdsSelectionControlGroup v-model="slot" type="radio" class="justify-center gap-2">
    <CdsSelectionControl
      v-for="item of slots"
      :key="item.value"
      inline
      :value="item.value"
      :aria-label="`${item.title}, ${item.time}`"
      :style="{ '--cds-selection-control-width': '140px', '--cds-selection-control-height': '64px' }"
    >
      <template #input="{ inputNode, model }">
        <component :is="inputNode" />

        <div
          class="flex h-full w-full flex-col justify-center rounded-200 border px-3"
          :class="model.value ? 'border-line-selected ring-1 ring-line-selected' : 'border-line-primary'"
        >
          <span>{{ item.title }}</span>
          <span class="text-content-secondary">{{ item.time }}</span>
        </div>
      </template>
    </CdsSelectionControl>
  </CdsSelectionControlGroup>
</template>
```

## API

### CdsSelectionControlGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `falseIcon` | `IconValue \| undefined` | — | no | Icon of the unselected state |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `trueIcon` | `IconValue \| undefined` | — | no | Icon of the selected state |
| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: any]` | Fires when the selection inside the group changes. Passes the new value of the group |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | The controls of the group — checkboxes or radio buttons |

---

# CdsSkeletonLoader

_Category: Feedback · since 4.0.0_

_Tests: API 12/12 · 18 unit · 1 known bug · lines 94.1% (v4.0.0-alpha.13) · a11y: 0 axe recommendations (v4.0.0-alpha.11)_

A skeleton shows the shape of the future content while the data is loading: instead of an empty screen the user immediately sees where the heading, the text and the buttons will appear. The ready-made types (`type`) are assembled from "bones" — blanks for an avatar, a line of text, a button or a table.

**See also:** A skeleton fits the first load of a block or a page. For waiting inside a single action — submitting a form, saving — take the `loading` prop of CdsButton or CdsProgressCircle. If there is no data at all, show CdsEmptyState.

## Anatomy

A skeleton is a container with nested "bones": every bone repeats the shape of
one element of the future content. The `list-item-avatar-two-line, actions` type
unfolds into a circle for the avatar, two lines of text and two buttons.

## Variations

### Types

The `type` prop takes a ready-made structure from the catalog: `article` — a
heading and a paragraph, `card` — an image with a heading, `table` — a header,
rows and a footer.

**Example — `Presets.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <CdsSkeletonLoader type="article" width="260" />
    <CdsSkeletonLoader type="card" width="260" />
    <CdsSkeletonLoader type="list-item-avatar-three-line" width="260" />
    <CdsSkeletonLoader type="table" width="360" />
  </div>
</template>
```

### Your own structure

The type can be described with a string: a comma-separated list puts bones one
after another, and `@N` repeats a bone N times. An array of strings works the
same way as a comma-separated list.

**Example — `Structure.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <CdsSkeletonLoader type="heading, text@3, actions" width="260" />
    <CdsSkeletonLoader :type="['avatar', 'sentences', 'divider', 'button']" width="260" />
  </div>
</template>
```

### Catalog of types

All the built-in types and their structures. Any of them can be inserted into
your own string as a bone — `heading, table-row@3`.

**Example — `AllTypes.vue`:**

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

import { allowedTypes } from '../../api/CdsSkeletonLoader.types';

const types = allowedTypes;
</script>

<template>
  <div class="flex flex-col gap-4 max-w-[420px] m-auto">
    <div v-for="(structure, type) in types" :key="type" class="flex flex-col gap-1">
      <div class="text-sm">
        <strong>{{ type }}</strong> — <code>{{ structure }}</code>
      </div>
      <CdsSkeletonLoader :type="type" boilerplate />
    </div>
  </div>
</template>
```

### Sizes

The `width`, `height`, `min-width` and `max-width` props set the size of the
container — the bones stretch along it. Give the skeleton the same size as the
future content, so that the layout does not jump when the data arrives.

**Example — `Sizes.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <CdsSkeletonLoader width="200" height="80" />
    <CdsSkeletonLoader type="article" width="200" />
    <CdsSkeletonLoader type="article" max-width="140" />
  </div>
</template>
```

### Replacing the content

Put the content into the default slot: while `loading` is true, the skeleton is
visible in its place, and afterwards — the content itself, with no wrapper. The
`loading-text` prop sets the `aria-label` — a screen reader will announce what
exactly is loading.

**Example — `Loading.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsCardActions,
  CdsCardItem,
  CdsCardText,
  CdsSkeletonLoader
} from '@central-design-system/components';
import { ref } from 'vue';

const isLoading = ref(true);
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsButton variant="soft" color="brand" text="Переключить загрузку" @click="isLoading = !isLoading" />

    <CdsCard width="360">
      <CdsSkeletonLoader :loading="isLoading" type="heading, text@2, actions" height="180">
        <CdsCardItem title="Договор № 1024" subtitle="Поставка комплектующих" />
        <CdsCardText>Срок исполнения — 14 дней с момента подписания.</CdsCardText>
        <CdsCardActions align="end">
          <CdsButton variant="soft" color="neutral" text="Открыть" />
        </CdsCardActions>
      </CdsSkeletonLoader>
    </CdsCard>
  </div>
</template>
```

### Without animation

The `boilerplate` prop turns the shimmer off. Such a skeleton is a blank for
mockups and static prototypes; on a live screen it does not communicate waiting.

**Example — `Boilerplate.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <CdsSkeletonLoader type="card-avatar, article, actions" width="260" />
    <CdsSkeletonLoader type="card-avatar, article, actions" width="260" boilerplate />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The skeleton repeats the structure of the future content: a heading, lines of text, buttons. | A gray rectangle instead of a structure does not tell what will appear in its place. |
| As many bones as there will be items — the list does not jump after loading. | Eight skeleton rows for three records: the content arrives and the height collapses. |
| The shimmer animation shows that the loading is happening right now. | A static boilerplate on a live screen reads as broken layout — it is for mockups only. |

## Scenarios

### List of participants

While the list is loading, `type="list-item-avatar-two-line@3"` holds the space
for three records: an avatar and two lines of text in each. The slot hands over
the ready list as soon as the data arrives, so no `v-if` is needed in the
template.

**Example — `FeedList.vue`:**

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

const isLoading = ref(true);

const members = [
  { id: 1, initials: 'АС', name: 'Анна Соколова', role: 'Менеджер по закупкам' },
  { id: 2, initials: 'ПК', name: 'Пётр Ковалёв', role: 'Юрист' },
  { id: 3, initials: 'МЛ', name: 'Мария Лебедева', role: 'Бухгалтер' }
];

function load() {
  isLoading.value = true;
  setTimeout(() => (isLoading.value = false), 1500);
}

load();
</script>

<template>
  <div class="flex flex-col gap-3 w-[320px] m-auto">
    <CdsButton variant="soft" color="brand" text="Загрузить заново" :disabled="isLoading" @click="load" />

    <CdsSkeletonLoader :loading="isLoading" type="list-item-avatar-two-line@3" loading-text="Загружаем участников">
      <div class="flex flex-col gap-3">
        <div v-for="member in members" :key="member.id" class="flex items-center gap-2">
          <CdsAvatar :content="member.initials" />
          <div class="flex flex-col">
            <span class="font-medium">{{ member.name }}</span>
            <span class="text-sm opacity-70">{{ member.role }}</span>
          </div>
        </div>
      </div>
    </CdsSkeletonLoader>
  </div>
</template>
```

### Table of contracts

A skeleton of `table-heading, table-row@3` repeats the header and the rows of
the table, and `loading-text` explains the wait to the screen reader. The number
of rows matches the page size of the data — after loading, the height of the
block does not change.

**Example — `DataTable.vue`:**

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

const isLoading = ref(true);

const rows = [
  { id: 1, number: '1024', customer: 'ООО «Ромашка»', sum: '120 000 ₽' },
  { id: 2, number: '1025', customer: 'АО «Вектор»', sum: '86 400 ₽' },
  { id: 3, number: '1026', customer: 'ИП Смирнов', sum: '15 900 ₽' }
];

function load() {
  isLoading.value = true;
  setTimeout(() => (isLoading.value = false), 1500);
}

load();
</script>

<template>
  <div class="flex flex-col gap-3 w-[420px] m-auto">
    <CdsButton variant="soft" color="brand" text="Обновить данные" :disabled="isLoading" @click="load" />

    <CdsSkeletonLoader :loading="isLoading" type="table-heading, table-row@3" loading-text="Загружаем договоры">
      <table class="w-full text-left">
        <thead>
          <tr class="text-sm opacity-70">
            <th class="py-1 font-medium">Номер</th>
            <th class="py-1 font-medium">Заказчик</th>
            <th class="py-1 font-medium">Сумма</th>
          </tr>
        </thead>
        <tbody>
          <tr v-for="row in rows" :key="row.id">
            <td class="py-1">{{ row.number }}</td>
            <td class="py-1">{{ row.customer }}</td>
            <td class="py-1">{{ row.sum }}</td>
          </tr>
        </tbody>
      </table>
    </CdsSkeletonLoader>
  </div>
</template>
```

### Page frame

On the first load of a page the blocks load independently, so each one has its
own skeleton: the list of sections is `list-item@4`, the content is `heading,
paragraph, paragraph`. A block that is ready appears right away, without waiting
for its neighbor.

**Example — `PageLayout.vue`:**

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

const isLoading = ref(true);

const sections = ['Общие сведения', 'Документы', 'Участники', 'История'];

function load() {
  isLoading.value = true;
  setTimeout(() => (isLoading.value = false), 1500);
}

load();
</script>

<template>
  <div class="flex flex-col gap-4 w-[460px] m-auto">
    <CdsButton variant="soft" color="brand" text="Открыть страницу заново" :disabled="isLoading" @click="load" />

    <div class="grid grid-cols-[150px_1fr] gap-4">
      <CdsSkeletonLoader :loading="isLoading" type="list-item@4" loading-text="Загружаем разделы">
        <nav class="flex flex-col gap-2">
          <CdsLink v-for="section in sections" :key="section" href="#" :text="section" />
        </nav>
      </CdsSkeletonLoader>

      <CdsSkeletonLoader :loading="isLoading" type="heading, paragraph, paragraph" loading-text="Загружаем описание">
        <article class="flex flex-col gap-2">
          <h3 class="font-medium">Закупка комплектующих</h3>
          <p class="text-sm">
            Заказчик принимает заявки до 20 числа. Победитель определяется по совокупности цены и срока поставки.
          </p>
          <p class="text-sm">Документы можно подать в электронном виде — подписанные квалифицированной подписью.</p>
        </article>
      </CdsSkeletonLoader>
    </div>
  </div>
</template>
```

## API

### CdsSkeletonLoader

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `boilerplate` | `boolean \| undefined` | `false` | no | Boilerplate mode: turns the shimmer animation off (for prototyping). |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `loading` | `boolean \| undefined` | `false` | no | Shows the skeleton instead of the slot content while loading. |
| `loadingText` | `string \| undefined` | — | no | Text for the `aria-label` while loading. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `theme` | `string \| undefined` | — | no | Component theme |
| `type` | `(string & {}) \| "text" \| "block" \| "article" \| "button" \| "table" \| "divider" \| "subtitle" \| "chip" \| "avatar" \| "actions" \| "heading" \| "sentences" \| "paragraph" \| "card" \| "card-avatar" \| "date-picker" \| "date-picker-options" \| "date-picker-days" \| "list-item" \| "list-item-avatar" \| "list-item-two-line" \| "list-item-avatar-two-line" \| "list-item-three-line" \| "list-item-avatar-three-line" \| "table-heading" \| "table-thead" \| "table-tbody" \| "table-row-divider" \| "table-row" \| "table-tfoot" \| readonly ((string & {}) \| "text" \| "block" \| "article" \| "button" \| "table" \| "divider" \| "subtitle" \| "chip" \| "avatar" \| "actions" \| "heading" \| "sentences" \| "paragraph" \| "card" \| "card-avatar" \| "date-picker" \| "date-picker-options" \| "date-picker-days" \| "list-item" \| "list-item-avatar" \| "list-item-two-line" \| "list-item-avatar-two-line" \| "list-item-three-line" \| "list-item-avatar-three-line" \| "table-heading" \| "table-thead" \| "table-tbody" \| "table-row-divider" \| "table-row" \| "table-tfoot")[] \| undefined` | `'block'` | no | Skeleton type: a predefined preset or an arbitrary structure string (or an array of strings). |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content rendered instead of the skeleton once the loading is done. |

---

# CdsSlideGroup

_Category: Atoms · since 4.0.0_

_Tests: none yet — behavior is not covered by automated tests_

A slide group lays a set of elements out in a single scrollable line: when the elements do not fit, the strip is paged with arrows. It can also drive a selection through `v-model` — CdsTabs and CdsTagGroup are built on the slide group.

**See also:** For a bar of sections take the ready CdsTabs, for picking tags take CdsTagGroup, and to page through slides one by one take CdsSlideView.

## Anatomy

Arrow buttons sit at the edges of the container, and the strip of elements
scrolls between them. The arrows appear only when the strip does not fit into
the container, and they page it by the width of the visible area.

## Variations

### Scrolling and arrows

By default the arrows appear on a desktop when the elements do not fit into the
container; on mobile the strip is scrolled with a finger without arrows. The
`show-arrows` prop changes this behavior: `true` shows the arrows on overflow
and on mobile, `desktop` and `mobile` always show them on the matching devices,
`always` always shows them, `never` never does.

**Example — `Arrows.vue`:**

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

<template>
  <div class="m-auto max-w-[520px]">
    <CdsSlideGroup show-arrows>
      <CdsSlideGroupItem v-for="n in 15" :key="n">
        <CdsButton variant="soft" color="neutral" class="m-1" :text="`Элемент ${n}`" />
      </CdsSlideGroupItem>
    </CdsSlideGroup>
  </div>
</template>
```

### Selecting elements

Wrap the elements into `CdsSlideGroupItem` and the group starts driving the
selection: `v-model` holds the value of the selected element from its `value`
prop. `CdsSlideGroupItem` itself renders nothing — its slot receives
`isSelected` and `toggle`, and how to show the selected state is up to you. The
`mandatory` prop forbids clearing the last selection.

**Example — `Selection.vue`:**

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

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

<template>
  <div class="m-auto max-w-[520px]">
    <CdsSlideGroup v-model="selected" mandatory show-arrows>
      <CdsSlideGroupItem v-for="n in 12" :key="n" v-slot="{ isSelected, toggle }" :value="n">
        <CdsButton
          :variant="isSelected ? 'solid' : 'soft'"
          :color="isSelected ? 'brand' : 'neutral'"
          class="m-1"
          :text="`Элемент ${n}`"
          @click="toggle"
        />
      </CdsSlideGroupItem>
    </CdsSlideGroup>
  </div>
</template>
```

The `multiple` prop allows selecting several elements — `v-model` becomes an
array, and `max` limits the number of selected ones.

**Example — `Multiple.vue`:**

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

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

<template>
  <div class="m-auto max-w-[520px]">
    <CdsSlideGroup v-model="selected" multiple :max="3" show-arrows>
      <CdsSlideGroupItem v-for="n in 12" :key="n" v-slot="{ isSelected, toggle }" :value="n">
        <CdsButton
          :variant="isSelected ? 'solid' : 'soft'"
          :color="isSelected ? 'brand' : 'neutral'"
          class="m-1"
          :text="`Элемент ${n}`"
          @click="toggle"
        />
      </CdsSlideGroupItem>
    </CdsSlideGroup>
  </div>
</template>
```

### The active element in the center

When the selection changes, the strip scrolls to the active element itself —
that is the job of `scroll-to-active`, which is on by default. The
`center-active` prop additionally keeps the active element in the center of the
container.

**Example — `CenterActive.vue`:**

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

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

<template>
  <div class="m-auto max-w-[520px]">
    <CdsSlideGroup v-model="selected" center-active mandatory show-arrows>
      <CdsSlideGroupItem v-for="n in 20" :key="n" v-slot="{ isSelected, toggle }" :value="n">
        <CdsButton
          :variant="isSelected ? 'solid' : 'soft'"
          :color="isSelected ? 'brand' : 'neutral'"
          class="m-1"
          :text="`Элемент ${n}`"
          @click="toggle"
        />
      </CdsSlideGroupItem>
    </CdsSlideGroup>
  </div>
</template>
```

### Vertical group

The `direction="vertical"` prop turns the strip into a column — limit its height
with `max-height` on the group itself.

**Example — `Vertical.vue`:**

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

<template>
  <div class="m-auto flex justify-center">
    <CdsSlideGroup direction="vertical" show-arrows class="max-h-[220px]">
      <CdsSlideGroupItem v-for="n in 12" :key="n">
        <CdsButton variant="soft" color="neutral" class="m-1" :text="`Элемент ${n}`" />
      </CdsSlideGroupItem>
    </CdsSlideGroup>
  </div>
</template>
```

### Slots

| Slot      | Description                                                    |
| --------- | -------------------------------------------------------------- |
| `default` | The elements of the strip, usually `CdsSlideGroupItem`         |
| `prev`    | Your own content for the "back" button instead of the arrow    |
| `next`    | Your own content for the "forward" button instead of the arrow |

All the slots receive the `prev`, `next`, `select` and `isSelected` methods. The
click on the area of an arrow is handled by the group itself, so it is enough to
put the visuals only into `prev` / `next`. The icons of the default arrows are
changed without slots — with the `prev-icon` and `next-icon` props.

**Example — `CustomArrows.vue`:**

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

<template>
  <div class="m-auto max-w-[520px]">
    <CdsSlideGroup show-arrows="always">
      <template #prev>
        <CdsFunctionalButton icon="arrow-left" aria-label="Назад" />
      </template>

      <CdsSlideGroupItem v-for="n in 15" :key="n">
        <CdsButton variant="soft" color="neutral" class="m-1" :text="`Элемент ${n}`" />
      </CdsSlideGroupItem>

      <template #next>
        <CdsFunctionalButton icon="arrow-right" aria-label="Вперёд" />
      </template>
    </CdsSlideGroup>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The arrows hint that the strip scrolls and that there are more elements than visible. | Without arrows a cut-off element is the only hint of scrolling, and it is easy to miss. |
| Elements of the same kind and size page predictably and read as a single row. | A mix of components of different sizes makes the strip ragged — it no longer reads as one list. |

## Scenarios

### Booking an appointment

Two slide groups with a selection: the strip of days with `center-active` keeps
the selected date in the center, and the strip of times is more compact — with
`size="sm"` buttons. Both lists use `mandatory`: a booking always has a selected
date and time.

**Example — `Booking.vue`:**

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

const days = [
  { value: '04.08', label: 'Пн, 4 авг' },
  { value: '05.08', label: 'Вт, 5 авг' },
  { value: '06.08', label: 'Ср, 6 авг' },
  { value: '07.08', label: 'Чт, 7 авг' },
  { value: '08.08', label: 'Пт, 8 авг' },
  { value: '11.08', label: 'Пн, 11 авг' },
  { value: '12.08', label: 'Вт, 12 авг' },
  { value: '13.08', label: 'Ср, 13 авг' }
];
const times = ['09:00', '10:00', '11:00', '12:00', '14:00', '15:00', '16:00', '17:00'];

const day = ref('06.08');
const time = ref('11:00');

const dayLabel = computed(() => days.find((item) => item.value === day.value)?.label);
</script>

<template>
  <div class="m-auto flex w-full max-w-[440px] flex-col gap-2">
    <CdsSlideGroup v-model="day" center-active mandatory show-arrows>
      <CdsSlideGroupItem v-for="item in days" :key="item.value" v-slot="{ isSelected, toggle }" :value="item.value">
        <CdsButton
          :variant="isSelected ? 'solid' : 'soft'"
          :color="isSelected ? 'brand' : 'neutral'"
          class="m-1"
          :text="item.label"
          @click="toggle"
        />
      </CdsSlideGroupItem>
    </CdsSlideGroup>

    <CdsSlideGroup v-model="time" mandatory show-arrows>
      <CdsSlideGroupItem v-for="item in times" :key="item" v-slot="{ isSelected, toggle }" :value="item">
        <CdsButton
          :variant="isSelected ? 'solid' : 'soft'"
          color="brand"
          size="sm"
          class="m-1"
          :text="item"
          @click="toggle"
        />
      </CdsSlideGroupItem>
    </CdsSlideGroup>

    <p class="m-0 text-center text-200 text-content-secondary">Встреча: {{ dayLabel }} в {{ time }}</p>
  </div>
</template>
```

### A strip of documents

The slide group works without a selection too — as a regular scrollable strip.
The cards go straight into the `default` slot without `CdsSlideGroupItem`, and
the arrows page the strip by the width of the visible area.

**Example — `CardsRow.vue`:**

```vue
<script setup lang="ts">
import { CdsIcon, CdsSlideGroup } from '@central-design-system/components';

const documents = [
  { title: 'Договор поставки', date: '28.07.2026' },
  { title: 'Спецификация № 4', date: '25.07.2026' },
  { title: 'Акт сверки', date: '21.07.2026' },
  { title: 'Счёт № 1042', date: '18.07.2026' },
  { title: 'Протокол разногласий', date: '14.07.2026' },
  { title: 'Коммерческое предложение', date: '10.07.2026' }
];
</script>

<template>
  <div class="m-auto max-w-[520px]">
    <CdsSlideGroup show-arrows>
      <div
        v-for="document in documents"
        :key="document.title"
        class="m-1 flex w-[160px] flex-col gap-1 rounded-200 bg-surface-secondary p-3"
      >
        <CdsIcon icon="file" />
        <span class="text-200">{{ document.title }}</span>
        <span class="text-100 text-content-secondary">{{ document.date }}</span>
      </div>
    </CdsSlideGroup>
  </div>
</template>
```

### A formatting bar

A toolbar inside a narrow container: icon buttons with `aria-label`, `multiple`
allows turning several formats on at once, and the `show-arrows="always"` arrows
page through the tools that did not fit.

**Example — `Toolbar.vue`:**

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

const formats = ref(['bold']);

const tools = [
  { value: 'bold', icon: 'bold', label: 'Жирный' },
  { value: 'italic', icon: 'italic', label: 'Курсив' },
  { value: 'underline', icon: 'underline', label: 'Подчёркнутый' },
  { value: 'highlight', icon: 'highlight', label: 'Маркер' },
  { value: 'list', icon: 'list-bullet', label: 'Список' },
  { value: 'link', icon: 'link', label: 'Ссылка' },
  { value: 'formula', icon: 'formula', label: 'Формула' },
  { value: 'insert', icon: 'paste', label: 'Вставка' }
];
</script>

<template>
  <div class="m-auto max-w-[280px]">
    <CdsSlideGroup v-model="formats" multiple show-arrows="always">
      <CdsSlideGroupItem v-for="tool in tools" :key="tool.value" v-slot="{ isSelected, toggle }" :value="tool.value">
        <CdsButton
          :variant="isSelected ? 'solid' : 'soft'"
          :color="isSelected ? 'brand' : 'neutral'"
          size="sm"
          class="m-1"
          :icon="tool.icon"
          :aria-label="tool.label"
          @click="toggle"
        />
      </CdsSlideGroupItem>
    </CdsSlideGroup>
  </div>
</template>
```

## API

### CdsSlideGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `centerActive` | `boolean \| undefined` | — | no | Forces the active component to be aligned to the center. |
| `contentClass` | `any` | — | no | Adds classes to the slide group container |
| `contentStyle` | `any` | — | no | Adds inline styles to the slide group container |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `mandatory` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `mobile` | `boolean \| null \| undefined` | `null` | no | Determines the display mode of the component: `true` renders it in mobile mode, `false` in desktop mode, `null` makes the mode depend on the current breakpoint. |
| `mobileBreakpoint` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | — | no | Sets the breakpoint at which the component switches to mobile mode. Accepts a number (for example, 600) or the name of a predefined breakpoint (`xs`, `sm`, `md`, `lg`, `xl`). |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `nextIcon` | `IconValue \| undefined` | `'chevron-right'` | no | Icon for the “next” button. |
| `prevIcon` | `IconValue \| undefined` | `'chevron-left'` | no | Icon for the “previous” button. |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `scrollToActive` | `boolean \| undefined` | `true` | no | When `true`, the container scrolls the active component into view whenever it changes. |
| `selectedClass` | `string \| undefined` | `'cds-slide-group-item--active'` | no | CSS class applied in the selected state |
| `showArrows` | `string \| boolean \| undefined` | — | no | Changes how the arrows are shown. By default the arrows appear on desktop devices when the container overflows and stay hidden on mobile devices. `true` also shows them on mobile on overflow, `desktop` always shows them on desktop, `mobile` always on mobile, `always` on both, and `never` disables the arrows. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `SlideGroupSlot` | Slot for the CdsSlideGroupItem components |
| `next` | `SlideGroupSlot` | Slot for the "next" button. |
| `prev` | `SlideGroupSlot` | Slot for the "previous" button. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `focus` | `(location?: "next" \| "prev" \| "first" \| "last" \| undefined) => void` | Focuses the component |
| `hasNext` | `boolean` | Returns true if there are elements after the current index. |
| `hasPrev` | `boolean` | Returns true if there are elements before the current index. |
| `scrollOffset` | `number` | Returns the scroll offset of the element |
| `scrollTo` | `(location: "next" \| "prev") => void` | Scrolls to the element by its index |
| `selected` | `readonly string[]` | Returns the index of the selected element |

### CdsSlideGroupItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `value` | `any` | — | no | Value of the component within the group |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `group:selected` | `[value: { value: boolean; }]` | Fires when an element is selected inside the group. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ isSelected: boolean; select: (value: boolean) => void; toggle: () => void; selectedClass: false \| (string \| undefined)[]; }` | Slot for the content |

---

# CdsSlideView

_Category: Atoms · since 4.0.0_

_Tests: none yet — behavior is not covered by automated tests_

A slide view shows one slide out of a set and switches them with a shift animation: arrows, swipes and `v-model` page forward and backward. It is the base for carousels and step-by-step interfaces — CdsCarousel is built on the slide view.

**See also:** For a carousel of images with dot delimiters and autoplay take the ready CdsCarousel, for sections with a navigation bar take CdsTabs, and for a strip where several elements are visible at once take CdsSlideGroup.

## Anatomy

The container shows one active `CdsSlideViewItem` slide, and the arrows at the
edges page to the neighboring ones — they are turned on by the `show-arrows`
prop. `v-model` holds the index of the active slide — or the value from the
`value` prop of the slide, if it is set.

## Variations

### Arrows

By default there are no arrows — the slides are paged with a swipe on touch
devices or programmatically through `v-model`. The `show-arrows` prop turns the
arrows on: `true` shows them at all times, `"hover"` only on hover over the
slide. Keyboard navigation comes together with the arrows. The swipe is turned
off with `:touch="false"`, and the icons of the arrows are changed with the
`prev-icon` and `next-icon` props.

**Example — `ArrowsHover.vue`:**

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

const slide = ref(0);
</script>

<template>
  <CdsSlideView v-model="slide" show-arrows="hover" continuous class="m-auto max-w-[520px]">
    <CdsSlideViewItem v-for="n in 4" :key="n">
      <div class="flex h-[180px] items-center justify-center bg-surface-secondary text-500">Слайд {{ n }}</div>
    </CdsSlideViewItem>
  </CdsSlideView>
</template>
```

### Vertical arrows

The `vertical-arrows` prop gathers the arrows turned on by `show-arrows` into a
column at the edge of the slide: `true` or `'left'` puts them on the left,
`'right'` on the right.

**Example — `VerticalArrows.vue`:**

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

const slide = ref(0);
</script>

<template>
  <CdsSlideView v-model="slide" show-arrows vertical-arrows="right" continuous class="m-auto max-w-[520px]">
    <CdsSlideViewItem v-for="n in 4" :key="n">
      <div class="flex h-[180px] items-center justify-center bg-surface-secondary text-500">Слайд {{ n }}</div>
    </CdsSlideViewItem>
  </CdsSlideView>
</template>
```

### Continuous paging

The `continuous` prop closes the slides into a ring: the first one follows the
last. Without it the matching arrow is hidden on the edge slides.

**Example — `Continuous.vue`:**

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

const slide = ref(0);
</script>

<template>
  <CdsSlideView v-model="slide" show-arrows continuous class="m-auto max-w-[520px]">
    <CdsSlideViewItem v-for="n in 4" :key="n">
      <div class="flex h-[180px] items-center justify-center bg-surface-secondary text-500">Слайд {{ n }}</div>
    </CdsSlideViewItem>
  </CdsSlideView>
</template>
```

### Direction

The `direction="vertical"` prop moves the slides vertically — the navigation
keys change together with the animation: ↑ / ↓ work instead of ← / →.

**Example — `Vertical.vue`:**

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

const slide = ref(0);
</script>

<template>
  <CdsSlideView v-model="slide" show-arrows direction="vertical" continuous class="m-auto max-w-[520px]">
    <CdsSlideViewItem v-for="n in 4" :key="n">
      <div class="flex h-[180px] items-center justify-center bg-surface-secondary text-500">Слайд {{ n }}</div>
    </CdsSlideViewItem>
  </CdsSlideView>
</template>
```

### Transitions

The `crossfade` prop replaces the shift with a soft dissolve — a good fit when
the slides are not lined up in a sequence. On a single `CdsSlideViewItem` the
animation is configured with the `transition` and `reverse-transition` props:
the name of your own transition animation or `false` to turn it off. The content
of a slide is rendered on the first show; the `eager` prop renders it right away
— useful for SEO.

**Example — `Crossfade.vue`:**

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

const slide = ref(0);
</script>

<template>
  <CdsSlideView v-model="slide" show-arrows crossfade continuous class="m-auto max-w-[520px]">
    <CdsSlideViewItem v-for="n in 4" :key="n">
      <div class="flex h-[180px] items-center justify-center bg-surface-secondary text-500">Слайд {{ n }}</div>
    </CdsSlideViewItem>
  </CdsSlideView>
</template>
```

### Slots

| Slot           | Description                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| `default`      | The `CdsSlideViewItem` slides                                                 |
| `prev`, `next` | Your own paging buttons; they receive `props` with `onClick` and `aria-label` |
| `additional`   | Content after the slides: indicators, a counter, captions                     |

The `additional` slot receives a `group` with the selection methods — but an
outer `v-model` is usually enough, as in the demo with the dot indicators.

**Example — `CustomControls.vue`:**

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

const slide = ref(0);
const total = 4;
</script>

<template>
  <CdsSlideView v-model="slide" show-arrows continuous class="m-auto max-w-[520px]">
    <template #prev="{ props }">
      <CdsButton variant="soft" color="brand" size="sm" icon="chevron-left" aria-label="Назад" @click="props.onClick" />
    </template>

    <CdsSlideViewItem v-for="n in total" :key="n">
      <div class="flex h-[180px] items-center justify-center bg-surface-secondary text-500">Слайд {{ n }}</div>
    </CdsSlideViewItem>

    <template #next="{ props }">
      <CdsButton
        variant="soft"
        color="brand"
        size="sm"
        icon="chevron-right"
        aria-label="Вперёд"
        @click="props.onClick"
      />
    </template>

    <template #additional>
      <div class="mt-2 flex justify-center gap-1">
        <button
          v-for="n in total"
          :key="n"
          type="button"
          class="h-[8px] w-[8px] cursor-pointer rounded-full border-none p-0"
          :class="slide === n - 1 ? 'bg-brand-primary' : 'bg-surface-secondary'"
          :aria-label="`Слайд ${n}`"
          @click="slide = n - 1"
        />
      </div>
    </template>
  </CdsSlideView>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Dots or a counter show how many slides there are and which one is open now. | Without a position indicator it is unclear how much content is hidden and where you are. |
| Slides of the same height: the container is stable and the content below does not jump. | Slides of different heights jerk the page on every switch. |

## Scenarios

### A step-by-step form

The steps of a questionnaire are switched with buttons through `v-model`: the
arrows stay off and the swipes are muted with `:touch="false"` — the only way to
move is "Back" and "Next". The height of the container animates to the content
of the active step automatically.

**Example — `Wizard.vue`:**

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

const step = ref(0);
const total = 3;

const name = ref('');
const email = ref('');
const company = ref('');
</script>

<template>
  <div class="m-auto flex w-full max-w-[400px] flex-col gap-2">
    <span class="text-200 text-content-secondary">Шаг {{ step + 1 }} из {{ total }}</span>

    <CdsSlideView v-model="step" :touch="false">
      <CdsSlideViewItem>
        <div class="flex flex-col gap-2">
          <CdsTextInput v-model="name" label="Имя" placeholder="Александра" />
          <CdsTextInput v-model="email" label="Рабочая почта" placeholder="name@company.ru" />
        </div>
      </CdsSlideViewItem>

      <CdsSlideViewItem>
        <div class="flex flex-col gap-2">
          <CdsTextInput v-model="company" label="Компания" placeholder="ООО «Ромашка»" />
        </div>
      </CdsSlideViewItem>

      <CdsSlideViewItem>
        <div class="rounded-200 bg-surface-secondary p-4">
          <p class="m-0 text-200">Проверьте данные перед отправкой:</p>
          <p class="m-0 mt-1 text-200 text-content-secondary">
            {{ name || 'Имя не указано' }} · {{ email || 'почта не указана' }} · {{ company || 'компания не указана' }}
          </p>
        </div>
      </CdsSlideViewItem>
    </CdsSlideView>

    <div class="flex justify-between">
      <CdsButton variant="soft" color="brand" text="Назад" :disabled="step === 0" @click="step--" />
      <CdsButton v-if="step < total - 1" text="Далее" @click="step++" />
      <CdsButton v-else text="Отправить" />
    </div>
  </div>
</template>
```

### Customer testimonials

The quotes are not lined up in a sequence, so `crossfade` replaces the shift.
The arrows appear on hover (`show-arrows="hover"`), the position is shown by a
counter in the `additional` slot, and `continuous` pages the testimonials in a
loop.

**Example — `Testimonials.vue`:**

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

const slide = ref(0);

const reviews = [
  {
    text: 'Перевели закупки в электронный вид за две недели — поставщики подключились без единого звонка в поддержку.',
    author: 'Мария, директор по закупкам'
  },
  {
    text: 'Удобно сравнивать предложения: все документы и цены собраны в одном месте.',
    author: 'Игорь, руководитель отдела снабжения'
  },
  {
    text: 'Интеграция с нашей учётной системой заняла один день. Теперь заявки уходят автоматически.',
    author: 'Светлана, ИТ-директор'
  }
];
</script>

<template>
  <CdsSlideView v-model="slide" crossfade continuous show-arrows="hover" class="m-auto max-w-[520px]">
    <CdsSlideViewItem v-for="review in reviews" :key="review.author">
      <figure class="m-0 flex h-[200px] flex-col justify-center gap-2 rounded-200 bg-surface-secondary px-12">
        <blockquote class="m-0 text-300">«{{ review.text }}»</blockquote>
        <figcaption class="text-200 text-content-secondary">{{ review.author }}</figcaption>
      </figure>
    </CdsSlideViewItem>

    <template #additional>
      <p class="m-0 mt-1 text-center text-200 text-content-secondary">{{ slide + 1 }} / {{ reviews.length }}</p>
    </template>
  </CdsSlideView>
</template>
```

### An events feed

A compact widget with vertical paging: `direction="vertical"` moves the events
from the bottom up, and `vertical-arrows="right"` gathers the arrows into a
column at the right edge.

**Example — `EventsFeed.vue`:**

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

const slide = ref(0);

const events = [
  { icon: 'notification', text: 'Новая заявка № 142 от ООО «Ромашка»', time: '2 минуты назад' },
  { icon: 'message', text: 'Поставщик ответил на вопрос по лоту № 7', time: '15 минут назад' },
  { icon: 'file', text: 'Подписан договор по закупке № 89', time: 'час назад' },
  { icon: 'trophy', text: 'Определён победитель тендера № 56', time: '3 часа назад' }
];
</script>

<template>
  <CdsSlideView
    v-model="slide"
    show-arrows
    direction="vertical"
    vertical-arrows="right"
    continuous
    class="m-auto max-w-[440px]"
  >
    <CdsSlideViewItem v-for="event in events" :key="event.text">
      <div class="flex h-[96px] items-center gap-3 rounded-200 bg-surface-secondary pl-4 pr-[64px]">
        <CdsIcon :icon="event.icon" />
        <div class="flex flex-col">
          <span class="text-200">{{ event.text }}</span>
          <span class="text-100 text-content-secondary">{{ event.time }}</span>
        </div>
      </div>
    </CdsSlideViewItem>
  </CdsSlideView>
</template>
```

## API

### CdsSlideView

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `continuous` | `boolean \| undefined` | — | no | Loops the navigation: from the last slide you move to the first one and back |
| `crossfade` | `boolean \| undefined` | — | no | Slides change with a smooth crossfade instead of a shift |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `mandatory` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `nextIcon` | `IconValue \| undefined` | `'chevron-right'` | no | Icon of the button that moves to the next slide |
| `prevIcon` | `IconValue \| undefined` | `'chevron-left'` | no | Icon of the button that moves to the previous slide |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `reverse` | `boolean \| undefined` | — | no | Inverts the direction of the transition animation between slides |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `showArrows` | `string \| boolean \| undefined` | — | no | Shows the navigation arrows. `'hover'` — only while the pointer is over the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `touch` | `boolean \| TouchHandlers \| undefined` | — | no | Controls swipe navigation: `false` turns the gestures off, an object sets your own touch handlers |
| `transitionDuration` | `number \| undefined` | — | no | Duration of the transition animation between slides, in milliseconds |
| `verticalArrows` | `boolean \| "left" \| "right" \| undefined` | — | no | Places the navigation arrows vertically: `'left'` or `'right'` — the side, `true` — the default side |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[]` | Fires when the active slide changes. Passes the value of the new active slide |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `additional` | `{ group: GroupProvide; }` | Extra content above the slides — indicator dots or your own navigation, for example |
| `default` | `{ group: GroupProvide; }` | Slides. The slot props carry the group state for controlling the active slide |
| `next` | `{ props: ControlProps; }` | Button that moves to the next slide. The slot props are ready to bind to your own button |
| `prev` | `{ props: ControlProps; }` | Button that moves to the previous slide. The slot props are ready to bind to your own button |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `group` | `GroupProvide` | State of the slide group: the list of elements, the active slide and the switching methods. |

### CdsSlideViewItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `reverseTransition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the reverse direction. A transition component name, or `false` to turn the animation off |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `transition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the forward direction. A transition component name, or `false` to turn the animation off |
| `value` | `any` | — | no | Value of the component within the group |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `group:selected` | `[value: { value: boolean; }]` | Fires when a slide is selected inside the group. `value` tells whether the slide became active |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the slide |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `groupItem` | `GroupItemProvide` | State of the slide inside the group: whether it is selected, its value and the toggle method. |

---

# CdsStages

_Category: Feedback · since 4.0.0 · status: deprecated_

_Tests: API 13/13 · 17 unit · 1 known bug · lines 100% (v4.0.0-alpha.13) · a11y: 9 axe recommendations (v4.0.0-alpha.11)_

A stage bar shows the course of a business process: which stages are behind, which one is running now and where the process stopped because of an error. The component only displays the status — the stages are not clickable, so the bar fits cards, headers and lists where the state of the process has to be read at a glance.

**See also:** The component is deprecated: do not write new code with it. It keeps working across the whole 4.x line and prints a `[CDS UPGRADE]` warning in the dev console; it will be removed in 5.0. To show the course of a process without step navigation use CdsSteps — without the `interactive` prop the steps are not clickable, and the header without `items` works as a status tracker (see the "Request status" scenario). Mind that the look differs: `CdsStages` is an arrow bar, `CdsSteps` is a row of indicators with a progress line. To switch between equally weighted sections — CdsTabs.

## Anatomy

The bar is a row of stages: each one has a title, and the arrow separators
between neighboring stages set the direction of the process. The color of a
stage encodes its state: neutral — the stage is ahead, accented — it is the
current one, green — passed, red — an error.

## Variations

### Stages

Pass an array of objects into `items`: the title and the value of a stage are
read by the `item-title` and `item-value` keys (`title` and `value` by default).
As long as `current` is not set, all the stages stay neutral — the process has
not started yet.

**Example — `Default.vue`:**

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

const items = [
  { title: 'Заявка', value: 1 },
  { title: 'Проверка', value: 2 },
  { title: 'Согласование', value: 3 },
  { title: 'Договор', value: 4 }
];
</script>

<template>
  <div class="flex items-center justify-center">
    <CdsStages :items="items" />
  </div>
</template>
```

### The current stage

`current` takes the value of the active stage: it is highlighted with the accent
color, and the stages to the left of it are marked as passed.

**Example — `Current.vue`:**

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

const items = [
  { title: 'Заявка', value: 1 },
  { title: 'Проверка', value: 2 },
  { title: 'Согласование', value: 3 },
  { title: 'Договор', value: 4 }
];
</script>

<template>
  <div class="flex items-center justify-center">
    <CdsStages :items="items" :current="3" />
  </div>
</template>
```

### An error

An error is set in the data of a stage — `props: { error: true }` on an `items`
element. The stage turns red once the process has reached it: when it is the
current one or is already passed.

**Example — `Error.vue`:**

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

const items = [
  { title: 'Заявка', value: 1 },
  { title: 'Проверка', value: 2 },
  { title: 'Согласование', value: 3, props: { error: true } },
  { title: 'Договор', value: 4 }
];
</script>

<template>
  <div class="flex items-center justify-center">
    <CdsStages :items="items" :current="3" />
  </div>
</template>
```

### Finishing the process

The `finished` prop marks all the stages as passed at once — the value of
`current` does not matter then.

**Example — `Finished.vue`:**

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

const items = [
  { title: 'Заявка', value: 1 },
  { title: 'Проверка', value: 2 },
  { title: 'Согласование', value: 3 },
  { title: 'Договор', value: 4 }
];
</script>

<template>
  <div class="flex items-center justify-center">
    <CdsStages :items="items" finished />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A stage title is one or two words: the bar is read at a glance. | Sentence-long titles stretch the stages and repeat the same words. |
| Three to six stages: each one is a meaningful milestone of the process. | Splitting into tiny steps turns the bar into an unreadable comb. |
| The error belongs to the stage where the process stopped: usually the current one. | Errors on passed stages alarm for nothing: the process moved on, they no longer matter. |

## Scenarios

### Order progress

The value of `current` comes from the data and changes as the order is
processed. Once the last stage is passed, turn `finished` on — the whole bar
becomes green.

**Example — `OrderTracking.vue`:**

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

const stages = [
  { title: 'Оформлен', value: 'created' },
  { title: 'Комплектация', value: 'assembly' },
  { title: 'В пути', value: 'shipping' },
  { title: 'Получен', value: 'delivered' }
];

const index = ref(0);

const finished = computed(() => index.value >= stages.length);
const current = computed(() => (finished.value ? null : stages[index.value].value));
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsStages class="w-full" :items="stages" :current="current" :finished="finished" />

    <CdsButton v-if="!finished" text="Следующий этап" @click="index++" />
    <CdsButton v-else variant="soft" color="brand" text="Оформить новый заказ" @click="index = 0" />
  </div>
</template>
```

### Rejected during review

The status of the listing is stored as a single string, and `items`, `current`
and `finished` are computed from it. On rejection the "Проверка" stage gets
`props.error` and turns red — the user immediately sees where the process
stopped.

**Example — `Moderation.vue`:**

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

type Status = 'review' | 'rejected' | 'published';

const status = ref<Status>('review');

const items = computed(() => [
  { title: 'Черновик', value: 'draft' },
  { title: 'Проверка', value: 'review', props: { error: status.value === 'rejected' } },
  { title: 'Публикация', value: 'published' }
]);

const current = computed(() => (status.value === 'rejected' ? 'review' : status.value));
const finished = computed(() => status.value === 'published');
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <CdsStages class="w-full" :items="items" :current="current" :finished="finished" />

    <div class="flex gap-2">
      <template v-if="status === 'review'">
        <CdsButton text="Одобрить" @click="status = 'published'" />
        <CdsButton variant="soft" color="brand" text="Отклонить" @click="status = 'rejected'" />
      </template>

      <CdsButton v-else variant="soft" color="brand" text="Вернуть на проверку" @click="status = 'review'" />
    </div>
  </div>
</template>
```

### Statuses in a list

The bar is compact and does not intercept clicks, so it is easy to repeat in
every row of a list or a table: the width comes from a utility class, and the
state of the row from its own `current`, `finished` and error.

**Example — `StatusList.vue`:**

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

interface Order {
  name: string;
  current?: number;
  error?: boolean;
  finished?: boolean;
}

const stages = [
  { title: 'Заявка', value: 1 },
  { title: 'Проверка', value: 2 },
  { title: 'Договор', value: 3 }
];

const orders: Order[] = [
  { name: 'Поставка канцтоваров', current: 2 },
  { name: 'Обслуживание техники', current: 2, error: true },
  { name: 'Ремонт переговорной', finished: true }
];

const stagesFor = (order: Order) =>
  stages.map((stage) => (order.error && stage.value === order.current ? { ...stage, props: { error: true } } : stage));
</script>

<template>
  <div class="m-auto flex w-[560px] flex-col gap-3">
    <div v-for="order in orders" :key="order.name" class="flex items-center justify-between gap-3">
      <span class="text-200">{{ order.name }}</span>

      <CdsStages
        class="w-[300px] shrink-0"
        :items="stagesFor(order)"
        :current="order.current"
        :finished="order.finished"
      />
    </div>
  </div>
</template>
```

## API

### CdsStages

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `current` | `string \| number \| null \| undefined` | `null` | no | Current stage |
| `finished` | `boolean \| undefined` | — | no | All stages are finished |
| `itemChildren` | `SelectItemKey` | `'children'` | no | Object field that holds the child items, or a function that returns them |
| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
| `itemType` | `SelectItemKey` | `'type'` | no | Object field that defines the item type (`item`, `divider`, `subheader`), or a function that returns it |
| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
| `returnObject` | `boolean \| undefined` | — | no | Return an object in the model value instead of an array |
| `theme` | `string \| undefined` | — | no | Component theme |
| `valueComparator` | `ValueComparator \| undefined` | — | no | Function that compares item values to determine the selected state |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isCurrent` | `(idx: number) => boolean` | Checks whether the stage with the given index is the current one. |
| `isFinished` | `boolean` | Whether all the stages are passed. |

---

# CdsStatus

_Category: Feedback · since 4.0.0_

_Tests: API 8/8 · 20 unit · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A status is a non-interactive indicator of the state of an object: the request is paid, the document is under review, the payment is overdue. The `status` prop sets the semantics — the color and the icon — while `variant` sets the display mode: a prominent filled badge or compact text with a colored icon.

**See also:** For labels with arbitrary palette colors — categories, filters — take CdsTag; for counters and marker dots in the corner of an element — CdsBadge.

## Variations

### Statuses

The `status` prop sets one of the five semantic statuses. Assign the values to
the states of the object: `info` — neutral, `progress` — the process is running,
`warning` — needs attention, `success` — success, `danger` — a problem.

**Example — `Statuses.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsStatus text="Новый" />
    <CdsStatus status="progress" text="В обработке" />
    <CdsStatus status="warning" text="Требует внимания" />
    <CdsStatus status="success" text="Оплачен" />
    <CdsStatus status="danger" text="Просрочен" />
  </div>
</template>
```

### Display mode

The `variant` prop controls how prominent the status is. `fill` (the default) is
a badge with a colored background; it catches the eye in lists and tables.
`text` has no background, a colored status icon and neutral text: the semantics
are kept, but the status does not compete with the surrounding content.

A similar "colored icon + text" pair can be assembled by hand — from
CdsIcon with the `color` prop and text next to it.
That way you are free to pick the icon and the color; `variant="text"`, on the
other hand, guarantees that the icon and the color always match the semantics of
the status.

**Example — `Variants.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <div class="flex items-center gap-2">
      <span class="w-[48px] text-100 text-content-secondary">fill</span>
      <CdsStatus status="success" text="Оплачен" />
    </div>
    <div class="flex items-center gap-2">
      <span class="w-[48px] text-100 text-content-secondary">text</span>
      <CdsStatus status="success" text="Оплачен" variant="text" />
    </div>
  </div>
</template>
```

### Indicator

The `indicator` prop puts a dot in the status color before the text. The status
reads more compactly and fits dense lists well. With `variant="text"` the dot
replaces the icon.

**Example — `Indicator.vue`:**

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

<template>
  <div class="flex flex-col items-center gap-2">
    <div class="flex flex-wrap items-center justify-center gap-2">
      <CdsStatus indicator text="Новый" />
      <CdsStatus indicator status="progress" text="В обработке" />
      <CdsStatus indicator status="warning" text="Требует внимания" />
      <CdsStatus indicator status="success" text="Оплачен" />
      <CdsStatus indicator status="danger" text="Просрочен" />
    </div>
    <div class="flex flex-wrap items-center justify-center gap-4">
      <CdsStatus indicator variant="text" text="Новый" />
      <CdsStatus indicator variant="text" status="progress" text="В обработке" />
      <CdsStatus indicator variant="text" status="success" text="Оплачен" />
      <CdsStatus indicator variant="text" status="danger" text="Просрочен" />
    </div>
  </div>
</template>
```

### Pulse

The `pulse` prop makes the dot pulse and works only together with `indicator`.
Enable it where a process is running right now: a check, an upload, a sync.
Finished and static states do not need it — endless motion distracts (WCAG
2.2.2). Under `prefers-reduced-motion` the pulse is turned off.

**Example — `Pulse.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsStatus indicator pulse status="progress" text="Идёт проверка" />
    <CdsStatus indicator pulse variant="text" status="progress" text="Идёт проверка" />
    <CdsStatus indicator status="success" text="Проверено" />
  </div>
</template>
```

### Status change

When the status changes, the color of the fill, the text and the dot transitions
smoothly, without a jump.

**Example — `StatusChange.vue`:**

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

const statuses = [
  { status: 'info', text: 'Черновик' },
  { status: 'progress', text: 'На проверке' },
  { status: 'warning', text: 'Нужны правки' },
  { status: 'success', text: 'Согласован' }
] as const;

const index = ref(0);
const current = computed(() => statuses[index.value]);
</script>

<template>
  <div class="flex items-center justify-center gap-4">
    <CdsStatus indicator :pulse="current.status === 'progress'" :status="current.status" :text="current.text" />
    <CdsButton
      size="sm"
      variant="soft"
      color="neutral"
      text="Сменить статус"
      @click="index = (index + 1) % statuses.length"
    />
  </div>
</template>
```

### Text

The text comes from the `text` prop. When you need markup — emphasis,
non-breaking spaces — use the `default` slot: it replaces the text from the
prop.

**Example — `WithSlot.vue`:**

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

<template>
  <div class="flex justify-center">
    <CdsStatus status="progress" variant="text">На проверке до <b>15&nbsp;августа</b></CdsStatus>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The color of the status matches its meaning: success is green, a problem is red. | The color contradicts the meaning — the user reads the signal before the text and draws the wrong conclusion. |
| The status text is one or two words, so the state is read instantly. | A long phrase does not fit and gets truncated with an ellipsis. Move the details into the text next to it. |
| One display mode per list: the statuses are easy to compare across rows. | Mixing fill and text in neighboring rows looks like equal states have different importance. |

## Scenarios

### Statuses of records in a list

In lists and tables a `fill` badge shows the state of a record at first glance.
Keep the vocabulary of statuses short and consistent across the whole section —
then the column can be scanned by color, without reading it.

**Example — `RecordsList.vue`:**

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

const orders = [
  { id: 4821, title: 'Поставка серверов', status: 'success', text: 'Оплачен' },
  { id: 4820, title: 'Закупка ноутбуков', status: 'progress', text: 'В обработке' },
  { id: 4819, title: 'Аренда склада', status: 'warning', text: 'Ждёт оплаты' },
  { id: 4818, title: 'Ремонт офиса', status: 'danger', text: 'Просрочен' }
] as const;
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <div v-for="order in orders" :key="order.id" class="flex items-center justify-between gap-4">
      <span>{{ order.title }}</span>
      <CdsStatus :status="order.status" :text="order.text" />
    </div>
  </div>
</template>
```

### Tracking a process

The status reflects the course of an asynchronous process: after being sent for
review the object moves to `progress`, and once it is done — to `success`. The
user sees the current state without reloading the page.

**Example — `ProcessTracking.vue`:**

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

const step = ref<'draft' | 'review' | 'done'>('draft');

const current = computed(() => {
  if (step.value === 'review') return { status: 'progress', text: 'На проверке' } as const;
  if (step.value === 'done') return { status: 'success', text: 'Согласован' } as const;

  return { status: 'info', text: 'Черновик' } as const;
});

const send = () => {
  step.value = 'review';

  setTimeout(() => {
    step.value = 'done';
  }, 2000);
};
</script>

<template>
  <div class="m-auto flex w-[360px] items-center justify-between gap-4">
    <div class="flex items-center gap-2">
      <span>Договор № 4821</span>
      <CdsStatus :status="current.status" :text="current.text" />
    </div>

    <CdsButton v-if="step !== 'done'" size="sm" text="На проверку" :loading="step === 'review'" @click="send" />
    <CdsButton v-else variant="soft" color="neutral" size="sm" text="Заново" @click="step = 'draft'" />
  </div>
</template>
```

### A status in a details block

In a dense info block — an invoice card, a panel of details — the `fill`
background pulls attention away. The `text` variant sits in line with the rest
of the data: the colored icon keeps the semantics, and the text stays neutral.

**Example — `DetailsCard.vue`:**

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

<template>
  <div class="m-auto flex w-[320px] flex-col gap-1">
    <div class="flex items-center justify-between">
      <span class="text-content-secondary">Счёт № 4821</span>
      <CdsStatus status="success" text="Оплачен" variant="text" />
    </div>
    <div class="flex items-center justify-between">
      <span class="text-content-secondary">Сумма</span>
      <span>124 500 ₽</span>
    </div>
    <div class="flex items-center justify-between">
      <span class="text-content-secondary">Срок оплаты</span>
      <span>15 августа</span>
    </div>
  </div>
</template>
```

## API

### CdsStatus

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `indicator` | `boolean \| undefined` | — | no | A dot in the status color before the text. With `variant="text"` it replaces the icon. |
| `pulse` | `boolean \| undefined` | — | no | Pulse of the dot. Works only together with `indicator`. Enable it only where a process is running right now: endless motion distracts and, per WCAG 2.2.2, should not accompany static states. Not animated under `prefers-reduced-motion`. |
| `status` | `"progress" \| "danger" \| "success" \| "warning" \| "info" \| undefined` | `'info'` | no | Semantic status — drives the color and the default icon. |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `variant` | `"fill" \| "text" \| undefined` | `'fill'` | no | Display mode: `fill` — a filled badge without an icon; `text` — a transparent background with a colored status icon. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Slot for the status text. |

---

# CdsSteps

_Category: Navigation · since 4.0.0_

_Tests: none yet — behavior is not covered by automated tests_

The stepper walks the user through a multi-step process: it shows which steps are done, which one is active and how many are left. It can switch the content of the steps and renders the "Back" / "Next" buttons out of the box, while a header without content works as a status tracker.

**See also:** The stepper shows the progress of a business process without step navigation on its own: without the `interactive` prop the steps are not clickable, and the header without `items` works as a status tracker — see the ["Request status"](#request-status) scenario. The CdsStages component, which used to solve the same task, is deprecated. For sections of equal weight that are switched in any order, use CdsTabs.

## Anatomy

The stepper consists of a header with the steps, a content area and the
navigation buttons — the last two appear when the steps are set through `items`.
Every step is a state indicator with a progress line up to the next step, a
title and a description.

## Variations

### Steps from an array

Pass an array of objects into `items` — the title, the description and the value
of a step are read by the `item-title`, `item-text` and `item-value` keys (by
default `title`, `text`, and the value is the ordinal number of the step
starting from one). The content of a step comes from the `item.{value}` slots or
from the shared `item` slot, and the "Back" / "Next" buttons are rendered
automatically: their texts are changed by the `prev-text` / `next-text` props,
and `hide-actions` hides the buttons.

**Example — `Default.vue`:**

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

const step = ref(1);
const items = [
  { title: 'ФИО', text: 'Имя и фамилия' },
  { title: 'Паспортные данные', text: 'Номер паспорта и дата рождения' },
  { title: 'Способ оплаты', text: 'Данные банковской карты' },
  { title: 'Подтверждение', text: 'Код из смс' }
];
</script>

<template>
  <div class="m-auto max-w-[750px]">
    <CdsSteps v-model="step" :items="items">
      <template v-for="(item, index) in items" :key="item.title" #[`item.${index+1}`]>
        <CdsCard :title="item.title" :text="`Контент шага «${item.title}»: ${item.text.toLowerCase()}.`" borderless />
      </template>
    </CdsSteps>
  </div>
</template>
```

### States

Steps can also be declared by hand — with `CdsStepsItem` components in the
default slot: only the header is rendered, the content and the navigation stay
up to you. A step has three states: `error` — finished with an error, `warning`
— needs attention, `disabled` — unavailable.

**Example — `States.vue`:**

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

const step = ref(1);
</script>

<template>
  <CdsSteps v-model="step">
    <CdsStepsItem title="ФИО" text="Имя и фамилия" />
    <CdsStepsItem title="Паспортные данные" error text="Номер паспорта и дата рождения" />
    <CdsStepsItem title="Способ оплаты" disabled text="Данные банковской карты" />
    <CdsStepsItem title="Подтверждение" warning text="Код из смс" />
  </CdsSteps>
</template>
```

### Interactive steps

The `interactive` prop allows jumping to any step by click or from the keyboard
— the progress animates in a cascade and `disabled` steps are skipped. The
`readonly` prop turns the transitions off while keeping the appearance.

**Example — `Interactive.vue`:**

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

const step = ref(2);
</script>

<template>
  <CdsSteps v-model="step" interactive>
    <CdsStepsItem title="ФИО" text="Имя и фамилия" />
    <CdsStepsItem title="Паспортные данные" text="Номер паспорта и дата рождения" />
    <CdsStepsItem title="Способ оплаты" text="Данные банковской карты" />
    <CdsStepsItem title="Подтверждение" text="Код из смс" />
  </CdsSteps>
</template>
```

### Vertical layout

The `vertical` prop turns the header into a column — a good fit for status
trackers and narrow panels.

**Example — `Vertical.vue`:**

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

const step = ref(0);
</script>

<template>
  <div class="flex h-[350px] w-full items-center justify-center">
    <CdsSteps v-model="step" vertical interactive>
      <CdsStepsItem title="ФИО" text="Имя и фамилия" />
      <CdsStepsItem title="Паспортные данные" text="Номер паспорта и дата рождения" />
      <CdsStepsItem title="Способ оплаты" text="Данные банковской карты" />
      <CdsStepsItem title="Подтверждение" text="Код из смс" />
    </CdsSteps>
  </div>
</template>
```

### Slots

Slots give control over every area of the stepper:

| Slot                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `default`                            | Your own `CdsStepsItem` when `items` is not set                    |
| `title`, `text`                      | Title and description of every step                                |
| `header-item`, `header-item.{value}` | Full replacement of the step content in the header                 |
| `item`, `item.{value}`               | Step content in the content area                                   |
| `actions`                            | Your own navigation buttons (receives the `prev` / `next` methods) |
| `prev`, `next`                       | Replacement of a single button inside the default navigation block |

The `title` and `text` slots receive the state of the step (`selected`,
`complete`, `error`, `first`, `last`…) — handy for adding tags and hints.

**Example — `Slots.vue`:**

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

const step = ref(3);
const items = [
  { title: 'ФИО', text: 'Имя и фамилия' },
  { title: 'Паспортные данные', text: 'Номер паспорта и дата рождения', error: true },
  { title: 'Способ оплаты', text: 'Данные банковской карты', disabled: true },
  { title: 'Подтверждение', text: 'Код из смс' }
];
</script>

<template>
  <CdsSteps v-model="step">
    <CdsStepsItem v-for="item in items" :key="item.title" :disabled="item.disabled" :error="item.error">
      <template #title>
        <span class="inline-flex items-center gap-1">
          {{ item.title }}
          <CdsTag v-if="!item.disabled" text="Доступ" />
        </span>
      </template>
      <template #text="{ last }">
        <span class="inline-flex items-center gap-1">
          <CdsTooltip v-if="last">
            <template #activator="{ props }">
              <CdsIcon icon="info" v-bind="props" />
            </template>
            Push уведомления
          </CdsTooltip>
          {{ item.text }}
        </span>
      </template>
    </CdsStepsItem>
  </CdsSteps>
</template>
```

### Model

The active step is controlled through `v-model`. For steps from `items` the
default value is the ordinal number starting from one; for steps declared by
hand it is the index starting from zero. Your own value is set by the
`item-value` key or by the `value` prop of `CdsStepsItem`. The `prev` / `next`
methods are available through the component ref.

**Example — `Model.vue`:**

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

const step = ref(2);
const items = [
  { title: 'ФИО', text: 'Имя и фамилия' },
  { title: 'Паспортные данные', text: 'Номер паспорта и дата рождения' },
  { title: 'Способ оплаты', text: 'Данные банковской карты' },
  { title: 'Подтверждение', text: 'Код из смс' }
];
const next = () => {
  if (step.value < items.length - 1) step.value++;
};
const prev = () => {
  if (step.value > 0) step.value--;
};
</script>

<template>
  <div>
    <div class="mb-4 flex w-full items-center justify-center gap-2">
      <CdsFunctionalButton icon="chevron-left" @click="prev" />
      v-model: {{ step }}
      <CdsFunctionalButton icon="chevron-right" @click="next" />
    </div>
    <CdsSteps v-model="step">
      <CdsStepsItem v-for="item in items" :key="item.title" :title="item.title" :text="item.text" />
    </CdsSteps>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The step title is a short name of the stage; the details go into the text description. | Sentence-long titles inflate the header and are hard to scan. |
| Three to five steps: the process stays graspable and every step is a meaningful stage. | Seven steps or more scare the user with their volume — merge the adjacent stages. |
| The description adds to the title: what the step needs or what will happen. | A description that repeats the title adds nothing — drop it. |

## Scenarios

### Checkout wizard

A classic wizard: every step gets its own `item.{value}` slot with a form. The
built-in buttons page through the steps, and the fields are bound to shared
state through `v-model`, so the data survives the transitions.

**Example — `Checkout.vue`:**

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

const step = ref(1);
const city = ref('');
const address = ref('');
const payment = ref('card');

const items = [
  { title: 'Доставка', text: 'Город и адрес' },
  { title: 'Оплата', text: 'Способ оплаты' },
  { title: 'Проверка', text: 'Данные заказа' }
];
</script>

<template>
  <div class="m-auto max-w-[750px]">
    <CdsSteps v-model="step" :items="items">
      <template #[`item.1`]>
        <CdsForm class="m-auto flex w-[350px] flex-col gap-2 py-2">
          <CdsTextInput v-model="city" label="Город" placeholder="Москва" />
          <CdsTextInput v-model="address" label="Адрес" placeholder="Улица, дом, офис" />
        </CdsForm>
      </template>

      <template #[`item.2`]>
        <CdsRadioGroup v-model="payment" label="Как оплатите заказ?" class="m-auto w-[350px] py-2" hide-details>
          <CdsRadio value="card" label="Банковской картой" />
          <CdsRadio value="invoice" label="Счётом на компанию" />
        </CdsRadioGroup>
      </template>

      <template #[`item.3`]>
        <div class="m-auto flex w-[350px] flex-col gap-1 py-2">
          <p>Доставка: {{ [city, address].filter(Boolean).join(', ') || 'не указана' }}</p>
          <p>Оплата: {{ payment === 'card' ? 'банковской картой' : 'счётом на компанию' }}</p>
        </div>
      </template>
    </CdsSteps>
  </div>
</template>
```

### Confirmation before moving on

The `actions` slot replaces the built-in buttons and receives the `prev` and
`next` methods — you define the conditions of the transition yourself. Here the
"Next" button stays disabled until the user accepts the terms of service.

**Example — `Confirmation.vue`:**

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

const step = ref(1);
const agreed = ref(false);

const items = [
  { title: 'Условия', text: 'Договор оферты' },
  { title: 'Данные', text: 'Реквизиты компании' },
  { title: 'Готово', text: 'Заявка отправлена' }
];
</script>

<template>
  <div class="m-auto max-w-[750px]">
    <CdsSteps v-model="step" :items="items">
      <template #[`item.1`]>
        <div class="m-auto flex w-[350px] flex-col gap-2 py-2">
          <p>Перед заполнением заявки ознакомьтесь с условиями обслуживания.</p>
          <CdsCheckbox v-model="agreed" label="Принимаю условия обслуживания" hide-details />
        </div>
      </template>

      <template #[`item.2`]>
        <p class="py-2 text-center">Здесь будет форма с реквизитами компании.</p>
      </template>

      <template #[`item.3`]>
        <p class="py-2 text-center">Заявка отправлена — подтверждение придёт на почту.</p>
      </template>

      <template #actions="{ prev, next }">
        <div class="flex items-center justify-between">
          <CdsButton variant="soft" color="brand" text="Назад" :disabled="step === 1" @click="prev" />
          <CdsButton text="Далее" :disabled="step === 3 || (step === 1 && !agreed)" @click="next" />
        </div>
      </template>
    </CdsSteps>
  </div>
</template>
```

### Request status

A header without `items` works as a process tracker: only the steps, no content
and no buttons. The completed stages are marked with indicators, and the
descriptions carry the dates and the deadlines. The `vertical` prop lays the
history out in a column.

**Example — `StatusTracker.vue`:**

```vue
<script setup lang="ts">
import { CdsSteps, CdsStepsItem } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsSteps :model-value="2" vertical>
      <CdsStepsItem title="Заявка отправлена" text="12 марта, 10:24" />
      <CdsStepsItem title="Документы проверены" text="13 марта, 16:02" />
      <CdsStepsItem title="Согласование" text="Обычно занимает до двух дней" />
      <CdsStepsItem title="Заключение договора" />
    </CdsSteps>
  </div>
</template>
```

## API

### CdsSteps

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `hideActions` | `boolean \| undefined` | — | no | Hides the step navigation buttons |
| `interactive` | `boolean \| undefined` | — | no | Allows jumping to a step by click |
| `itemProps` | `SelectItemKey` | `'props'` | no | Object field that holds the props of the item, or a function that returns them |
| `items` | `any[] \| undefined` | `[]` | no | Array of items to display |
| `itemText` | `SelectItemKey` | `'text'` | no | Key of the step description in an items element object |
| `itemTitle` | `SelectItemKey` | `'title'` | no | Object field used as the item title, or a function that returns it |
| `itemValue` | `SelectItemKey` | `'value'` | no | Object field used as the item value, or a function that returns it |
| `mandatory` | `boolean \| "force" \| undefined` | `'force'` | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `nextText` | `string \| undefined` | `'$cds.steps.next'` | no | Text of the next step button |
| `prevText` | `string \| undefined` | `'$cds.steps.prev'` | no | Text of the previous step button |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `required` | `boolean \| "force" \| undefined` | `'force'` | no | Requires at least one item to stay selected |
| `selectedClass` | `string \| undefined` | `'cds-steps-item--current'` | no | CSS class applied in the selected state |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `vertical` | `boolean \| undefined` | — | no | Vertical layout |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: unknown]` | Fired when the v-model value changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `CdsStepsSlot` | Custom navigation buttons |
| `default` | `CdsStepsSlot` | Header content: custom CdsStepsItem (used when items is not set) |
| `header-item` | `CdsStepsItemSlot` | Custom rendering of every step content in the header |
| `item` | `CdsStepsInternalItem` | Step content in the content area |
| `next` | `CdsStepsActionsSlot` | Custom next step button |
| `prev` | `CdsStepsActionsSlot` | Custom previous step button |
| `text` | `CdsStepsItemSlot` | Custom description of every step |
| `title` | `CdsStepsItemSlot` | Custom title of every step |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `next` | `() => void` | Moves to the next step. |
| `prev` | `() => void` | Moves to the previous step. |

### CdsStepsActions

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| "next" \| "prev" \| undefined` | `false` | no | Disables the navigation buttons: both or a specific one |
| `nextText` | `string \| undefined` | `'$cds.steps.next'` | no | Text of the next step button |
| `prevText` | `string \| undefined` | `'$cds.steps.prev'` | no | Text of the previous step button |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:next` | `[]` | Click on the next step button |
| `click:prev` | `[]` | Click on the previous step button |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `next` | `CdsStepsActionsSlot` | Custom next step button |
| `prev` | `CdsStepsActionsSlot` | Custom previous step button |

### CdsStepsItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | The step finished with an error |
| `interactive` | `boolean \| undefined` | — | no | Allows jumping to a step by click |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `text` | `string \| undefined` | — | no | Step description |
| `title` | `string \| undefined` | — | no | Step title |
| `value` | `any` | — | no | Value of the component within the group |
| `warning` | `boolean \| undefined` | — | no | The step needs attention |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `group:selected` | `[value: { value: boolean; }]` | Fired when the selected state of the step inside the group changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `CdsStepsItemSlot` | Extra step content after the title and the description |
| `text` | `CdsStepsItemSlot` | Custom step description |
| `title` | `CdsStepsItemSlot` | Custom step title |

### CdsStepsView

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `crossfade` | `boolean \| undefined` | — | no | Slides change with a smooth crossfade instead of a shift |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `reverse` | `boolean \| undefined` | — | no | Inverts the direction of the transition animation between slides |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transitionDuration` | `number \| undefined` | — | no | Duration of the transition animation between slides, in milliseconds |
| `verticalArrows` | `boolean \| "left" \| "right" \| undefined` | — | no | Places the navigation arrows vertically: `'left'` or `'right'` — the side, `true` — the default side |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: any]` | Fired when the v-model value changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `additional` | `{ group: GroupProvide; }` | Extra content above the slides — indicator dots or your own navigation, for example |
| `default` | `{ group: GroupProvide; }` | Slides. The slot props carry the group state for controlling the active slide |
| `next` | `{ props: ControlProps; }` | Button that moves to the next slide. The slot props are ready to bind to your own button |
| `prev` | `{ props: ControlProps; }` | Button that moves to the previous slide. The slot props are ready to bind to your own button |

### CdsStepsViewItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `reverseTransition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the reverse direction. A transition component name, or `false` to turn the animation off |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `transition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the forward direction. A transition component name, or `false` to turn the animation off |
| `value` | `any` | — | no | Value of the component within the group |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the slide |

---

# CdsSurface

_Category: Atoms · since 4.0.0 · status: new_

_Tests: API 12/12 · 12 unit · lines 100% (v4.0.0-alpha.13) · a11y: 1 axe recommendation (v4.0.0-alpha.11)_

A surface is a container with a background from the tokens, sizes, positioning and a theme of its own. Take it when a block needs a design system background rather than a ready-made component: the backdrop of a panel, a plate, the base of your own component.

**See also:** For a card with a title and actions take CdsCard, for the sections of a page take CdsLayout. `CdsSurface` is the lowest layer, without content or paddings of its own.

## Variations

### Color

The `color` prop sets the background from the theme tokens and picks a
contrasting text color. Besides `surface-*`, any color of the palette and any
CSS color will do. Which colors exactly hide behind the tokens is decided by the
theme: the `theme` prop switches it for the surface and for everything inside
it.

**Example — `Colors.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsSurface color="surface-primary" class="p-3 rounded-200">surface-primary</CdsSurface>
    <CdsSurface color="surface-secondary" class="p-3 rounded-200">surface-secondary</CdsSurface>
    <CdsSurface color="surface-elevated" class="p-3 rounded-200">surface-elevated</CdsSurface>
    <CdsSurface color="surface-inverse" class="p-3 rounded-200">surface-inverse</CdsSurface>
  </div>
</template>
```

### Sizes

The `width`, `height`, `min-width`, `max-width`, `min-height` and `max-height`
props accept a number (pixels) or a string with any CSS unit.

**Example — `Dimensions.vue`:**

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

<template>
  <div class="flex flex-wrap items-start justify-center gap-2">
    <CdsSurface color="surface-secondary" width="120" height="80" class="p-2 rounded-200"> 120 × 80 </CdsSurface>

    <CdsSurface color="surface-secondary" min-height="80" max-width="200" class="p-2 rounded-200">
      Ширина не больше 200, высота не меньше 80
    </CdsSurface>
  </div>
</template>
```

### Positioning

The `position` prop sets the CSS position, `location` pins the surface to an
edge of the container — `top end`, `bottom start`, `center`. Together they build
a plate on top of another block.

**Example — `Position.vue`:**

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

<template>
  <CdsSurface color="surface-secondary" position="relative" height="140" class="w-[280px] m-auto rounded-200">
    <CdsSurface color="surface-inverse" position="absolute" location="top end" class="p-1 rounded-100">
      top end
    </CdsSurface>

    <CdsSurface color="surface-inverse" position="absolute" location="bottom start" class="p-1 rounded-100">
      bottom start
    </CdsSurface>
  </CdsSurface>
</template>
```

## Scenarios

### A summary panel

The surface gives the background and the sizes, while the paddings and the
layout inside are up to you. The `tag` prop changes the tag of the wrapper —
here it is `section`, so the block stays meaningful in the structure of the
page.

**Example — `SummaryPanel.vue`:**

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

const rows = [
  { label: 'Позиций', value: '12' },
  { label: 'Доставка', value: '1 500 ₽' },
  { label: 'Итого', value: '48 900 ₽' }
];
</script>

<template>
  <CdsSurface tag="section" color="surface-secondary" class="w-[320px] m-auto p-4 rounded-200">
    <div class="flex flex-col gap-1">
      <div v-for="row of rows" :key="row.label" class="flex justify-between">
        <span>{{ row.label }}</span>
        <b>{{ row.value }}</b>
      </div>
    </div>

    <CdsDivider class="my-3" />

    <CdsButton block text="Оформить заказ" />
  </CdsSurface>
</template>
```

## API

### CdsSurface

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `color` | `string \| undefined` | — | no | Background color of the surface |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `location` | `Anchor \| null \| undefined` | — | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | The main content of the surface. |

---

# CdsTable

_Category: Content · since 4.0.0_

_Tests: API 0/72 · 13 unit · lines 15.2% (v4.0.0-alpha.13) · a11y: 50 axe recommendations (v4.0.0-alpha.11)_

A table shows large sets of records in columns and takes the data work off your hands: sorting, filters, pagination, row selection and expansion, a pinned header and pinned columns. Columns are described by the `columns` prop, the records by the `data` prop.

**See also:** For a plain list of similar items without columns, use CdsList; for a hierarchy without tabular data, use CdsTree.

## Anatomy

Around the table there are the `header`, `toolbar` and `footer` slots and
built-in pagination (the `pagination` prop). The table itself consists of a
column header and rows with cells.

## Variations

### Showing data

A minimal table: an array of column descriptions in `columns`, the records in
`data`. The row key comes from the record's `key` field or from the `row-key`
prop.

**Example — `Default.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TSimpleRow = {
  key: string;
  name: string;
  age: string;
  address: string;
  phone: string;
};

const simpleColumns: NTable.NColumn.TColumns<TSimpleRow> = [
  { title: 'Заголовок', dataIndex: 'name' },
  { title: 'Заголовок', dataIndex: 'age' },
  { title: 'Заголовок', dataIndex: 'address' },
  { title: 'Заголовок', dataIndex: 'phone' }
];

const makeSimpleData = (count: number): TSimpleRow[] =>
  [...Array(count)].map((_, i) => ({
    key: i.toString(),
    name: 'Текст ячейки',
    age: 'Текст ячейки',
    address: 'Текст ячейки',
    phone: 'Текст ячейки'
  }));

const columns = simpleColumns;
const data = makeSimpleData(5);
</script>

<template>
  <CdsTable :columns="columns" :data="data" />
</template>
```

The column's `align` property aligns the content — numeric values are
conventionally aligned to the right.

**Example — `Basic.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: string; name: string; price: string; address: string; tags: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Наименование', dataIndex: 'name', key: 'name' },
  { title: 'Цена', dataIndex: 'price', key: 'price', align: 'right' },
  { title: 'Адрес', dataIndex: 'address', key: 'address' },
  { title: 'Наличие', key: 'tags', dataIndex: 'tags' }
];
const data: TDataType[] = [
  { key: '1', name: 'iPhone 17 Pro Max', price: '$1500', address: 'г. Москва', tags: 'В наличии' },
  { key: '2', name: 'MacBook Air M5', price: '$2000', address: 'г. Москва', tags: 'В наличии' },
  { key: '3', name: 'Apple Vision Pro', price: '$3500', address: 'г. Нью-Йорк', tags: 'Нет в наличии' }
];
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false" />
</template>
```

### Sizes

The `size` prop controls the density: `md` is the default, `sm` and `xs` are for
data-dense screens.

**Example — `Size.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

const columns: NTable.NColumn.TColumns = [...Array(4)].map((_, i) => ({
  title: 'Заголовок',
  dataIndex: `header${i + 1}`,
  key: (i + 1).toString()
}));
const data = [...Array(4)].map((_, i) => ({
  key: (i + 1).toString(),
  header1: 'Текст ячейки',
  header2: 'Текст ячейки',
  header3: 'Текст ячейки',
  header4: 'Текст ячейки'
}));
</script>

<template>
  <div class="flex flex-col gap-5">
    <CdsTable :columns="columns" :data="data" size="md" :pagination="false">
      <template #header>
        <h4>Medium size</h4>
      </template>
    </CdsTable>

    <CdsTable :columns="columns" :data="data" size="sm" :pagination="false">
      <template #header>
        <h4>Small size</h4>
      </template>
    </CdsTable>

    <CdsTable :columns="columns" :data="data" size="xs" :pagination="false">
      <template #header>
        <h4>Extra small size</h4>
      </template>
    </CdsTable>
  </div>
</template>
```

### Rows

The `row-class-name` property computes a row class from the record: the built-in
`cds-table--striped` class alternates the background, `cds-table__row--warning`
and `cds-table__row--error` add a status highlight. The `hovered` prop
highlights the row under the cursor.

**Example — `Stripe.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TSimpleRow = {
  key: string;
  name: string;
  age: string;
  address: string;
  phone: string;
};

const simpleColumns: NTable.NColumn.TColumns<TSimpleRow> = [
  { title: 'Заголовок', dataIndex: 'name' },
  { title: 'Заголовок', dataIndex: 'age' },
  { title: 'Заголовок', dataIndex: 'address' },
  { title: 'Заголовок', dataIndex: 'phone' }
];

const makeSimpleData = (count: number): TSimpleRow[] =>
  [...Array(count)].map((_, i) => ({
    key: i.toString(),
    name: 'Текст ячейки',
    age: 'Текст ячейки',
    address: 'Текст ячейки',
    phone: 'Текст ячейки'
  }));

const columns = simpleColumns;
const data = makeSimpleData(4);
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :row-class-name="(_record: unknown, index: number) => (index % 2 === 1 ? 'cds-table--striped' : '')"
    :pagination="false"
    hovered
  />
</template>
```

**Example — `StateRow.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TSimpleRow = {
  key: string;
  name: string;
  age: string;
  address: string;
  phone: string;
};

const simpleColumns: NTable.NColumn.TColumns<TSimpleRow> = [
  { title: 'Заголовок', dataIndex: 'name' },
  { title: 'Заголовок', dataIndex: 'age' },
  { title: 'Заголовок', dataIndex: 'address' },
  { title: 'Заголовок', dataIndex: 'phone' }
];

const makeSimpleData = (count: number): TSimpleRow[] =>
  [...Array(count)].map((_, i) => ({
    key: i.toString(),
    name: 'Текст ячейки',
    age: 'Текст ячейки',
    address: 'Текст ячейки',
    phone: 'Текст ячейки'
  }));

const columns = simpleColumns;
const data = makeSimpleData(4);
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :row-class-name="(_record, index) => (index % 2 === 1 ? 'cds-table__row--warning' : 'cds-table__row--error')"
    :pagination="false"
    hovered
  />
</template>
```

### Cell content

The column's `ellipsis` property truncates long text to a single line with an
ellipsis — in cells and in headers alike.

**Example — `Ellipsis.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: string; name: string; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Заголовок таблицы', dataIndex: 'name', key: 'name' },
  { title: 'Заголовок таблицы', dataIndex: 'address', key: 'address 1', ellipsis: true },
  { title: 'Заголовок таблицы Заголовок таблицы', dataIndex: 'address', key: 'address 2', ellipsis: true },
  { title: 'Заголовок таблицы Заголовок таблицы', dataIndex: 'address', key: 'address 3', ellipsis: true },
  { title: 'Заголовок таблицы Заголовок таблицы', dataIndex: 'address', key: 'address 4', ellipsis: true }
];
const data: TDataType[] = [...Array(3)].map((_, i) => ({
  key: (i + 1).toString(),
  name: 'Текст ячейки',
  address: 'Текст ячейки Текст ячейки Текст ячейки Текст ячейки'
}));
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false" />
</template>
```

### Responsiveness

The column's `responsive` property lists the breakpoints at which the column is
visible — secondary columns get hidden on narrow screens.

**Example — `Responsive.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

const columns: NTable.NColumn.TColumns = [
  { title: 'Заголовок (all screens)', dataIndex: 'name', key: 'name' },
  { title: 'Заголовок (small screen or bigger)', dataIndex: 'age', key: 'age', responsive: ['smUp'] },
  { title: 'Заголовок (medium screen or bigger)', dataIndex: 'address', key: 'address', responsive: ['mdUp'] },
  {
    title: 'Заголовок (only md, sm, xs screen)',
    dataIndex: 'phone',
    key: 'phone',
    responsive: ['md', 'sm', 'xs']
  }
];
const data = [{ key: '1', name: 'Текст ячейки', age: 'Текст ячейки', address: 'Текст ячейки', phone: 'Текст ячейки' }];
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false" />
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| Numbers are aligned right — the digits line up and the amounts are easy to compare. | Numbers aligned left blend into the text, and you have to read closely to compare values. |
| Truncate long text with the column's ellipsis — rows keep the same height and the full text stays available in a tooltip. | Raw long text stretches the row and the table loses its rhythm. |
| Highlight only the rows that need attention with a status. | When nearly every row is highlighted, the signal stops working. |

## Documentation sections

- Structure and headers — header grouping,
  merged cells, the slots around the table, column widths and declarative
  column descriptions.
- Pinning and scrolling — pinning the header
  and columns while scrolling, horizontal scroll buttons.
- Filters and sorting — column filters,
  multiple sorting, resetting and a custom filter panel.
- Row selection — checkboxes, operations on
  the selected set, custom selection menu items.
- Expansion and trees — expandable rows,
  nested tables and tree data.
- Editing — editable cells, rows and the
  whole table.
- Drag and drop — dragging rows and
  columns.
- Scenarios — server-side data and
  ready-made recipes for product tables.

## Grouping headers

A nested `children` array on a column joins several columns under a shared
header — the header becomes multi-level.

**Example — `GroupingTableHead.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

const columns: NTable.NColumn.TColumns = [
  { title: 'Имя', dataIndex: 'name', key: 'name', width: 100, fixed: 'left' },
  {
    title: 'Информация',
    children: [
      { title: 'Возраст', dataIndex: 'age', key: 'age', width: 200 },
      {
        title: 'Адрес',
        children: [
          { title: 'Улица', dataIndex: 'street', key: 'street', width: 200 },
          {
            title: 'Дом',
            children: [
              { title: 'Корпус', dataIndex: 'building', key: 'building', width: 100 },
              { title: 'Квартира', dataIndex: 'number', key: 'number', width: 100 }
            ]
          }
        ]
      }
    ]
  },
  {
    title: 'Компания',
    children: [
      { title: 'Адрес компании', dataIndex: 'companyAddress', key: 'companyAddress', width: 200 },
      { title: 'Название компании', dataIndex: 'companyName', key: 'companyName' }
    ]
  },
  { title: 'Пол', dataIndex: 'gender', key: 'gender', width: 80, fixed: 'right' }
];

const data = [...Array(10)].map((_, i) => ({
  key: i,
  name: 'Иван',
  age: i + 1,
  street: 'Главная',
  building: 'Б',
  number: 1004,
  companyAddress: 'г. Москва, ул. Ленина',
  companyName: 'B2B-Center',
  gender: 'Муж'
}));
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false" :scroll="{ x: 'calc(700px + 50%)', y: 240 }" bordered />
</template>
```

## Merging cells

The column's `customCell` function returns `colSpan`/`rowSpan` for a specific
cell, while `colSpan` on the column itself merges header cells. A cell with
`colSpan: 0` is not rendered.

**Example — `ColspanAndRowspan.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: string; name: string; age: number; tel: string; phone: string; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  {
    title: 'Имя',
    dataIndex: 'name',
    customCell: (_, index) => ({ colSpan: index! < 4 ? 1 : 5 })
  },
  {
    title: 'Возраст',
    dataIndex: 'age',
    customCell: (_, index) => {
      if (index === 4) return { colSpan: 0 };
    }
  },
  {
    title: 'Номер телефона',
    colSpan: 2,
    dataIndex: 'tel',
    customCell: (_, index) => {
      if (index === 2) return { rowSpan: 2 };
      if (index === 3) return { rowSpan: 0 };
      if (index === 4) return { colSpan: 0 };
    }
  },
  {
    title: 'Номер домашнего телефона',
    colSpan: 0,
    dataIndex: 'phone',
    customCell: (_, index) => {
      if (index === 4) return { colSpan: 0 };
    }
  },
  {
    title: 'Адрес',
    dataIndex: 'address',
    customCell: (_, index) => {
      if (index === 4) return { colSpan: 0 };
    }
  }
];
const data: TDataType[] = [
  {
    key: '1',
    name: 'Иванов Иван',
    age: 20,
    tel: '79999999999',
    phone: '74959999999',
    address: 'г. Москва, ул. Ленина д. 1'
  },
  {
    key: '2',
    name: 'Иванов Василий',
    tel: '79999999999',
    phone: '74959999999',
    age: 32,
    address: 'г. Москва, ул. Ленина д. 2'
  },
  {
    key: '3',
    name: 'Иванов Кирилл',
    age: 41,
    tel: '79999999999',
    phone: '74959999999',
    address: 'г. Москва, ул. Ленина д. 3'
  },
  {
    key: '4',
    name: 'Иванов Александр',
    age: 30,
    tel: '79999999999',
    phone: '74959999999',
    address: 'г. Екатеринбург, ул. Ленина д. 4'
  },
  {
    key: '5',
    name: 'Иванов Иван',
    age: 18,
    tel: '79999999999',
    phone: '74959999999',
    address: 'г. Новосибирск, ул. Ленина д. 5'
  }
];
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false" />
</template>
```

## Header, toolbar and footer

The `header`, `toolbar` and `footer` slots add your own areas around the table,
and the `pagination` prop adds built-in pagination with a record counter and a
page size selector.

**Example — `HeaderFooter.vue`:**

```vue
<script setup lang="ts">
import type { ITableProps, NTable } from '@central-design-system/components';
import { CdsButton, CdsTab, CdsTable, CdsTabs, CdsTextInput } from '@central-design-system/components';
import { ref } from 'vue';

type TDataType = { key: number; name: string; money: string; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Название', dataIndex: 'name' },
  { title: 'Адрес', dataIndex: 'address' },
  { title: 'Цена', className: 'column-money', dataIndex: 'money', align: 'right' }
];
const data: TDataType[] = [...Array(100)].map((_, i) => ({
  key: i,
  name: `Позиция ${i + 1}`,
  money: new Intl.NumberFormat('ru-RU', { style: 'currency', currency: 'RUB' }).format((i + 1) * 10000),
  address: `г. Москва, ул. Ленина, д.${i}`
}));

const contentSwitcher = ref(0);
const total = ref(10);

const onChange: ITableProps<TDataType>['onChange'] = (pagination) => {
  total.value = pagination.total!;
};
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :pagination="{ total, counter: true, size: true, position: ['bottomLeft'] }"
    @change="onChange"
  >
    <template #header>
      <div class="flex justify-between">
        <div>
          <h4 class="mb-2">Заголовок таблицы</h4>
          <p class="mb-4 text-content-secondary">Описание таблицы в слоте заголовка таблицы</p>
          <div class="flex">
            <CdsTabs v-model="contentSwitcher">
              <CdsTab v-for="i in 5" :key="i">Текст</CdsTab>
            </CdsTabs>
          </div>
        </div>
        <div>
          <CdsButton variant="soft" color="brand" text="Внешнее действия" />
        </div>
      </div>
    </template>

    <template #toolbar>
      <div class="flex justify-between">
        <div class="flex gap-4">
          <CdsTextInput prepend-inner-icon="search" placeholder="Описание поиска" hide-messages class="w-[250px]" />
          <CdsButton prepend-icon="adjust" text="Фильтры" variant="soft" color="neutral" />
        </div>
        <div class="flex gap-2">
          <CdsButton variant="soft" color="brand" text="Отменить" />
          <CdsButton text="Действие" />
        </div>
      </div>
    </template>

    <template #footer>
      <div class="flex items-center justify-between">
        <h4>Подвал таблицы</h4>
        <div class="flex gap-2">
          <CdsButton variant="soft" color="brand" text="Отменить" />
          <CdsButton text="Действие" />
        </div>
      </div>
    </template>
  </CdsTable>
</template>
```

## Resizing columns

The column's `resizable` property enables dragging the header border. The new
width is reported by the `resize-column` event — store it in the column
description.

**Example — `ResizableColumn.vue`:**

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

type TDataType = { key: string; name: string; price: string; address: string; tags: string };

const columns = ref<NTable.NColumn.TColumns<TDataType>>([
  { title: 'Наименование', dataIndex: 'name', key: 'name', resizable: true, width: 150 },
  {
    title: 'Цена',
    dataIndex: 'price',
    key: 'price',
    align: 'right',
    resizable: true,
    width: 100,
    minWidth: 100,
    maxWidth: 200
  },
  { title: 'Адрес', dataIndex: 'address', key: 'address' },
  { title: 'Наличие', key: 'tags', dataIndex: 'tags' }
]);
const data: TDataType[] = [
  {
    key: '1',
    name: 'iPhone 17 Pro Max',
    price: '$1500',
    address: 'г. Москва, ул. Ленина, д. 1',
    tags: 'В наличии'
  },
  {
    key: '2',
    name: 'MacBook Air M5',
    price: '$2000',
    address: 'г. Москва, ул. Ленина, д. 1',
    tags: 'В наличии'
  },
  {
    key: '3',
    name: 'Apple Vision Pro',
    price: '$3500',
    address: 'г. Нью-Йорк, ул. Ленина, д. 1',
    tags: 'Нет в наличии'
  }
];

const handleResizeColumn = (width: number, column: NTable.NColumn.IColumn) => {
  column.width = width;
};
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false" @resize-column="handleResizeColumn" />
</template>
```

## Declarative column descriptions

Instead of the `columns` array, columns can be described in the template with
the `CdsTableColumn` and `CdsTableColumnGroup` components — handy when headers
and cells need their own markup.

**Example — `CustomizeStyles.vue`:**

```vue
<script setup lang="ts">
import { CdsStatus, CdsTable, CdsTableColumn, CdsTableColumnGroup, CdsToggle } from '@central-design-system/components';

type TDataType = {
  key: string;
  firstName: string;
  lastName: string;
  age: number;
  address: string;
  tags: string[];
};

const data: TDataType[] = [
  {
    key: '1',
    firstName: 'Иван',
    lastName: 'Иванов',
    age: 20,
    address: 'г. Москва, ул. Ленина, д. 1',
    tags: ['Senior', 'Developer']
  },
  {
    key: '2',
    firstName: 'Анатолий',
    lastName: 'Анатольев',
    age: 42,
    address: 'г. Москва, ул. Ленина, д. 2',
    tags: ['Junior', 'Developer']
  },
  {
    key: '3',
    firstName: 'Игнат',
    lastName: 'Игнатьев',
    age: 33,
    address: 'г. Москва, ул. Ленина, д. 3',
    tags: ['Junior', 'Developer']
  },
  {
    key: '4',
    firstName: 'Петр',
    lastName: 'Петров',
    age: 28,
    address: 'г. Москва, ул. Ленина, д. 4',
    tags: ['Middle', 'Developer']
  }
];
</script>

<template>
  <CdsTable :data="data" :pagination="false">
    <CdsTableColumnGroup>
      <template #title>
        <span class="text-brand-primary">Сотрудник</span>
      </template>
      <CdsTableColumn key="firstName" data-index="firstName">
        <template #title>
          <span class="text-brand-primary">Имя</span>
        </template>
      </CdsTableColumn>
      <CdsTableColumn key="lastName" title="Фамилия" data-index="lastName" />
    </CdsTableColumnGroup>
    <CdsTableColumn key="age" title="Возраст" data-index="age" />
    <CdsTableColumn key="address" title="Адрес" data-index="address" />
    <CdsTableColumn key="tags" title="Особенности" data-index="tags">
      <template #default="{ text: tags }">
        <CdsStatus
          v-for="tag in tags"
          :key="tag"
          :status="tag === 'Junior' ? 'danger' : tag === 'developer' ? 'info' : 'success'"
          class="mr-2"
        >
          {{ tag }}
        </CdsStatus>
      </template>
    </CdsTableColumn>
    <CdsTableColumn key="action" title="Действия" data-index="action">
      <template #default="{ record }">
        <CdsToggle :disabled="!record.tags.includes('Junior')" hide-messages />
      </template>
    </CdsTableColumn>
  </CdsTable>
</template>
```

## Fixed header

The `scroll.y` property limits the height of the table body — the column header
stays in place while you scroll vertically.

**Example — `FixedHeader.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: number; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Имя', dataIndex: 'name', width: 150 },
  { title: 'Возраст', dataIndex: 'age', width: 150 },
  { title: 'Адрес', dataIndex: 'address' }
];

const data: TDataType[] = [...Array(100)].map((_, i) => ({
  key: i,
  name: `Иван Иванов ${i}`,
  age: 27,
  address: `г. Москва, ул. Ленина, д. ${i}`
}));
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="{ total: 50 }" :scroll="{ y: 245 }" />
</template>
```

## Fixed columns

The column's `fixed: 'left' | 'right'` property pins it during horizontal
scrolling. Set `scroll.x` wider than the container so that scrolling appears.

**Example — `FixedColumns.vue`:**

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

type TDataType = { key: string; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Имя', dataIndex: 'name', key: 'name', fixed: 'left', width: 100 },
  { title: 'Возраст', dataIndex: 'age', key: 'age', fixed: 'left', width: 100 },
  { title: 'Заголовок 1', dataIndex: 'address', key: '1' },
  { title: 'Заголовок 2', dataIndex: 'address', key: '2' },
  { title: 'Заголовок 3', dataIndex: 'address', key: '3' },
  { title: 'Заголовок 4', dataIndex: 'address', key: '4' },
  { title: 'Заголовок 5', dataIndex: 'address', key: '5' },
  { title: 'Заголовок 6', dataIndex: 'address', key: '6' },
  { title: 'Заголовок 7', dataIndex: 'address', key: '7' },
  { title: 'Заголовок 8', dataIndex: 'address', key: '8' },
  { title: 'Действия', key: 'actions', fixed: 'right', width: 100 }
];

const data: TDataType[] = [
  { key: '1', name: 'Иван', age: 32, address: 'г. Москва' },
  { key: '2', name: 'Петр', age: 40, address: 'г. Пермь' },
  { key: '3', name: 'Вадим', age: 32, address: 'г. Москва' },
  { key: '4', name: 'Евгений', age: 40, address: 'г. Балашиха' }
];
</script>

<template>
  <CdsTable :columns="columns" :data="data" :scroll="{ x: 1300, y: 1000 }" :pagination="{ total: 2 }">
    <template #bodyCell="{ column }">
      <template v-if="column.key === 'actions'">
        <CdsButton size="sm" variant="soft" color="brand">Удалить</CdsButton>
      </template>
    </template>
  </CdsTable>
</template>
```

## Fixed columns and header

Together, `scroll.x` and `scroll.y` pin both the columns and the header — the
center of the table scrolls in both directions.

**Example — `FixedColumnsAndHeader.vue`:**

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

type TDataType = { key: number; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Имя', dataIndex: 'name', key: 'name', fixed: 'left', width: 100 },
  { title: 'Возраст', dataIndex: 'age', key: 'age', fixed: 'left', width: 100 },
  { title: 'Заголовок 1', dataIndex: 'address', key: '1', width: 150 },
  { title: 'Заголовок 2', dataIndex: 'address', key: '2', width: 150 },
  { title: 'Заголовок 3', dataIndex: 'address', key: '3', width: 150 },
  { title: 'Заголовок 4', dataIndex: 'address', key: '4', width: 150 },
  { title: 'Заголовок 5', dataIndex: 'address', key: '5', width: 150 },
  { title: 'Заголовок 6', dataIndex: 'address', key: '6', width: 150 },
  { title: 'Заголовок 7', dataIndex: 'address', key: '7', width: 150 },
  { title: 'Заголовок 8', dataIndex: 'address', key: '8', width: 150 },
  { title: 'Действия', key: 'actions', fixed: 'right', width: 100 }
];

const data: TDataType[] = [...Array(10)].map((_, i) => ({
  key: i,
  name: `Иван ${i}`,
  age: 24,
  address: `ул. Главная, д. ${i}`
}));
</script>

<template>
  <CdsTable :columns="columns" :data="data" :scroll="{ x: 1500, y: 300 }" :pagination="false">
    <template #bodyCell="{ column }">
      <template v-if="column.key === 'actions'">
        <CdsButton size="sm" variant="soft" color="brand">Удалить</CdsButton>
      </template>
    </template>
  </CdsTable>
</template>
```

## Scroll buttons

A table with horizontal scrolling can get scroll buttons: take the DOM node of
the table body (`.cds-table__body`) through the component `ref` and change its
`scrollLeft` on click.

**Example — `ScrollButtons.vue`:**

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

type TDataType = { key: string; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Имя', dataIndex: 'name', key: 'name', fixed: 'left', width: 100 },
  { title: 'Возраст', dataIndex: 'age', key: 'age', fixed: 'left', width: 100 },
  { title: 'Заголовок 1', dataIndex: 'address', key: '1' },
  { title: 'Заголовок 2', dataIndex: 'address', key: '2' },
  { title: 'Заголовок 3', dataIndex: 'address', key: '3' },
  { title: 'Заголовок 4', dataIndex: 'address', key: '4' },
  { title: 'Заголовок 5', dataIndex: 'address', key: '5' },
  { title: 'Заголовок 6', dataIndex: 'address', key: '6' },
  { title: 'Заголовок 7', dataIndex: 'address', key: '7' },
  { title: 'Заголовок 8', dataIndex: 'address', key: '8' },
  { title: 'Заголовок 9', dataIndex: 'address', key: '9' },
  { title: 'Заголовок 10', dataIndex: 'address', key: '10' },
  { title: 'Действия', key: 'actions', fixed: 'right', width: 100 }
];

const data: TDataType[] = [
  { key: '1', name: 'Иван', age: 32, address: 'г. Москва' },
  { key: '2', name: 'Петр', age: 40, address: 'г. Москва' }
];

// Функционал для реализации кнопок скролла
const scrollStep = 50;
const tableRef = ref<InstanceType<typeof CdsTable> | null>(null);

function handleClickScrollButton(_event: MouseEvent, isLeft: boolean) {
  const tableBody = unref(tableRef)?.$el.querySelector('.cds-table__body');

  if (tableBody) {
    tableBody.scrollLeft += isLeft ? -scrollStep : scrollStep;
  }
}
</script>

<template>
  <CdsTable ref="tableRef" :columns="columns" :data="data" :scroll="{ x: 1300, y: 1000 }" :pagination="false">
    <template #header>
      <div class="flex justify-between">
        <div>
          <h4 class="mb-2">Заголовок таблицы</h4>
          <p class="text-content-secondary">Описание таблицы в слоте заголовка таблицы</p>
        </div>
        <div>
          <CdsButton text="Действие" />
        </div>
      </div>
    </template>
    <template #toolbar>
      <div class="flex justify-end">
        <div class="flex gap-2">
          <CdsButton
            icon="chevron-left"
            variant="soft"
            color="neutral"
            @click="(e) => handleClickScrollButton(e, true)"
          />
          <CdsButton
            icon="chevron-right"
            variant="soft"
            color="neutral"
            @click="(e) => handleClickScrollButton(e, false)"
          />
        </div>
      </div>
    </template>

    <template #bodyCell="{ column }">
      <template v-if="column.key === 'actions'">
        <CdsButton variant="soft" color="brand" size="sm">Удалить</CdsButton>
      </template>
    </template>

    <template #footer>
      <div class="flex justify-end gap-2">
        <CdsButton
          icon="chevron-left"
          variant="soft"
          color="neutral"
          @click="(e) => handleClickScrollButton(e, true)"
        />
        <CdsButton
          icon="chevron-right"
          variant="soft"
          color="neutral"
          @click="(e) => handleClickScrollButton(e, false)"
        />
      </div>
    </template>
  </CdsTable>
</template>
```

## Filters and sorting

The column filter menu is set by `filters` and `onFilter`, the sorting by the
`sorter` function. `sortDirections` lists the directions, `defaultSortOrder`
sets the initial order, and `filterMultiple: false` switches the filter to
single choice. Every change is reported by the `change` event.

**Example — `FilterAndSorter.vue`:**

```vue
<script setup lang="ts">
import type { ITableProps, NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: string; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  {
    title: 'Имя',
    dataIndex: 'name',
    filters: [
      { text: 'Иван', value: 'Иван' },
      { text: 'Петр', value: 'Петр' },
      {
        text: 'Фамилии',
        value: 'Submenu',
        children: [
          { text: 'Иванов', value: 'Иван Иванов' },
          { text: 'Петров', value: 'Петр Петров' }
        ]
      }
    ],
    onFilter: (value, record: TDataType) => record.name.indexOf(value as string) === 0,
    sorter: (a: TDataType, b: TDataType) => a.name.length - b.name.length,
    sortDirections: ['descend']
  },
  {
    title: 'Возраст',
    dataIndex: 'age',
    defaultSortOrder: 'descend',
    sorter: (a: TDataType, b: TDataType) => a.age - b.age
  },
  {
    title: 'Адрес',
    dataIndex: 'address',
    filters: [
      { text: 'Москва', value: 'Москва' },
      { text: 'Санкт-Петербург', value: 'Санкт-Петербург' }
    ],
    filterMultiple: false,
    onFilter: (value, record: TDataType) => record.address.indexOf(value as string) === 0,
    sorter: (a: TDataType, b: TDataType) => a.address.length - b.address.length,
    sortDirections: ['descend', 'ascend']
  }
];

const data: TDataType[] = [
  { key: '1', name: 'Иван Иванов', age: 40, address: 'Москва, ул. Ленина, д. 1' },
  { key: '2', name: 'Петр Петров', age: 42, address: 'Санкт-Петербург, ул. Ленина, д. 1' },
  { key: '3', name: 'Иван Иванов', age: 18, address: 'Санкт-Петербург, ул. Ленина, д. 2' },
  { key: '4', name: 'Петр Петров', age: 28, address: 'Москва, ул. Ленина, д. 2' }
];

const onChange: ITableProps<TDataType>['onChange'] = (pagination, filters, sorter) => {
  console.log('onChange', pagination, filters, sorter);
};
</script>

<template>
  <CdsTable :columns="columns" :data="data" @change="onChange" />
</template>
```

## Multiple sorting

A `sorter` object with a `multiple` field allows sorting by several columns at
once — the number sets the column's priority in the chain.

**Example — `MultipleSorter.vue`:**

```vue
<script setup lang="ts">
import type { ITableProps, NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: string; product: string; usd: number; eur: number; rub: number };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Продукт', dataIndex: 'product' },
  {
    title: 'Цена USD',
    dataIndex: 'usd',
    sorter: { compare: (a, b) => a.usd - b.usd, multiple: 3 }
  },
  {
    title: 'Цена EUR',
    dataIndex: 'eur',
    sorter: { compare: (a, b) => a.eur - b.eur, multiple: 2 }
  },
  {
    title: 'Цена RUB',
    dataIndex: 'rub',
    sorter: { compare: (a, b) => a.rub - b.rub, multiple: 1 }
  }
];

const data: TDataType[] = [
  { key: '1', product: 'Позиция 1', usd: 100, eur: 92, rub: 9100 },
  { key: '2', product: 'Позиция 2', usd: 50, eur: 46, rub: 4530 },
  { key: '3', product: 'Позиция 3', usd: 150, eur: 138, rub: 13590 },
  { key: '4', product: 'Позиция 4', usd: 25, eur: 23, rub: 2265 }
];

const onChange: ITableProps['onChange'] = (pagination, filters, sorter, extra) => {
  console.log('params', pagination, filters, sorter, extra);
};
</script>

<template>
  <CdsTable :columns="columns" :data="data" @change="onChange" />
</template>
```

## Resetting filters and sorting

The `filteredValue` and `sortOrder` column props make the state controlled:
keep it outside, update it in the `change` handler — and reset it with buttons
in a single assignment.

**Example — `ResetFiltersAndSorters.vue`:**

```vue
<script setup lang="ts">
import type { ITableProps, NTable } from '@central-design-system/components';
import { CdsButton, CdsTable } from '@central-design-system/components';
import { computed, ref } from 'vue';

type TDataItem = { key: string; name: string; age: number; address: string };

const filteredInfo = ref();
const sortedInfo = ref();

const columns = computed<NTable.NColumn.TColumns<TDataItem>>(() => {
  const filtered = filteredInfo.value || {};
  const sorted = sortedInfo.value || {};

  return [
    {
      title: 'Имя',
      dataIndex: 'name',
      key: 'name',
      filters: [
        { text: 'Иван', value: 'Иван' },
        { text: 'Петр', value: 'Петр' }
      ],
      filteredValue: filtered.name || null,
      onFilter: (value, record: TDataItem) => record.name.includes(value as string),
      sorter: (a: TDataItem, b: TDataItem) => a.name.length - b.name.length,
      sortOrder: sorted.columnKey === 'name' && sorted.order,
      ellipsis: true
    },
    {
      title: 'Возраст',
      dataIndex: 'age',
      key: 'age',
      sorter: (a: TDataItem, b: TDataItem) => a.age - b.age,
      sortOrder: sorted.columnKey === 'age' && sorted.order
    },
    {
      title: 'Адрес',
      dataIndex: 'address',
      key: 'address',
      filters: [
        { text: 'Москва', value: 'Москва' },
        { text: 'Санкт-Петербург', value: 'Санкт-Петербург' }
      ],
      filteredValue: filtered.address || null,
      onFilter: (value, record: TDataItem) => record.address.includes(value as string),
      sorter: (a: TDataItem, b: TDataItem) => a.address.length - b.address.length,
      sortOrder: sorted.columnKey === 'address' && sorted.order,
      ellipsis: true
    }
  ] as NTable.NColumn.TColumns<TDataItem>;
});

const data: TDataItem[] = [
  { key: '1', name: 'Иван Иванов', age: 40, address: 'Москва, ул. Ленина, д. 1' },
  { key: '2', name: 'Петр Петров', age: 42, address: 'Санкт-Петербург, ул. Ленина, д. 1' },
  { key: '3', name: 'Иван Иванов', age: 18, address: 'Санкт-Петербург, ул. Ленина, д. 2' },
  { key: '4', name: 'Петр Петров', age: 28, address: 'Москва, ул. Ленина, д. 2' }
];

const handleChange: ITableProps['onChange'] = (pagination, filters, sorter) => {
  filteredInfo.value = filters;
  sortedInfo.value = sorter;
};

const clearFilters = () => {
  filteredInfo.value = null;
};

const clearAll = () => {
  filteredInfo.value = null;
  sortedInfo.value = null;
};

const setAgeSort = () => {
  sortedInfo.value = { order: 'descend', columnKey: 'age' };
};
</script>

<template>
  <CdsTable :columns="columns" :data="data" @change="handleChange">
    <template #toolbar>
      <div class="flex justify-end gap-2">
        <CdsButton variant="soft" color="brand" @click="clearFilters">Очистить фильтры</CdsButton>
        <CdsButton variant="soft" color="brand" @click="clearAll">Очистить фильтры и сортировки</CdsButton>
        <CdsButton variant="solid" color="brand" @click="setAgeSort">Сортировать возраст</CdsButton>
      </div>
    </template>
  </CdsTable>
</template>
```

## Custom filter panel

The column's `customFilterDropdown: true` flag enables the
`customFilterDropdown` and `customFilterIcon` slots — the filter panel and its
icon are drawn by your markup, a search field for example.

**Example — `CustomizeFilterPanel.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsButton, CdsDivider, CdsIcon, CdsTable, CdsTextInput } from '@central-design-system/components';
import { reactive, ref, toRefs } from 'vue';

type TDataType = { key: string; name: string; age: number; address: string };

const state = reactive({
  searchText: '',
  searchedColumn: ''
});
const searchInput = ref();

const columns: NTable.NColumn.TColumns<TDataType> = [
  {
    title: 'Имя',
    dataIndex: 'name',
    key: 'name',
    customFilterDropdown: true,
    onFilter: (value, record) =>
      record.name
        .toString()
        .toLowerCase()
        .includes((value as string).toLowerCase()),
    onFilterDropdownVisibleChange: (visible) => {
      if (visible) {
        setTimeout(() => {
          searchInput.value?.focus?.();
        }, 100);
      }
    }
  },
  { title: 'Возраст', dataIndex: 'age', key: 'age' },
  {
    title: 'Адрес',
    dataIndex: 'address',
    key: 'address',
    customFilterDropdown: true,
    onFilter: (value, record) =>
      record.address
        .toString()
        .toLowerCase()
        .includes((value as string).toLowerCase()),
    onFilterDropdownVisibleChange: (visible) => {
      if (visible) {
        setTimeout(() => {
          searchInput.value?.focus?.();
        }, 100);
      }
    }
  }
];
const data: TDataType[] = [
  { key: '1', name: 'Иван Иванов', age: 18, address: 'г. Москва ул. Ленина д. 1' },
  { key: '2', name: 'Петр Петров', age: 25, address: 'г. Санкт-Петербург ул. Ленина д. 1' },
  { key: '3', name: 'Александр Александрович', age: 48, address: 'г. Екатеринбург ул. Ленина д. 1' },
  { key: '4', name: 'Иван Петрович', age: 42, address: 'г. Новосибирск ул. Ленина д. 1' }
];

const handleSearch = (selectedKeys: NTable.TKey[], confirm: Function, dataIndex?: NTable.TDataIndex) => {
  confirm();
  state.searchText = String(selectedKeys[0] ?? '');
  state.searchedColumn = String(dataIndex ?? '');
};

const handleReset = (clearFilters: ({ confirm }: { confirm: boolean }) => void) => {
  clearFilters({ confirm: true });
  state.searchText = '';
};

const searchingRegExp = (searchText: string) => new RegExp(`(?<=${searchText})|(?=${searchText})`, 'i');

const { searchText, searchedColumn } = toRefs(state);
</script>

<template>
  <CdsTable :columns="columns" :data="data">
    <template #customFilterDropdown="{ setSelectedKeys, selectedKeys, confirm, clearFilters, column }">
      <div class="p-1">
        <cds-text-input
          ref="searchInput"
          :placeholder="'Введите ' + String(column?.title ?? '').toLowerCase()"
          :model-value="selectedKeys[0]"
          size="sm"
          clearable
          hide-messages
          class="w-[176px]"
          @update:model-value="(value: any) => setSelectedKeys(value ? [value] : [])"
          @keydown.enter="handleSearch(selectedKeys, confirm, column?.dataIndex)"
        />
        <cds-divider class="my-3" />
        <div class="flex gap-2">
          <cds-button text="Сбросить" size="sm" variant="soft" color="brand" @click="handleReset(clearFilters)" />
          <cds-button
            text="Найти"
            size="sm"
            prepend-icon="search"
            @click="handleSearch(selectedKeys, confirm, column?.dataIndex)"
          />
        </div>
      </div>
    </template>
    <template #customFilterIcon>
      <cds-icon name="search" />
    </template>
    <template #bodyCell="{ text, column }">
      <span v-if="searchText && searchedColumn === column.dataIndex">
        <template v-for="(fragment, i) in text.toString().split(searchingRegExp(searchText))">
          <mark v-if="fragment.toLowerCase() === searchText.toLowerCase()" :key="i">
            {{ fragment }}
          </mark>
          <template v-else>{{ fragment }}</template>
        </template>
      </span>
    </template>
  </CdsTable>
</template>
```

## Selection and operations

The `row-selection` object turns on row selection: `selectedRowKeys` holds the
selected keys, `onChange` reports the changes. Actions on the selected set fit
nicely in the `toolbar` slot.

**Example — `SelectionAndOperation.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsButton, CdsTable } from '@central-design-system/components';
import { reactive, toRefs } from 'vue';

const state = reactive<{ selectedRowKeys: NTable.TKey[]; loading: boolean }>({
  selectedRowKeys: [],
  loading: false
});

const start = () => {
  state.loading = true;

  setTimeout(() => {
    state.loading = false;
    state.selectedRowKeys = [];
  }, 1000);
};

const cancel = () => {
  state.selectedRowKeys = [];
};

const onSelectChange = (selectedRowKeys: NTable.TKey[]) => {
  state.selectedRowKeys = selectedRowKeys;
};

const columns: NTable.NColumn.TColumns = [
  { title: 'Заголовок 1', dataIndex: 'name' },
  { title: 'Заголовок 2', dataIndex: 'age' },
  { title: 'Заголовок 3', dataIndex: 'address' },
  { title: 'Заголовок 4', dataIndex: 'phone' }
];
const data = [...Array(8)].map((_, i) => ({
  key: i,
  name: `Текст ячейки ${i}`,
  age: `Текст ячейки ${i}`,
  address: `Текст ячейки ${i}`,
  phone: `Текст ячейки ${i}`
}));

const { selectedRowKeys, loading } = toRefs(state);
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :row-selection="{ selectedRowKeys, onChange: onSelectChange }"
    :pagination="false"
  >
    <template #toolbar>
      <div class="flex items-center justify-between">
        <p>
          Выбрано: <strong>{{ selectedRowKeys.length }}</strong> строк
        </p>
        <div class="flex gap-2">
          <CdsButton variant="soft" color="brand" @click="cancel">Отменить</CdsButton>
          <CdsButton :loading="loading" @click="start">Загрузить</CdsButton>
        </div>
      </div>
    </template>
  </CdsTable>
</template>
```

## Custom selection menu items

The `selections` property fills the menu in the selection column header: the
ready-made `SELECTION_ALL`, `SELECTION_INVERT` and `SELECTION_NONE` constants
plus your own items with arbitrary logic.

**Example — `CustomSelection.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable, SELECTION_ALL, SELECTION_INVERT, SELECTION_NONE } from '@central-design-system/components';
import { computed, ref, unref } from 'vue';

const selectedRowKeys = ref<NTable.TKey[]>([]);

const onSelectChange = (selectedRows: NTable.TKey[]) => {
  selectedRowKeys.value = selectedRows;
};

const rowSelection = computed(() => ({
  selectedRowKeys: unref(selectedRowKeys),
  onChange: onSelectChange,
  hideDefaultSelections: true,
  selections: [
    SELECTION_ALL,
    SELECTION_INVERT,
    SELECTION_NONE,
    {
      key: 'odd',
      text: 'Выбрать нечетные',
      onSelect: (selectedRows: NTable.TKey[]) => {
        selectedRowKeys.value = selectedRows.filter((_key, index) => index % 2 === 0);
      }
    },
    {
      key: 'even',
      text: 'Выбрать четные',
      onSelect: (selectedRows: NTable.TKey[]) => {
        selectedRowKeys.value = selectedRows.filter((_key, index) => index % 2 !== 0);
      }
    }
  ]
}));

const columns: NTable.NColumn.TColumns = [
  { title: 'Заголовок 1', dataIndex: 'name' },
  { title: 'Заголовок 2', dataIndex: 'age' },
  { title: 'Заголовок 3', dataIndex: 'address' },
  { title: 'Заголовок 4', dataIndex: 'phone' }
];
const data = [...Array(6)].map((_, i) => ({
  key: i,
  name: `Текст ячейки ${i}`,
  age: `Текст ячейки ${i}`,
  address: `Текст ячейки ${i}`,
  phone: `Текст ячейки ${i}`
}));
</script>

<template>
  <CdsTable :columns="columns" :data="data" :row-selection="rowSelection" :pagination="false" />
</template>
```

## Expandable rows

The `expandedRowRender` slot renders the content of an expanded row — the
column with the chevron appears automatically.

**Example — `ExpandableRow.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsTable } from '@central-design-system/components';

type TDataType = { key: number; name: string; age: number; phone: string; address: string; description: string };

const columns: NTable.NColumn.TColumns<TDataType> = [
  { title: 'Имя', dataIndex: 'name', key: 'name' },
  { title: 'Возраст', dataIndex: 'age', key: 'age' },
  { title: 'Адрес', dataIndex: 'address', key: 'address' },
  { title: 'Телефон', dataIndex: 'phone', key: 'phone' }
];
const data: TDataType[] = [
  {
    key: 1,
    name: 'Иванов Иван',
    age: 20,
    phone: '79999999999',
    address: 'г. Москва, ул. Ленина д. 1',
    description: 'Меня зовут Иванов Иван, мне 20 лет и я живу по адресу г. Москва, ул. Ленина д. 1'
  },
  {
    key: 2,
    name: 'Иванов Василий',
    age: 32,
    phone: '79999999999',
    address: 'г. Москва, ул. Ленина д. 2',
    description: 'Меня зовут Иванов Василий, мне 32 года и я живу по адресу г. Москва, ул. Ленина д. 2'
  },
  {
    key: 3,
    name: 'Иванов Кирилл',
    age: 41,
    phone: '79999999999',
    address: 'г. Москва, ул. Ленина д. 3',
    description: 'Меня зовут Иванов Кирилл, мне 41 год и я живу по адресу г. Москва, ул. Ленина д. 3'
  }
];
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false">
    <template #expandedRowRender="{ record }">
      <p>{{ record.description }}</p>
    </template>
  </CdsTable>
</template>
```

## Nested tables

Anything can live inside `expandedRowRender` — including another `CdsTable`
with its own columns and data.

**Example — `NestedTable.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsFunctionalButton, CdsStatus, CdsTable, CdsToggle } from '@central-design-system/components';

const columns: NTable.NColumn.TColumns = [
  { title: 'Название', dataIndex: 'name', key: 'name' },
  { title: 'Платформа', dataIndex: 'platform', key: 'platform' },
  { title: 'Версия', dataIndex: 'version', key: 'version' },
  { title: 'Покрытие', dataIndex: 'coverage', key: 'coverage' },
  { title: 'Автор', dataIndex: 'creator', key: 'creator' },
  { title: 'Дата', dataIndex: 'createdAt', key: 'createdAt' },
  { title: 'Действия', key: 'operation' }
];
const data = [...Array(3)].map((_, i) => ({
  key: i,
  name: `Компонент ${i + 1}`,
  platform: 'iOS',
  version: '3.2.1',
  coverage: 100,
  creator: 'i.ivanov',
  createdAt: new Date('2023-02-07 23:12:00').toLocaleDateString()
}));

const innerColumns: NTable.NColumn.TColumns = [
  { title: 'Дата', dataIndex: 'date', key: 'date' },
  { title: 'Название', dataIndex: 'name', key: 'name' },
  { title: 'Статус', key: 'state' },
  { title: 'Покрытие', dataIndex: 'coverage', key: 'coverage' },
  { title: 'Действие', dataIndex: 'operation', key: 'operation' }
];
const innerData = [...Array(3)].map((_, i) => ({
  key: i,
  date: new Date('2023-02-07 23:12:00').toLocaleDateString(),
  name: `Это компонент ${i + 1}`,
  coverage: 'Покрыто: 56'
}));
</script>

<template>
  <CdsTable :columns="columns" :data="data" :pagination="false">
    <template #bodyCell="{ column }">
      <template v-if="column.key === 'operation'">
        <CdsToggle hide-messages />
      </template>
    </template>
    <template #expandedRowRender>
      <CdsTable :columns="innerColumns" :data="innerData" :pagination="false">
        <template #bodyCell="{ column }">
          <template v-if="column.key === 'state'">
            <span>
              <CdsStatus status="success" text="Готово" />
            </span>
          </template>
          <template v-else-if="column.key === 'operation'">
            <span class="flex gap-2">
              <CdsFunctionalButton icon="edit" />
              <CdsFunctionalButton icon="delete" />
            </span>
          </template>
        </template>
      </CdsTable>
    </template>
  </CdsTable>
</template>
```

## Tree data

Records with a `children` field expand as a tree. Together with `row-selection`,
the `checkStrictly: false` option turns on cascading selection: checking a
parent selects its children.

**Example — `TreeData.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsCheckbox, CdsTable } from '@central-design-system/components';
import { ref } from 'vue';

type TDataItem = {
  key: number;
  name: string;
  price: number;
  description: string;
  children?: TDataItem[];
};

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: 'Название', dataIndex: 'name', key: 'name' },
  { title: 'Цена, $', dataIndex: 'price', key: 'price', width: '12%' },
  { title: 'Описание', dataIndex: 'description', width: '30%', key: 'description' }
];
const data: TDataItem[] = [
  {
    key: 1,
    name: 'Apple iPhone',
    price: 3250,
    description: 'Описание товара',
    children: [
      { key: 11, name: 'iPhone 14 Pro', price: 2000, description: 'Описание товара' },
      {
        key: 12,
        name: 'Power Bank',
        price: 50,
        description: 'Описание товара',
        children: [{ key: 121, name: 'MagSafe Battery Pack', price: 50, description: 'Описание товара' }]
      },
      {
        key: 13,
        name: 'Headphones',
        price: 1200,
        description: 'Описание товара',
        children: [
          {
            key: 131,
            name: 'AirPods',
            price: 1200,
            description: 'Описание товара',
            children: [
              { key: 1311, name: 'AirPods Pro', price: 200, description: 'Описание товара' },
              { key: 1312, name: 'AirPods Max', price: 1000, description: 'Описание товара' }
            ]
          }
        ]
      }
    ]
  },
  { key: 2, name: 'Xiaomi Mi', price: 200, description: 'Описание товара' }
];

const rowSelection = ref({
  checkStrictly: false,
  onChange: (selectedRowKeys: NTable.TKey[], selectedRows: TDataItem[]) => {
    console.log(`selectedRowKeys: ${selectedRowKeys}`, 'selectedRows: ', selectedRows);
  },
  onSelect: (record: TDataItem, selected: boolean, selectedRows: TDataItem[]) => {
    console.log('onSelect', record, selected, selectedRows);
  }
});

const rowClassName = (record: TDataItem) => (!record.children?.length ? 'cds-table__row--no-children' : '');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsCheckbox v-model="rowSelection.checkStrictly" label="Строгий выбор" hide-messages />
    <CdsTable :columns="columns" :data="data" :row-selection="rowSelection" :row-class-name="rowClassName" />
  </div>
</template>
```

## Expanding every node

The `expanded-row-keys` prop makes expansion controlled: collect the keys of
every parent record — and an "Expand all" button unfolds the whole tree.

**Example — `TreeDataExpandableAll.vue`:**

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

type TDataItem = {
  key: number;
  name: string;
  price: number;
  description: string;
  children?: TDataItem[];
};

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: 'Название', dataIndex: 'name', key: 'name' },
  { title: 'Цена, $', dataIndex: 'price', key: 'price', width: '12%' },
  { title: 'Описание', dataIndex: 'description', width: '30%', key: 'description' }
];
const data = ref<TDataItem[]>([
  {
    key: 1,
    name: 'Apple iPhone',
    price: 3250,
    description: 'Описание товара',
    children: [
      { key: 11, name: 'iPhone 14 Pro', price: 2000, description: 'Описание товара' },
      {
        key: 12,
        name: 'Power Bank',
        price: 50,
        description: 'Описание товара',
        children: [{ key: 121, name: 'MagSafe Battery Pack', price: 50, description: 'Описание товара' }]
      },
      {
        key: 13,
        name: 'Headphones',
        price: 1200,
        description: 'Описание товара',
        children: [
          {
            key: 131,
            name: 'AirPods',
            price: 1200,
            description: 'Описание товара',
            children: [
              { key: 1311, name: 'AirPods Pro', price: 200, description: 'Описание товара' },
              { key: 1312, name: 'AirPods Max', price: 1000, description: 'Описание товара' }
            ]
          }
        ]
      }
    ]
  },
  { key: 2, name: 'Xiaomi Mi', price: 200, description: 'Описание товара' }
]);

const rowClassName = (record: TDataItem) => (!record.children?.length ? 'cds-table__row--no-children' : '');

// Массив для хранения ключей развернутых узлов
const expandedRowKeys = ref<NTable.TKey[]>([]);

// Рекурсивная функция для сбора всех ключей из данных
const getAllKeys = (items: TDataItem[]): NTable.TKey[] => {
  let keys: NTable.TKey[] = [];
  items.forEach((item) => {
    keys.push(item.key);
    if (item.children && item.children.length > 0) {
      keys = keys.concat(getAllKeys(item.children));
    }
  });
  return keys;
};

const allRowKeys = computed(() => getAllKeys(data.value));

const allExpanded = computed(() => allRowKeys.value.every((key) => expandedRowKeys.value.includes(key)));

const toggleAll = () => {
  expandedRowKeys.value = allExpanded.value ? [] : allRowKeys.value;
};

const handleExpand = (expanded: boolean, record: TDataItem) => {
  if (expanded) {
    expandedRowKeys.value.push(record.key);
  } else {
    expandedRowKeys.value = expandedRowKeys.value.filter((key) => key !== record.key);
  }
};
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :expanded-row-keys="expandedRowKeys"
    :row-class-name="rowClassName"
    @expand="handleExpand"
  >
    <template #headerCell="{ title, column }">
      <template v-if="column.key === 'name'">
        <CdsFunctionalButton :icon="allExpanded ? 'chevron-down' : 'chevron-right'" @click="toggleAll" />
      </template>
      {{ title }}
    </template>
  </CdsTable>
</template>
```

## Editable cells

The `bodyCell` slot replaces the content of a cell: on click the value turns
into an input, on confirmation it turns back into text.

**Example — `EditableCell.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsButton, CdsFunctionalButton, CdsTable, CdsTextInput, CdsTooltip } from '@central-design-system/components';
import type { Ref, UnwrapRef } from 'vue';
import { computed, reactive, ref } from 'vue';

type TDataItem = { key: string; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: 'Имя', dataIndex: 'name', width: '30%' },
  { title: 'Возраст', dataIndex: 'age' },
  { title: 'Адрес', dataIndex: 'address' },
  { title: 'Действия', dataIndex: 'actions' }
];

const data: Ref<TDataItem[]> = ref([
  { key: '0', name: 'Иван Иванов 0', age: 28, address: 'г. Москва, ул. Ленина, д. 0' },
  { key: '1', name: 'Иван Иванов 1', age: 28, address: 'г. Москва, ул. Ленина, д. 1' }
]);

const count = computed(() => data.value.length + 1);
const editableData: UnwrapRef<Record<string, TDataItem>> = reactive({});

function edit(key: string) {
  editableData[key] = data.value.filter((item) => key === item.key)[0];
}

function save(key: string) {
  Object.assign(data.value.filter((item) => key === item.key)[0], editableData[key]);
  delete editableData[key];
}

function remove(key: string) {
  data.value = data.value.filter((item) => item.key !== key);
}

const handleAdd = () => {
  data.value.push({
    key: `${count.value}`,
    name: `Иван Иванов ${count.value}`,
    age: 28,
    address: `г. Москва, ул. Ленина, д. ${count.value}`
  });
};
</script>

<template>
  <CdsTable :columns="columns" :data="data">
    <template #toolbar>
      <div class="flex justify-end">
        <CdsButton text="Добавить" @click="handleAdd" />
      </div>
    </template>

    <template #bodyCell="{ column, text, record }">
      <template v-if="column.dataIndex === 'name'">
        <div class="flex">
          <div v-if="editableData[record.key]" class="flex items-center grow-1">
            <CdsTextInput
              class="grow-1"
              v-model="editableData[record.key].name"
              hide-messages
              @keydown.enter="save(record.key)"
            />
            <CdsTooltip location="right">
              <template #activator="{ props }">
                <CdsFunctionalButton icon="save" class="ml-2" v-bind="props" @click="save(record.key)" />
              </template>
              Сохранить
            </CdsTooltip>
          </div>
          <div v-else class="flex items-center">
            {{ text || ' ' }}
            <CdsTooltip location="right">
              <template #activator="{ props }">
                <CdsFunctionalButton icon="edit" class="ml-2" v-bind="props" @click="edit(record.key)" />
              </template>
              Редактировать
            </CdsTooltip>
          </div>
        </div>
      </template>
      <template v-else-if="column.dataIndex === 'actions'">
        <CdsTooltip location="right">
          <template #activator="{ props }">
            <CdsFunctionalButton icon="delete" v-bind="props" @click="remove(record.key)" />
          </template>
          Удалить
        </CdsTooltip>
      </template>
    </template>
  </CdsTable>
</template>
```

## Editable rows

The whole row switches into edit mode: inputs in every cell, the "Save" and
"Cancel" buttons in the actions column.

**Example — `EditableRows.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsFunctionalButton, CdsTable, CdsTextInput, CdsTooltip } from '@central-design-system/components';
import type { UnwrapRef } from 'vue';
import { reactive, ref } from 'vue';

type TDataItem = { key: string; name: string; age: number; address: string };

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: 'Имя', dataIndex: 'name', width: '25%' },
  { title: 'Возраст', dataIndex: 'age', width: '15%' },
  { title: 'Адрес', dataIndex: 'address', width: '40%' },
  { title: 'Действия', dataIndex: 'actions' }
];

const data: TDataItem[] = [...Array(20)].map((_, i) => ({
  key: i.toString(),
  name: `Иван Иванов ${i}`,
  age: 28,
  address: `г. Москва, ул. Ленина, д. ${i}`
}));

const dataSource = ref(data);
const editableData: UnwrapRef<Record<string, TDataItem>> = reactive({});

function edit(key: string) {
  editableData[key] = dataSource.value.filter((item) => key === item.key)[0];
}

function save(key: string) {
  Object.assign(dataSource.value.filter((item) => key === item.key)[0], editableData[key]);
  delete editableData[key];
}

function cancel(key: string) {
  delete editableData[key];
}
</script>

<template>
  <CdsTable :columns="columns" :data="dataSource">
    <template #bodyCell="{ column, text, record }">
      <template v-if="['name', 'age', 'address'].includes(String(column.dataIndex))">
        <div>
          <CdsTextInput
            v-if="editableData[record.key]"
            v-model="editableData[record.key][column.dataIndex as keyof TDataItem]"
            hide-messages
          />
          <template v-else>
            {{ text }}
          </template>
        </div>
      </template>
      <template v-else-if="column.dataIndex === 'actions'">
        <div>
          <span v-if="editableData[record.key]">
            <CdsTooltip>
              <template #activator="{ props }">
                <CdsFunctionalButton icon="save" v-bind="props" @click="save(record.key)" />
              </template>
              Сохранить
            </CdsTooltip>
            <CdsTooltip>
              <template #activator="{ props }">
                <CdsFunctionalButton icon="remove" v-bind="props" @click="cancel(record.key)" />
              </template>
              Отменить
            </CdsTooltip>
          </span>
          <span v-else>
            <CdsTooltip location="left">
              <template #activator="{ props }">
                <CdsFunctionalButton icon="edit" v-bind="props" @click="edit(record.key)" />
              </template>
              Редактировать
            </CdsTooltip>
          </span>
        </div>
      </template>
    </template>
  </CdsTable>
</template>
```

## Editable table

Edit mode is turned on for the entire table at once — convenient for filling in
reference data in bulk.

**Example — `EditableTable.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import { CdsButton, CdsTable, CdsTextInput } from '@central-design-system/components';
import type { UnwrapRef } from 'vue';
import { reactive, ref } from 'vue';

type TDataItem = { key: string; name: string; age: number; address: string; quantity: number };

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: 'Имя', dataIndex: 'name', width: '25%' },
  { title: 'Возраст', dataIndex: 'age', width: '15%' },
  { title: 'Адрес', dataIndex: 'address', width: '40%' },
  { title: 'Количество', dataIndex: 'quantity' }
];

const data: TDataItem[] = [...Array(10)].map((_, i) => ({
  key: i.toString(),
  name: `Иван Иванов ${i}`,
  age: 32,
  address: `г. Москва, ул. Ленина, д. ${i}`,
  quantity: Math.round(Math.random() * 100)
}));

const dataSource = ref(data);
const editing = ref(false);
const editableData: UnwrapRef<Record<string, TDataItem>> = reactive({});

function edit() {
  if (!editing.value) {
    editing.value = true;
    dataSource.value.forEach((item) => {
      editableData[item.key] = { ...item };
    });
  } else {
    editing.value = false;
    Object.assign(dataSource.value, editableData);
  }
}

function cancel() {
  editing.value = false;
  dataSource.value.forEach((item) => {
    delete editableData[item.key];
  });
}
</script>

<template>
  <CdsTable :columns="columns" :data="dataSource">
    <template #toolbar>
      <div class="flex justify-end">
        <div class="flex gap-2">
          <CdsButton variant="soft" color="brand" :disabled="!editing" @click="cancel">Отменить</CdsButton>
          <CdsButton @click="edit">{{ editing ? 'Сохранить' : 'Редактировать' }}</CdsButton>
        </div>
      </div>
    </template>

    <template #bodyCell="{ column, text, record }">
      <div>
        <CdsTextInput
          v-if="editing"
          v-model="editableData[record.key][column.dataIndex as keyof TDataItem]"
          hide-messages
        />
        <template v-else>
          {{ text }}
        </template>
      </div>
    </template>
  </CdsTable>
</template>
```

## Dragging rows

The `row-draggable` prop shows a grip icon to the left of the row. The move is
reported by the `row-reorder` event — change the order in `data` yourself. A row
can only be dropped between neighboring rows.

**Example — `DraggableRows.vue`:**

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

type TRow = { key: string; name: string; category: string; price: string };

const columns: NTable.NColumn.TColumns<TRow> = [
  { title: 'Наименование', dataIndex: 'name', key: 'name' },
  { title: 'Категория', dataIndex: 'category', key: 'category' },
  { title: 'Цена', dataIndex: 'price', key: 'price', align: 'right' }
];

const data = ref<TRow[]>([
  { key: '1', name: 'iPhone 17 Pro Max', category: 'Смартфоны', price: '$1700' },
  { key: '2', name: 'MacBook Air M5', category: 'Ноутбуки', price: '$2000' },
  { key: '3', name: 'Apple Vision Pro', category: 'Гарнитуры', price: '$3500' },
  { key: '4', name: 'iPad Air', category: 'Планшеты', price: '$800' },
  { key: '5', name: 'AirPods Pro', category: 'Наушники', price: '$250' }
]);

const onRowReorder = (info: NTable.NDraggable.IRowReorderInfo<TRow>) => {
  const next = [...data.value];
  const dragIndex = next.findIndex((item) => item.key === info.dragKey);
  if (dragIndex === -1) return;
  const [moved] = next.splice(dragIndex, 1);
  const dropIndex = next.findIndex((item) => item.key === info.dropKey);
  next.splice(info.dropPosition === -1 ? dropIndex : dropIndex + 1, 0, moved);
  data.value = next;
};
</script>

<template>
  <CdsTable :columns="columns" :data="data" row-draggable :pagination="false" @row-reorder="onRowReorder" />
</template>
```

## Dragging nested rows

In a tree, a row is only reordered among the siblings of its own parent: it
cannot be dropped onto another level — the cursor shows "not allowed" and no
event arrives.

**Example — `DraggableNestedRows.vue`:**

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

type TRow = { key: number; name: string; price: number; children?: TRow[] };

const columns: NTable.NColumn.TColumns<TRow> = [
  { title: 'Название', dataIndex: 'name', key: 'name' },
  { title: 'Цена, $', dataIndex: 'price', key: 'price', align: 'right', width: '20%' }
];

const data = ref<TRow[]>([
  {
    key: 1,
    name: 'Apple iPhone',
    price: 3250,
    children: [
      { key: 11, name: 'iPhone 14 Pro', price: 2000 },
      { key: 12, name: 'Power Bank', price: 50 },
      { key: 13, name: 'Headphones', price: 1200 }
    ]
  },
  {
    key: 2,
    name: 'Xiaomi Mi',
    price: 200,
    children: [
      { key: 21, name: 'Mi Band', price: 40 },
      { key: 22, name: 'Mi Buds', price: 60 }
    ]
  }
]);

// Находит массив-родитель, содержащий строку с заданным ключом.
const findParentList = (list: TRow[], key: NTable.TKey): TRow[] | null => {
  for (const item of list) {
    if (item.key === key) return list;
    if (item.children) {
      const found = findParentList(item.children, key);
      if (found) return found;
    }
  }
  return null;
};

const onRowReorder = (info: NTable.NDraggable.IRowReorderInfo<TRow>) => {
  const next = [...data.value];
  // drag и drop гарантированно в одном родителе (reorder только между соседями).
  const parentList = findParentList(next, info.dragKey);
  if (!parentList) return;
  const dragIndex = parentList.findIndex((item) => item.key === info.dragKey);
  const [moved] = parentList.splice(dragIndex, 1);
  const dropIndex = parentList.findIndex((item) => item.key === info.dropKey);
  parentList.splice(info.dropPosition === -1 ? dropIndex : dropIndex + 1, 0, moved);
  data.value = next;
};
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :default-expand-all-rows="true"
    row-draggable
    :pagination="false"
    @row-reorder="onRowReorder"
  />
</template>
```

## Dragging columns

The `column-draggable` prop adds a grip icon to the header. The
`column-reorder` event reports the new order — update the `columns` array.

**Example — `DraggableColumns.vue`:**

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

type TRow = { key: string; name: string; category: string; price: string; stock: string };

const columns = ref<NTable.NColumn.TColumns<TRow>>([
  { title: 'Наименование', dataIndex: 'name', key: 'name' },
  { title: 'Категория', dataIndex: 'category', key: 'category' },
  { title: 'Цена', dataIndex: 'price', key: 'price', align: 'right' },
  { title: 'Наличие', dataIndex: 'stock', key: 'stock' }
]);

const data: TRow[] = [
  { key: '1', name: 'iPhone 17 Pro Max', category: 'Смартфоны', price: '$1500', stock: 'В наличии' },
  { key: '2', name: 'MacBook Air M5', category: 'Ноутбуки', price: '$2000', stock: 'В наличии' },
  { key: '3', name: 'Apple Vision Pro', category: 'Гарнитуры', price: '$3500', stock: 'Нет в наличии' }
];

const onColumnReorder = (info: NTable.NDraggable.IColumnReorderInfo<TRow>) => {
  const next = [...columns.value];
  const dragIndex = next.indexOf(info.dragColumn);
  if (dragIndex === -1) return;
  const [moved] = next.splice(dragIndex, 1);
  const dropIndex = next.indexOf(info.dropColumn);
  next.splice(info.dropPosition === -1 ? dropIndex : dropIndex + 1, 0, moved);
  columns.value = next;
};
</script>

<template>
  <CdsTable :columns="columns" :data="data" column-draggable :pagination="false" @column-reorder="onColumnReorder" />
</template>
```

## Dragging columns with groups

A leaf column is reordered inside its own group, while a group header is
dragged as a whole among neighboring groups.

**Example — `DraggableColumnGroups.vue`:**

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

const columns = ref<NTable.NColumn.TColumns>([
  { title: 'Имя', dataIndex: 'name', key: 'name', width: 120 },
  {
    title: 'Контакты',
    key: 'contacts',
    children: [
      { title: 'Телефон', dataIndex: 'phone', key: 'phone', width: 160 },
      { title: 'Email', dataIndex: 'email', key: 'email', width: 200 }
    ]
  },
  {
    title: 'Компания',
    key: 'company',
    children: [
      { title: 'Название', dataIndex: 'companyName', key: 'companyName', width: 160 },
      { title: 'Город', dataIndex: 'city', key: 'city', width: 140 }
    ]
  }
]);

const data = [...Array(5)].map((_, i) => ({
  key: i,
  name: 'Иван',
  phone: '+7 900 000-00-00',
  email: 'ivan@b2b-center.ru',
  companyName: 'B2B-Center',
  city: 'Москва'
}));

// Находит массив-родитель (уровень группы), содержащий колонку по ссылке.
const findParentList = (
  list: NTable.NColumn.TColumns,
  column: NTable.NColumn.IColumn
): NTable.NColumn.TColumns | null => {
  for (const col of list) {
    if (col === column) return list;
    const children = (col as NTable.NColumn.IColumnGroup).children;
    if (children) {
      const found = findParentList(children, column);
      if (found) return found;
    }
  }
  return null;
};

const onColumnReorder = (info: NTable.NDraggable.IColumnReorderInfo) => {
  const next = [...columns.value];
  const parentList = findParentList(next, info.dragColumn);
  if (!parentList) return;
  const dragIndex = parentList.indexOf(info.dragColumn);
  const [moved] = parentList.splice(dragIndex, 1);
  const dropIndex = parentList.indexOf(info.dropColumn);
  parentList.splice(info.dropPosition === -1 ? dropIndex : dropIndex + 1, 0, moved);
  columns.value = next;
};
</script>

<template>
  <CdsTable
    :columns="columns"
    :data="data"
    :scroll="{ x: 'max-content' }"
    bordered
    column-draggable
    :pagination="false"
    @column-reorder="onColumnReorder"
  />
</template>
```

## Data from the server

Pagination, sorting and filters are handled on the backend: the `change` event
gives you the current state of the table, the handler requests a page of data,
and the `loading` prop shows the request in progress.

**Example — `Ajax.vue`:**

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

type APIResponse = {
  results: {
    gender: 'female' | 'male';
    name: { first: string; last: string };
    email: string;
    login: { uuid: string };
    location: { city: string; country: string };
  }[];
};

const columns = [
  { title: 'Имя', dataIndex: 'name', sorter: true, width: '20%' },
  {
    title: 'Пол',
    dataIndex: 'gender',
    filters: [
      { text: 'Мужчина', value: 'male' },
      { text: 'Женщина', value: 'female' }
    ],
    width: '20%'
  },
  { title: 'Email', dataIndex: 'email' },
  { title: 'Адрес', dataIndex: 'location', sorter: true }
];
const dataSource = ref<APIResponse['results']>([]);

const FIRST_PAGE = 1;
const PER_PAGE = 10;
const TOTAL = 100;
const pagination = computed(() => ({
  total: TOTAL,
  length: PER_PAGE
}));

const isLoading = ref(false);

async function queryData(params: Record<string, any>) {
  try {
    isLoading.value = true;

    const query = new URLSearchParams(
      Object.entries(params)
        .filter(([, value]) => value !== undefined && value !== null)
        .map(([key, value]) => [key, String(value)])
    );
    const response = await fetch(`https://randomuser.me/api?${query}`);
    const data: APIResponse = await response.json();

    dataSource.value = data.results ?? [];
  } catch (error) {
    console.error(error);
  } finally {
    isLoading.value = false;
  }
}

onMounted(() => {
  queryData({ results: PER_PAGE, page: FIRST_PAGE });
});

const handleTableChange: ITableProps['onChange'] = (paginationInfo, filters: any, sorter: any) => {
  queryData({
    results: paginationInfo.length as number,
    page: paginationInfo.modelValue,
    sortField: sorter.field,
    sortOrder: sorter.order,
    ...filters
  });
};
</script>

<template>
  <CdsTable
    :data="dataSource"
    :columns="columns"
    :row-key="(record) => record.login.uuid"
    :pagination="pagination"
    :loading="isLoading"
    @change="handleTableChange"
  >
    <template #bodyCell="{ column, text }">
      <template v-if="column.dataIndex === 'name'">{{ text.first }} {{ text.last }}</template>
      <template v-if="column.dataIndex === 'location'">{{ text.country }}, {{ text.city }}</template>
    </template>
  </CdsTable>
</template>
```

## Product moderation

A header with tabs, a toolbar with search and filters, an empty state with an
action and external pagination in the footer — a typical table for a moderation
section.

**Example — `ReceiptModeration.vue`:**

```vue
<script setup lang="ts">
import type { NTable } from '@central-design-system/components';
import {
  CdsBadge,
  CdsButton,
  CdsEmptyState,
  CdsFunctionalButton,
  CdsIcon,
  CdsLoader,
  CdsPagination,
  CdsSelect,
  CdsSkeletonLoader,
  CdsTab,
  CdsTable,
  CdsTabs,
  CdsTag,
  CdsTextInput,
  CdsTooltip,
  utils
} from '@central-design-system/components';
import { computed, onMounted, ref, unref, watch } from 'vue';

const { debounce, plurals } = utils;

type TDataItem = {
  key: number;
  sku: string;
  date: string;
  name: string;
  category: string;
  tolerance: number;
  count: string;
  base_price: number | string;
  percent: number;
  price: number | string;
};

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: 'Артикул', dataIndex: 'sku', width: 140 },
  { title: 'Дата', dataIndex: 'date', width: 140 },
  { title: 'Наименование', dataIndex: 'name', width: 350 },
  { title: 'Толеранс, %', dataIndex: 'tolerance', align: 'right', width: 110 },
  { title: 'Единица', dataIndex: 'count', width: 110 },
  { title: 'Базовая цена, ₽', dataIndex: 'base_price', align: 'right', width: 140 },
  { title: '%', dataIndex: 'percent', align: 'right', width: 70 },
  { title: 'Новая цена, ₽', dataIndex: 'price', align: 'right', width: 140 }
];
const data = ref<TDataItem[]>([]);
const filtersData = ['Узлы, устройства и инструменты', 'Изделия производственные', 'Машины установки и оборудование'];
const isLoading = ref(false);
const tableDataSwitcher = ref(0);
const isActiveFilters = ref(false);

const currentPage = ref(1);
const totalData = ref(100);
const perPage = ref(10);
const pagesLength = computed(() => Math.ceil(unref(totalData) / unref(perPage)));
const pageSizeItems = Array.from(new Set([5, 10, 15, 20, 30, 50]), (item) => ({
  value: item,
  title: item.toString()
}));

const queryParams = computed(() => ({
  page: unref(currentPage),
  perPage: unref(perPage)
}));

const formatPrice = (price: number | string) =>
  new Intl.NumberFormat('ru-RU', {
    style: 'decimal',
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  }).format(+price);

const queryData = async (params?: Record<string, any>) => {
  try {
    isLoading.value = true;

    const query = new URLSearchParams({ example: 'example1', ...params });
    const response = await fetch(`https://cds-api.b2b-center.ru/api/v1/examples/data-table?${query}`);
    const { data: examples, meta: metaInfo } = await response.json();
    // Принудительная задержка для примера загрузки
    await new Promise((resolve) => setTimeout(resolve, 1000));

    totalData.value = metaInfo.total;
    perPage.value = metaInfo.perPage;

    data.value =
      examples.map((item: TDataItem, idx: number) => ({
        ...item,
        base_price: formatPrice(item.base_price),
        price: formatPrice(item.price),
        key: idx
      })) ?? [];
  } catch (error) {
    console.error(error);
  } finally {
    isLoading.value = false;
  }
};

const getDataTableExample = () => {
  queryData(unref(queryParams));
};
const clearDataTableExample = () => {
  data.value = [];
};

const isPublishLoading = ref(false);
const publishData = async () => {
  isPublishLoading.value = true;

  await new Promise((resolve) => setTimeout(resolve, 1000));
  selectedRowKeys.value = [];

  isPublishLoading.value = false;
};

const selectedRowKeys = ref<NTable.TKey[]>([]);
const selectedRowText = computed(() => plurals(unref(selectedRowKeys).length, ['строка', 'строки', 'строк']));

const cancelSelected = () => {
  selectedRowKeys.value = [];
};

const onSelectChange = (selectedKeys: NTable.TKey[]) => {
  selectedRowKeys.value = selectedKeys;
};

const handleSearch = debounce(async () => {
  await queryData(unref(queryParams));
}, 500);

onMounted(() => {
  queryData(unref(queryParams));
});

watch([currentPage, perPage], () => {
  queryData(unref(queryParams));
});

watch(tableDataSwitcher, () => {
  queryData(unref(queryParams));
});
</script>

<template>
  <CdsTable
    class="min-w-[860px]"
    :columns="columns"
    :data="data"
    :row-selection="{ selectedRowKeys, onChange: onSelectChange }"
    :pagination="false"
  >
    <template #header>
      <div class="flex justify-between">
        <div>
          <h4>Список товаров, поступивших на модерацию</h4>
          <p class="mb-4 text-content-secondary">
            Согласуйте или отклоните товары поставщика для их доступности в каталоге
          </p>
          <div class="flex">
            <CdsTabs v-model="tableDataSwitcher">
              <CdsTab>Все 654</CdsTab>
              <CdsTab>Новые 340</CdsTab>
              <CdsTab>Обновленные 314</CdsTab>
            </CdsTabs>
          </div>
        </div>
        <div>
          <CdsButton variant="soft" color="brand" text="Удалить данные" @click="clearDataTableExample" />
        </div>
      </div>
    </template>

    <template #toolbar>
      <div class="flex items-center justify-between">
        <div class="flex items-center gap-4">
          <p>
            Выбрано: <strong>{{ selectedRowKeys.length }}</strong> {{ selectedRowText }}
          </p>
          <CdsTextInput
            prepend-inner-icon="search"
            placeholder="Артикул, наименование"
            hide-messages
            class="w-[250px]"
            @update:model-value="handleSearch"
          />
          <CdsButton
            variant="soft"
            :color="isActiveFilters ? 'brand' : 'neutral'"
            prepend-icon="adjust"
            @click="isActiveFilters = !isActiveFilters"
          >
            Фильтры
            <CdsBadge v-if="isActiveFilters" content="10" inline />
          </CdsButton>
        </div>
        <div class="flex gap-2">
          <CdsButton variant="soft" color="brand" text="Отклонить" @click="cancelSelected" />
          <CdsButton text="Опубликовать" :loading="isPublishLoading" @click="publishData" />
        </div>
      </div>
      <div v-if="isActiveFilters" class="mt-4">
        <h6 class="mb-2">Активные фильтры:</h6>
        <div class="flex flex-col gap-2">
          <div class="flex">
            <div class="flex items-start">
              <CdsFunctionalButton icon="remove" @click="isActiveFilters = false" />
              <div class="mx-1 flex h-[24px] items-center">Категории:</div>
            </div>
            <div class="flex flex-wrap items-center gap-2">
              <CdsTag v-for="item in filtersData" :key="item">{{ item }}</CdsTag>
            </div>
          </div>
        </div>
      </div>
    </template>

    <template #headerCell="{ title, column }">
      <div class="flex items-center" :class="{ 'justify-end': column.align === 'right' }">
        <span>{{ title }}</span>
        <CdsTooltip v-if="['count', 'percent'].includes(String(column.dataIndex))">
          <template #activator="{ props }">
            <CdsIcon name="info" class="ml-2" v-bind="props" />
          </template>
          Информация о столбце
        </CdsTooltip>
      </div>
    </template>

    <template #bodyCell>
      <template v-if="isLoading">
        <CdsSkeletonLoader type="text" />
      </template>
    </template>

    <template #footer>
      <div class="flex items-center justify-between">
        <CdsPagination v-model="currentPage" :length="pagesLength" class="w-full" />
        <div class="flex w-full justify-center gap-1">
          Отображено <strong>{{ perPage }}</strong> из <strong>{{ totalData }}</strong>
        </div>
        <div class="flex w-full items-center justify-end gap-2">
          <span class="text-content-tertiary">Строк на странице:</span>
          <CdsSelect v-model="perPage" :items="pageSizeItems" hide-messages class="max-w-[70px]" />
        </div>
      </div>
    </template>

    <template #emptyText>
      <div class="flex h-[500px] items-center justify-center">
        <CdsLoader v-if="isLoading" fixed overlay />
        <CdsEmptyState
          title="Нет данных"
          description="Нажмите кнопку ниже чтобы добавить данные в таблицу"
          illustration="documents"
        >
          <template #actions>
            <CdsButton text="Добавить данные" @click="getDataTableExample" />
          </template>
        </CdsEmptyState>
      </div>
    </template>
  </CdsTable>
</template>
```

## Items and prices

Built-in pagination with a counter and a page size selector, a skeleton while
loading and composite cells with an extra line of text.

**Example — `ReceiptPositions.vue`:**

```vue
<script setup lang="ts">
import type { ITableProps, NTable } from '@central-design-system/components';
import {
  CdsButton,
  CdsEmptyState,
  CdsLoader,
  CdsSkeletonLoader,
  CdsTab,
  CdsTable,
  CdsTabs,
  CdsTextInput,
  utils
} from '@central-design-system/components';
import { computed, onMounted, ref, unref, watch } from 'vue';

const { plurals } = utils;

type TDataItem = {
  key: number;
  id: number;
  name: string;
  best_price: number | string;
  qty: number;
  price: number | string;
  tax: number;
  delay: number;
  download: boolean;
};

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: '№', dataIndex: 'id', width: 40 },
  { title: 'Позиция', dataIndex: 'name', width: 350 },
  { title: 'Лучшая цена с НДС, ₽', dataIndex: 'best_price', width: 200, align: 'right' },
  { title: 'Количество', dataIndex: 'qty', align: 'right', width: 80 },
  { title: 'Цена за единицу с НДС, ₽', dataIndex: 'price', align: 'right', width: 200 },
  { title: 'НДС, %', dataIndex: 'tax', align: 'right', width: 80 },
  { title: 'Срок поставки, дней', dataIndex: 'delay', align: 'right', width: 180 },
  { title: 'Документация', dataIndex: 'docs', align: 'right', width: 80 }
];

const data = ref<TDataItem[]>([]);
const total = ref(10);
const isLoading = ref(false);
const tableDataSwitcher = ref(0);

const formatPrice = (price: number | string) =>
  new Intl.NumberFormat('ru-RU', {
    style: 'decimal',
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  }).format(+price);

const queryDataTableExample = async () => {
  try {
    isLoading.value = true;

    const response = await fetch('https://cds-api.b2b-center.ru/api/v1/examples/data-table?example=example2');
    const { data: examples } = await response.json();
    // Принудительная задержка для примера загрузки
    await new Promise((resolve) => setTimeout(resolve, 1000));

    data.value =
      examples.map((item: TDataItem, idx: number) => ({
        ...item,
        best_price: formatPrice(item.best_price),
        price: formatPrice(item.price),
        key: idx
      })) ?? [];
  } catch (error) {
    console.error(error);
  } finally {
    isLoading.value = false;
  }
};

const selectedRowKeys = ref<NTable.TKey[]>([]);
const selectedRowText = computed(() => plurals(unref(selectedRowKeys).length, ['строка', 'строки', 'строк']));

const onSelectChange = (selectedKeys: NTable.TKey[]) => {
  selectedRowKeys.value = selectedKeys;
};

const onTableChange: ITableProps<TDataItem>['onChange'] = (pagination) => {
  total.value = pagination.total!;
};

onMounted(() => {
  queryDataTableExample();
});

watch(tableDataSwitcher, () => {
  queryDataTableExample();
});
</script>

<template>
  <CdsTable
    class="min-w-[860px]"
    :columns="columns"
    :data="data"
    :pagination="{ total, position: ['bottomLeft'], counter: true, size: true }"
    :row-selection="{ selectedRowKeys, onChange: onSelectChange }"
    @change="onTableChange"
  >
    <template #header>
      <div class="flex justify-between">
        <div>
          <h4 class="mb-4">Позиции и цены</h4>
          <CdsTabs v-model="tableDataSwitcher">
            <CdsTab>Заявки на позиции</CdsTab>
            <CdsTab>Позиции без заявки</CdsTab>
          </CdsTabs>
        </div>
        <div>
          <CdsButton prepend-icon="upload" variant="soft" color="brand" text="Загрузить из файла" />
        </div>
      </div>
    </template>

    <template #toolbar>
      <div class="flex items-end justify-between">
        <div>
          <p>
            Выбрано: <strong>{{ selectedRowKeys.length }}</strong> {{ selectedRowText }}
          </p>
        </div>
        <div class="flex gap-2">
          <CdsTextInput prefix="на" suffix="%" model-value="5" hide-messages class="mr-2 w-[127px]" />
          <CdsButton variant="soft" color="brand" text="Пересчитать" />
          <CdsButton text="Сохранить цены" />
        </div>
      </div>
    </template>

    <template #bodyCell="{ column, record, text }">
      <template v-if="isLoading">
        <CdsSkeletonLoader type="text@4" />
      </template>
      <template v-else>
        <div v-if="column.dataIndex === 'name'" class="flex flex-col">
          <p>{{ text }}</p>
          <span class="text-content-secondary">Количество: 100 шт</span>
          <span class="text-content-secondary">Максимальная цена: 150.00 ₽ с НДС 20%</span>
        </div>
        <div v-if="column.dataIndex === 'docs'">
          <CdsButton
            size="sm"
            :prepend-icon="record.download ? 'download' : 'upload'"
            variant="soft"
            :color="record.download ? 'neutral' : 'brand'"
            :text="record.download ? 'Скачать' : 'Добавить'"
          />
        </div>
      </template>
    </template>

    <template #emptyText>
      <div class="flex h-[500px] items-center justify-center">
        <CdsLoader v-if="isLoading" fixed overlay />
        <CdsEmptyState
          title="Нет данных"
          description="Нажмите кнопку ниже чтобы добавить данные в таблицу"
          illustration="documents"
        >
          <template #actions>
            <CdsButton text="Добавить данные" @click="queryDataTableExample" />
          </template>
        </CdsEmptyState>
      </div>
    </template>
  </CdsTable>
</template>
```

## Item list

A nested table inside an expanded row and a toolbar with fields and a dropdown
calendar — a recipe for documents with line items.

**Example — `ReceiptPositionsList.vue`:**

```vue
<script setup lang="ts">
import type { ITableProps, NTable } from '@central-design-system/components';
import {
  CdsButton,
  CdsDatePicker,
  CdsEmptyState,
  CdsFunctionalButton,
  CdsLoader,
  CdsMenu,
  CdsSkeletonLoader,
  CdsTab,
  CdsTable,
  CdsTabs,
  CdsTextInput,
  utils
} from '@central-design-system/components';
import { computed, onMounted, ref, unref, watch } from 'vue';

const { plurals } = utils;

type TInnerDataItem = {
  key: number | string;
  factory: string;
  firm: number;
  place: string;
  date: string;
  price_one: number | string;
  qty: number;
  price: number | string;
};
type TDataItem = {
  key: number | string;
  id: number;
  name: string;
  group: number | string;
  size: number;
  qty: number | string;
  price: number | string;
  innerData: TInnerDataItem[];
};

const columns: NTable.NColumn.TColumns<TDataItem> = [
  { title: '№', dataIndex: 'id', width: 59 },
  { title: 'Код ОЗМ', dataIndex: 'code', width: 91 },
  { title: 'Позиция', dataIndex: 'name', width: 545 },
  { title: 'Группа закупок', dataIndex: 'group', width: 187 },
  { title: 'Единица', dataIndex: 'size', width: 89 },
  { title: 'Количество', dataIndex: 'qty', align: 'right', width: 107 },
  { title: 'Плановая стоимость, ₽', dataIndex: 'price', align: 'right', width: 187 },
  { title: '', dataIndex: 'action', width: 45 }
];
const innerColumns: NTable.NColumn.TColumns<TInnerDataItem> = [
  { title: 'Завод', dataIndex: 'factory', width: 98 },
  { title: 'Склад', dataIndex: 'firm', width: 92 },
  { title: 'Место поставки', dataIndex: 'place', width: 218 },
  { title: 'Плановая дата поставки', dataIndex: 'date', width: 280 },
  { title: 'Цена за единицу, ₽', dataIndex: 'price_one', align: 'right', width: 290 },
  { title: 'Количество', dataIndex: 'qty', align: 'right', width: 107 },
  { title: 'Плановая стоимость, ₽', dataIndex: 'price', align: 'right', width: 185 },
  { title: '', dataIndex: 'action', width: 44 }
];

const data = ref<TDataItem[]>([]);
const total = ref(10);
const isLoading = ref(false);
const tableDataSwitcher = ref(0);
const date = ref('');

const formatPrice = (price: number | string) =>
  new Intl.NumberFormat('ru-RU', {
    style: 'decimal',
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  }).format(+price);

const queryDataTableExample = async () => {
  try {
    isLoading.value = true;

    const response = await fetch('https://cds-api.b2b-center.ru/api/v1/examples/data-table?example=example3');
    const { data: examples } = await response.json();
    // Принудительная задержка для примера загрузки
    await new Promise((resolve) => setTimeout(resolve, 1000));

    data.value =
      examples.map((item: TDataItem, idx: number) => ({
        ...item,
        price: formatPrice(item.price),
        innerData: item.innerData.map((innerItem, innerIdx) => ({
          ...innerItem,
          price_one: formatPrice(innerItem.price_one),
          key: `${idx}.${innerIdx}`
        })),
        key: idx
      })) ?? [];
  } catch (error) {
    console.error(error);
  } finally {
    isLoading.value = false;
  }
};

const selectedRowKeys = ref<NTable.TKey[]>([]);
const selectedRowText = computed(() => plurals(unref(selectedRowKeys).length, ['строка', 'строки', 'строк']));

const onSelectChange = (selectedKeys: NTable.TKey[]) => {
  selectedRowKeys.value = selectedKeys;
};

const onTableChange: ITableProps<TDataItem>['onChange'] = (pagination) => {
  total.value = pagination.total!;
};

onMounted(() => {
  queryDataTableExample();
});

watch(tableDataSwitcher, () => {
  queryDataTableExample();
});
</script>

<template>
  <CdsTable
    class="min-w-[860px]"
    :columns="columns"
    :data="data"
    :pagination="{ total, position: ['bottomLeft'], counter: true, size: true }"
    :row-selection="{ selectedRowKeys, onChange: onSelectChange }"
    @change="onTableChange"
  >
    <template #header>
      <div class="flex justify-between">
        <div>
          <h4 class="mb-4">Список позиций</h4>
          <CdsTabs v-model="tableDataSwitcher">
            <CdsTab text="Позиции" />
            <CdsTab text="Адреса" />
          </CdsTabs>
        </div>
        <div class="flex gap-2">
          <CdsButton prepend-icon="download" variant="soft" color="brand" text="Скачать шаблон" />
          <CdsButton prepend-icon="upload" variant="soft" color="brand" text="Загрузить из файла" />
        </div>
      </div>
    </template>

    <template #toolbar>
      <div class="flex flex-wrap items-end justify-between gap-4">
        <div class="flex items-end gap-4">
          <p class="min-w-[121px]">
            Выбрано: <strong>{{ selectedRowKeys.length }}</strong> {{ selectedRowText }}
          </p>
          <CdsTextInput label="Все адреса" placeholder="Введите адрес" hide-messages class="w-[250px]" />
          <CdsTextInput
            v-model="date"
            append-inner-icon="calendar"
            label="Дата"
            placeholder="Выберите дату"
            hide-messages
            class="w-[250px]"
          >
            <CdsMenu activator="parent" :close-on-content-click="false">
              <CdsDatePicker v-model="date" />
            </CdsMenu>
          </CdsTextInput>
        </div>
        <div class="flex gap-2">
          <CdsButton variant="soft" color="brand" prepend-icon="add" text="Добавить позицию" />
          <CdsButton variant="soft" color="brand" prepend-icon="add" text="Добавить адреса и позиции" />
        </div>
      </div>
    </template>

    <template #bodyCell="{ column }">
      <template v-if="isLoading">
        <CdsSkeletonLoader type="text" />
      </template>
      <template v-else>
        <CdsFunctionalButton v-if="column.dataIndex === 'action'" icon="delete" />
      </template>
    </template>

    <template #expandedRowRender="{ record }">
      <CdsTable :columns="innerColumns" :data="record.innerData" :pagination="false">
        <template #bodyCell="{ column }">
          <template v-if="column.dataIndex === 'action'">
            <CdsFunctionalButton icon="delete" />
          </template>
        </template>
      </CdsTable>
    </template>

    <template #emptyText>
      <div class="flex h-[500px] items-center justify-center">
        <CdsLoader v-if="isLoading" fixed overlay />
        <CdsEmptyState
          title="Нет данных"
          description="Нажмите кнопку ниже чтобы добавить данные в таблицу"
          illustration="documents"
        >
          <template #actions>
            <CdsButton text="Добавить данные" @click="queryDataTableExample" />
          </template>
        </CdsEmptyState>
      </div>
    </template>
  </CdsTable>
</template>
```

## API

### CdsTable

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bordered` | `boolean \| undefined` | `false` | no | Show every table border |
| `borderless` | `boolean \| undefined` | `false` | no | Remove every table border |
| `canExpandable` | `boolean \| undefined` | `false` | no | Rows can be expanded |
| `childrenColumnName` | `string \| undefined` | `'children'` | no | Name of the property holding the child records |
| `columnDraggable` | `NTable.NDraggable.TColumnDraggable<any> \| undefined` | — | no | Column drag and drop. `true` or a configuration object `{ icon, disabled, allowDrop }`. Reordering only happens among siblings inside the same group; the consumer changes the order in the `@column-reorder` handler. |
| `columns` | `NTable.NColumn.TColumns<any> \| undefined` | — | no | Table columns |
| `components` | `NTable.NCustomize.TableComponents<any> \| undefined` | — | no | Override the default table components |
| `customHeaderRow` | `NTable.NCustomize.TGetComponentProps<NTable.NColumn.IColumn<any>[]> \| undefined` | — | no | Sets the properties for every header row |
| `customRow` | `NTable.NCustomize.TGetComponentProps<any> \| undefined` | — | no | Sets the properties for every row |
| `data` | `any[] \| undefined` | — | no | Array of records to show in the table |
| `defaultExpandAllRows` | `boolean \| undefined` | `false` | no | All rows are expanded by default |
| `defaultExpandedRowKeys` | `NTable.TKey[] \| undefined` | `undefined as ITableProps['defaultExpandedRowKeys']` | no | Keys of the rows expanded by default |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `expandColumnWidth` | `number \| undefined` | — | no | Width of the expand column |
| `expandedRowClassName` | `NTable.NRow.TClassName<any> \| undefined` | — | no | Classes for rows in the expanded state |
| `expandedRowKeys` | `NTable.TKey[] \| undefined` | `undefined as ITableProps['expandedRowKeys']` | no | Keys of the currently expanded rows (supports v-model) |
| `expandedRowRender` | `NTable.NExpand.TExpandedRowRender<any> \| undefined` | — | no | Render function for every expanded row |
| `expandFixed` | `NTable.TFixed \| undefined` | — | no | Pin the expand column (left \| right \| boolean) |
| `expandIcon` | `NTable.NExpand.TRenderExpandIcon<any> \| undefined` | — | no | Custom expand icon |
| `expandIconColumnIndex` | `number \| undefined` | — | no | Index of the column that holds the expand icon |
| `expandRowByClick` | `boolean \| undefined` | `false` | no | Expand the row by clicking anywhere in it |
| `footer` | `NTable.NRender.TPanelRender<any> \| undefined` | — | no | Render function for the table footer |
| `getPopupContainer` | `NTable.NCustomize.TGetPopupContainer \| undefined` | — | no | Container that dropdowns are rendered into |
| `header` | `NTable.NRender.TPanelRender<any> \| undefined` | — | no | Render function for the table title |
| `hovered` | `boolean \| undefined` | `false` | no | Highlight the row on hover |
| `id` | `string \| undefined` | — | no | Table identifier |
| `indentSize` | `number \| undefined` | `20` | no | Indent size in pixels for each nesting level |
| `loading` | `boolean \| undefined` | `false` | no | Table loading state |
| `locale` | `NTable.ILocale \| undefined` | — | no | Table localization (overrides the strings of the global locale) |
| `pagination` | `false \| NTable.NPagination.IProps \| undefined` | — | no | Table pagination configuration |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `rowClassName` | `string \| NTable.NRow.TClassName<any> \| undefined` | — | no | Row classes |
| `rowDraggable` | `NTable.NDraggable.TRowDraggable<any> \| undefined` | — | no | Row drag and drop. `true` or a configuration object `{ icon, disabled, allowDrop }`. Reordering only happens between siblings of the same parent; the consumer changes the order in the `@row-reorder` handler. |
| `rowExpandable` | `((record: any) => boolean) \| undefined` | — | no | Whether the row can be expanded |
| `rowKey` | `string \| NTable.NRow.TGetRowKey<any> \| undefined` | `'key'` | no | Unique row key — a string or a function returning a string |
| `rowSelection` | `NTable.NRow.IRowSelection<any> \| undefined` | — | no | Row selection configuration |
| `scroll` | `(NTable.TScroll & { scrollToFirstRowOnChange?: boolean \| undefined; }) \| undefined` | — | no | Whether the table can be scrolled |
| `showExpandColumn` | `boolean \| undefined` | — | no | Show the expand column |
| `showHeader` | `boolean \| undefined` | — | no | Whether to show the table header |
| `showSorterTooltip` | `NTable.NSorter.TTooltip \| undefined` | `true` | no | Whether to show sorting tooltips in the header. You can pass an object with CdsTooltip properties. |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `sortDirection` | `string[] \| undefined` | — | no | Sorting of the table data. 'ascend' \| 'descend' |
| `sticky` | `boolean \| NTable.NSticky.ISticky \| undefined` | — | no | Sticky behavior for the header and the scrollbar |
| `tableLayout` | `NTable.TLayout \| undefined` | — | no | Fixed or auto layout |
| `theme` | `string \| undefined` | — | no | Component theme |
| `toolbar` | `NTable.NRender.TPanelRender<any> \| undefined` | — | no | Render function for the table toolbar |
| `transformCellText` | `NTable.NCell.TTransformCellText<any> \| undefined` | — | no | Transform the text inside a cell |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `change` | `[pagination: NTable.NPagination.IProps, filters: Record<string, NTable.TFilterValue \| null>, sorter: NTable.ISorterResult<any> \| NTable.ISorterResult<any>[], extra: NTable.ICurrentData<any>]` | Fired when the pagination, the filters or the sorting change. |
| `columnReorder` | `[info: NTable.NDraggable.IColumnReorderInfo<any>]` | Fired when a column is dragged. The consumer changes the order of the columns. |
| `expand` | `[expanded: boolean, record: any]` | Fired when a row is expanded or collapsed. |
| `expandedRowsChange` | `[expandedKeys: NTable.TKey[]]` | Fired when the set of expanded rows changes. |
| `resizeColumn` | `[width: number, column: NTable.NColumn.IColumn<any>]` | Fired when a column is resized. |
| `rowReorder` | `[info: NTable.NDraggable.IRowReorderInfo<any>]` | Fired when a row is dragged. The consumer changes the order of the data. |
| `update:expandedRowKeys` | `[expandedKeys: NTable.TKey[]]` | Fired when the expanded rows are updated (v-model). |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `bodyCell` | `{ text: any; value: any; record: any; index: number; column: NTable.NColumn.IColumn<any>; }` | Custom render of a table body cell. |
| `customFilterDropdown` | `NTable.NColumn.IFilterDropdownProps<any>` | Custom filter dropdown of a column (used together with the column `customFilterDropdown`). |
| `customFilterIcon` | `{ filtered: boolean; column: NTable.NColumn.IColumn<any>; }` | Custom column filter icon. |
| `default` | `any` | Declarative column description with CdsTableColumn / CdsTableColumnGroup. |
| `emptyText` | `any` | Content shown when there is no data. |
| `expandedRowRender` | `{ record: any; index: number; indent: number; expanded: boolean; }` | Render of the expanded row content. |
| `expandIcon` | `NTable.NExpand.IRenderExpandIconProps<any>` | Custom row expand icon. |
| `footer` | `readonly any[]` | Table footer (the panel below the table). |
| `header` | `readonly any[]` | Table title (the panel above the table). |
| `headerCell` | `{ title: NTable.NColumn.TTitle<any>; column: NTable.NColumn.IColumn<any>; }` | Custom render of a table header cell. |
| `summary` | `{ pageData: readonly any[]; }` | Summary row of the table. |
| `toolbar` | `readonly any[]` | Table toolbar (the panel above the table). |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `table` | `any` | Reference to the internal table instance — gives access to its methods and state. |

### CdsTableColumn

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ value: any; text: any; record: any; index?: number \| undefined; renderIndex?: number \| undefined; column: NTable.NColumn.IColumn<any>; }` | Custom render of a column cell. |
| `filterIcon` | `{ filtered: boolean; column: NTable.NColumn.IColumn<any>; }` | Custom column filter icon. |
| `title` | `NTable.NColumn.ITitleProps<any>` | Column title. |

### CdsTableColumnGroup

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Columns of the group (CdsTableColumn). |
| `title` | `NTable.NColumn.ITitleProps<any>` | Title of the column group. |

---

# CdsTabs

_Category: Navigation · since 4.0.0_

_Tests: API 0/107 · 5 unit · lines 68.3% (v4.0.0-alpha.13) · a11y: 8 axe recommendations (v4.0.0-alpha.11)_

Tabs split the screen into sections of equal weight and switch between them in place, without going to another page. The bar is built from `CdsTab` components or from an `items` array, and the content of the sections is switched by `CdsTabsView` and `CdsTabsViewItem`.

**See also:** For a sequential process with steps and progress, use CdsSteps; to pick a single value in a form, use CdsButtonToggle.

## Anatomy

Tabs consist of a bar and a content area: with tabs from `items` the content
area is rendered automatically, with manual markup `CdsTabsView` is composed
next to the bar. The bar is a container with tab buttons; the selected tab is
highlighted by a moving slider.

## Variations

### Tabs and content

Sections are declared with `CdsTab` components in the default slot, and the
content with `CdsTabsViewItem` components inside `CdsTabsView`. The `value` props
bind a tab to its content, and a shared `v-model` keeps the bar and the content
area in sync.

**Example — `Default.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs, CdsTabsView, CdsTabsViewItem } from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('overview');
</script>

<template>
  <div class="m-auto max-w-[470px]">
    <CdsTabs v-model="tab">
      <CdsTab value="overview">Обзор</CdsTab>
      <CdsTab value="docs">Документы</CdsTab>
      <CdsTab value="history">История</CdsTab>
    </CdsTabs>

    <CdsTabsView v-model="tab" class="mt-2">
      <CdsTabsViewItem value="overview"> Сводка по проекту: статус, ответственные и ближайшие сроки. </CdsTabsViewItem>
      <CdsTabsViewItem value="docs"> Договоры, акты и счета — всего 8 документов. </CdsTabsViewItem>
      <CdsTabsViewItem value="history"> Хронология изменений за последние 30 дней. </CdsTabsViewItem>
    </CdsTabsView>
  </div>
</template>
```

### Tabs from an array

Pass an array of strings or `{ text, value }` objects into `items` — the tabs
and the content area are rendered automatically. The content of a section comes
from the `item.{value}` slots, the label of a tab from the `tab.{value}` slots.

**Example — `Items.vue`:**

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

const tab = ref('requests');
const items = [
  { text: 'Заявки', value: 'requests' },
  { text: 'Договоры', value: 'contracts' },
  { text: 'Акты', value: 'acts' }
];
</script>

<template>
  <div class="m-auto max-w-[470px]">
    <CdsTabs v-model="tab" :items="items">
      <template #[`item.requests`]>
        <p class="py-2">Открытые заявки за последний месяц.</p>
      </template>
      <template #[`item.contracts`]>
        <p class="py-2">Действующие договоры с контрагентами.</p>
      </template>
      <template #[`item.acts`]>
        <p class="py-2">Акты, ожидающие подписания.</p>
      </template>
    </CdsTabs>
  </div>
</template>
```

### Alignment

The `align` prop pushes the tabs to the start of the bar (the default), to the
center or to the end.

**Example — `Align.vue`:**

```vue
<script setup lang="ts">
import { CdsRadio, CdsRadioGroup, CdsTab, CdsTabs } from '@central-design-system/components';
import { ref } from 'vue';

const align = ref<'start' | 'center' | 'end'>('start');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsRadioGroup v-model="align" label="Позиционирование (align)" direction="horizontal">
      <CdsRadio label="start" value="start" />
      <CdsRadio label="center" value="center" />
      <CdsRadio label="end" value="end" />
    </CdsRadioGroup>

    <CdsTabs :align="align" class="w-full">
      <CdsTab>Москва</CdsTab>
      <CdsTab>Лиссабон</CdsTab>
      <CdsTab>Нью-Йорк</CdsTab>
    </CdsTabs>
  </div>
</template>
```

### Layout

The `grow` prop stretches the tabs across the whole width of the bar — every tab
takes an equal share of the free space.

**Example — `Grow.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs } from '@central-design-system/components';
</script>

<template>
  <CdsTabs grow>
    <CdsTab>Актуальные</CdsTab>
    <CdsTab>Последние</CdsTab>
    <CdsTab>Архивные</CdsTab>
  </CdsTabs>
</template>
```

The `fixed-tabs` prop also equalizes the width of the tabs, but caps it at 300px
and centers the group.

**Example — `FixedTabs.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs } from '@central-design-system/components';
</script>

<template>
  <CdsTabs fixed-tabs>
    <CdsTab>Все</CdsTab>
    <CdsTab>Входящие</CdsTab>
    <CdsTab>Отправленные</CdsTab>
    <CdsTab>Удаленные</CdsTab>
  </CdsTabs>
</template>
```

The `direction="vertical"` prop turns the bar into a column — handy for settings
and sections with a long list. The content area is placed next to it with a
regular flex row.

**Example — `Vertical.vue`:**

```vue
<script setup lang="ts">
import { CdsCard, CdsCardText, CdsTab, CdsTabs, CdsTabsView, CdsTabsViewItem } from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('company');
</script>

<template>
  <CdsCard class="m-auto max-w-[560px]">
    <div class="flex">
      <CdsTabs v-model="tab" direction="vertical">
        <CdsTab value="company" prepend-icon="company">Компания</CdsTab>
        <CdsTab value="employees" prepend-icon="user-group">Сотрудники</CdsTab>
        <CdsTab value="requisites" prepend-icon="credit-card">Реквизиты</CdsTab>
      </CdsTabs>

      <CdsTabsView v-model="tab">
        <CdsTabsViewItem value="company">
          <CdsCardText> Название, сфера деятельности и контакты — эти данные видят поставщики в каталоге. </CdsCardText>
        </CdsTabsViewItem>

        <CdsTabsViewItem value="employees">
          <CdsCardText> В организации 14 сотрудников. Пригласите коллег и настройте им права доступа. </CdsCardText>
        </CdsTabsViewItem>

        <CdsTabsViewItem value="requisites">
          <CdsCardText> ИНН, КПП и расчётный счёт подставляются в документы автоматически. </CdsCardText>
        </CdsTabsViewItem>
      </CdsTabsView>
    </div>
  </CdsCard>
</template>
```

### Icons

A tab accepts the same content props as a button: `prepend-icon` and
`append-icon` add an icon next to the text, `icon` leaves only the icon. For an
icon tab do not forget `aria-label` — without text it stays the only name of the
section.

**Example — `Icons.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTabs>
      <CdsTab prepend-icon="file">Документы</CdsTab>
      <CdsTab prepend-icon="message">Обсуждение</CdsTab>
      <CdsTab prepend-icon="settings">Настройки</CdsTab>
    </CdsTabs>

    <CdsTabs>
      <CdsTab icon="list-bullet" aria-label="Списком" />
      <CdsTab icon="view-rows" aria-label="Карточками" />
    </CdsTabs>
  </div>
</template>
```

The `stacked` prop puts the icon above the text — the tab becomes taller and
more noticeable. Such a layout works well with `align="center"` in mobile
scenarios.

**Example — `Stacked.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs, CdsTabsView, CdsTabsViewItem } from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('recent');
</script>

<template>
  <div class="m-auto max-w-[470px]">
    <CdsTabs v-model="tab" stacked align="center">
      <CdsTab value="recent" prepend-icon="time">Недавние</CdsTab>
      <CdsTab value="favorites" prepend-icon="star">Избранное</CdsTab>
      <CdsTab value="nearby" prepend-icon="location">Рядом</CdsTab>
    </CdsTabs>

    <CdsTabsView v-model="tab" class="mt-2">
      <CdsTabsViewItem value="recent"> Поставщики, с которыми вы работали за последний месяц. </CdsTabsViewItem>
      <CdsTabsViewItem value="favorites"> Компании, которые вы добавили в избранное. </CdsTabsViewItem>
      <CdsTabsViewItem value="nearby"> Поставщики в вашем регионе с доставкой за один день. </CdsTabsViewItem>
    </CdsTabsView>
  </div>
</template>
```

### States

The `disabled` prop turns a tab off, `loading` shows a loading indicator instead
of the content.

**Example — `States.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs } from '@central-design-system/components';
</script>

<template>
  <div class="flex justify-center">
    <CdsTabs>
      <CdsTab>Активные</CdsTab>
      <CdsTab disabled>Черновики</CdsTab>
      <CdsTab loading>Архив</CdsTab>
    </CdsTabs>
  </div>
</template>
```

### Colors

Tabs accept the color aliases of the palette (`neutral`, `red`, `green`, `cyan`,
`purple`…) or any CSS color. The `color` prop paints the text of the tabs,
`active-color` the slider of the selected tab, `bg-color` the background of the
whole bar, and `base-color` the background of the unselected tabs.

**Example — `Colors.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs } from '@central-design-system/components';
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTabs color="purple" active-color="purple">
      <CdsTab>Обзор</CdsTab>
      <CdsTab>Аналитика</CdsTab>
      <CdsTab>Отчёты</CdsTab>
    </CdsTabs>

    <CdsTabs bg-color="cyan">
      <CdsTab>Обзор</CdsTab>
      <CdsTab>Аналитика</CdsTab>
      <CdsTab>Отчёты</CdsTab>
    </CdsTabs>
  </div>
</template>
```

### Scrolling

When the tabs do not fit into the bar, it scrolls. The `show-arrows` prop adds
scroll arrows, `center-active` keeps the selected tab in the center of the bar.

**Example — `CenterActive.vue`:**

```vue
<script setup lang="ts">
import { CdsTab, CdsTabs } from '@central-design-system/components';
</script>

<template>
  <CdsTabs center-active show-arrows>
    <CdsTab v-for="i of 20" :key="i">Раздел {{ i }}</CdsTab>
  </CdsTabs>
</template>
```

### Slider

The `slider-transition` prop picks the animation of the slider under the
selected tab: `shift` (the default) moves it to the new tab, `grow` grows it in
place, `fade` fades it in. The duration is set through
`slider-transition-duration`, and `hide-slider` removes the slider entirely.

**Example — `Slider.vue`:**

```vue
<script setup lang="ts">
import { CdsRadio, CdsRadioGroup, CdsTab, CdsTabs } from '@central-design-system/components';
import { ref } from 'vue';

const transition = ref<'shift' | 'grow' | 'fade'>('shift');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsRadioGroup v-model="transition" label="Анимация (slider-transition)" direction="horizontal">
      <CdsRadio label="shift" value="shift" />
      <CdsRadio label="grow" value="grow" />
      <CdsRadio label="fade" value="fade" />
    </CdsRadioGroup>

    <CdsTabs :slider-transition="transition">
      <CdsTab>Обзор</CdsTab>
      <CdsTab>Аналитика</CdsTab>
      <CdsTab>Отчёты</CdsTab>
    </CdsTabs>
  </div>
</template>
```

### Slots

Slots replace the automatic rendering from `items` when you need your own
markup:

| Slot                   | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| `default`              | Your own `CdsTab` when `items` is not set                   |
| `tab`, `tab.{value}`   | Tab for an `items` element: shared and for a specific value |
| `item`, `item.{value}` | Section content: shared and for a specific value            |
| `view`                 | Extra content inside `CdsTabsView`                          |
| `prev`, `next`         | Your own scroll arrows                                      |

The `tab` and `item` slots receive the array element and replace the whole
component — return `CdsTab` and `CdsTabsViewItem` with your own `value` from
them. The `tab.{value}` and `item.{value}` slots replace the content only.

**Example — `Slots.vue`:**

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

const tab = ref('profile');
const items = [
  { text: 'Профиль', value: 'profile', icon: 'user' },
  { text: 'Уведомления', value: 'notifications', icon: 'notification' },
  { text: 'Безопасность', value: 'security', icon: 'lock' }
];
</script>

<template>
  <div class="m-auto max-w-[420px]">
    <CdsTabs v-model="tab" :items="items">
      <template #tab="{ item }">
        <CdsTab :value="item.value" :prepend-icon="item.icon">{{ item.text }}</CdsTab>
      </template>

      <template #item="{ item }">
        <CdsTabsViewItem :value="item.value">
          <p class="py-2">Раздел «{{ item.text }}»</p>
        </CdsTabsViewItem>
      </template>
    </CdsTabs>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A tab name is a short noun: the section is easy to scan. | Sentence-long names stretch the bar and read slower. |
| Two to six tabs: every section is visible at once and the choice is obvious. | A dozen tabs cannot be scanned — merge adjacent sections or move the rare ones into a menu. |
| Tabs are sections of equal weight that are switched in any order. | For a sequential process take CdsSteps: tabs show neither order nor progress. |

## Scenarios

### Card sections

Classic tabs: a product card with sections and a shared `v-model`. The review
counter is a `CdsBadge` with the `inline` prop right inside the tab slot.

**Example — `ProductCard.vue`:**

```vue
<script setup lang="ts">
import {
  CdsBadge,
  CdsCard,
  CdsCardText,
  CdsTab,
  CdsTabs,
  CdsTabsView,
  CdsTabsViewItem
} from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('description');
</script>

<template>
  <CdsCard class="m-auto max-w-[560px]">
    <CdsTabs v-model="tab">
      <CdsTab value="description">Описание</CdsTab>
      <CdsTab value="specs">Характеристики</CdsTab>
      <CdsTab value="reviews">
        Отзывы

        <template #append>
          <CdsBadge content="12" inline />
        </template>
      </CdsTab>
    </CdsTabs>

    <CdsCardText>
      <CdsTabsView v-model="tab">
        <CdsTabsViewItem value="description">
          Офисное кресло с регулируемой спинкой и поясничной поддержкой. Подходит для работы за компьютером дольше
          восьми часов в день.
        </CdsTabsViewItem>

        <CdsTabsViewItem value="specs">
          <dl class="grid grid-cols-2 gap-x-2 gap-y-1">
            <dt class="text-content-secondary">Максимальная нагрузка</dt>
            <dd>120 кг</dd>
            <dt class="text-content-secondary">Материал обивки</dt>
            <dd>Сетка, ткань</dd>
            <dt class="text-content-secondary">Гарантия</dt>
            <dd>3 года</dd>
          </dl>
        </CdsTabsViewItem>

        <CdsTabsViewItem value="reviews">
          «Собирается за десять минут, спинка держит отлично» — и ещё 11 отзывов со средней оценкой 4,8.
        </CdsTabsViewItem>
      </CdsTabsView>
    </CdsCardText>
  </CdsCard>
</template>
```

### List filter

Tabs work without a content area too: `v-model` holds the selected status and
the list is filtered by it through a `computed`. There is a single content area
— only the selection changes.

**Example — `ListFilter.vue`:**

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

const status = ref('all');

const orders = [
  { id: 1, title: 'Поставка канцелярии', company: 'ООО «Ромашка»', status: 'active', label: 'В работе' },
  { id: 2, title: 'Ремонт офиса', company: 'ООО «Василёк»', status: 'done', label: 'Завершён' },
  { id: 3, title: 'Закупка ноутбуков', company: 'АО «Полюс»', status: 'active', label: 'В работе' },
  { id: 4, title: 'Клининг склада', company: 'ООО «Чисто»', status: 'done', label: 'Завершён' }
];

const filtered = computed(() =>
  status.value === 'all' ? orders : orders.filter((order) => order.status === status.value)
);
</script>

<template>
  <div class="m-auto flex w-[420px] flex-col gap-2">
    <CdsTabs v-model="status">
      <CdsTab value="all">Все</CdsTab>
      <CdsTab value="active">В работе</CdsTab>
      <CdsTab value="done">Завершённые</CdsTab>
    </CdsTabs>

    <CdsList lines="two">
      <CdsListItem
        v-for="order of filtered"
        :key="order.id"
        :value="order.id"
        :title="order.title"
        :subtitle="order.company"
      >
        <template #append>
          <CdsTag size="sm" :text="order.label" />
        </template>
      </CdsListItem>
    </CdsList>
  </div>
</template>
```

### Lazy loading of sections

A heavy section loads on the first open: a `watch` on `v-model` fires the
request, `CdsSkeletonLoader` stands in for the content while it loads, and the
already loaded sections open instantly.

**Example — `LazyLoad.vue`:**

```vue
<script setup lang="ts">
import { CdsSkeletonLoader, CdsTab, CdsTabs, CdsTabsView, CdsTabsViewItem } from '@central-design-system/components';
import { ref, watch } from 'vue';

const tab = ref('summary');
const loaded = ref(['summary']);
const loading = ref(false);

watch(tab, async (value) => {
  if (loaded.value.includes(value as string)) return;

  loading.value = true;
  await new Promise((resolve) => setTimeout(resolve, 900));
  loaded.value = [...loaded.value, value as string];
  loading.value = false;
});
</script>

<template>
  <div class="m-auto max-w-[560px]">
    <CdsTabs v-model="tab">
      <CdsTab value="summary">Сводка</CdsTab>
      <CdsTab value="analytics">Аналитика</CdsTab>
      <CdsTab value="reports">Отчёты</CdsTab>
    </CdsTabs>

    <div class="pt-2">
      <CdsSkeletonLoader v-if="loading" type="article" />

      <CdsTabsView v-else v-model="tab">
        <CdsTabsViewItem value="summary"> Выручка за квартал выросла на 12%, средний чек — на 4%. </CdsTabsViewItem>
        <CdsTabsViewItem value="analytics"> Данные аналитики загрузились и закешировались. </CdsTabsViewItem>
        <CdsTabsViewItem value="reports"> Отчёты сформированы и готовы к выгрузке. </CdsTabsViewItem>
      </CdsTabsView>
    </div>
  </div>
</template>
```

### Sections in a "More" menu

When there are more sections than fit into the bar, the rare ones hide into a
CdsMenu whose activator is a regular "More" tab in the
same bar. A click on "More" immediately shows the first section from the menu,
the selected item takes the place of the first visible tab (the displaced one
moves into the menu), and if the menu is closed without a choice, the bar and
the content return to the current section.

**Example — `MoreMenu.vue`:**

```vue
<script setup lang="ts">
import {
  CdsList,
  CdsListItem,
  CdsMenu,
  CdsTab,
  CdsTabs,
  CdsTabsView,
  CdsTabsViewItem
} from '@central-design-system/components';
import { computed, nextTick, ref, watch } from 'vue';

const tab = ref('Сводка');
const visible = ref(['Сводка', 'Продажи', 'Закупки']);
const more = ref(['Логистика', 'Финансы', 'Персонал']);

const menu = ref(false);
let lastSection = tab.value;

const section = computed(() => (visible.value.includes(tab.value) ? tab.value : more.value[0]));

watch(tab, (value) => {
  if (visible.value.includes(value)) lastSection = value;
});

watch(menu, (open) => {
  if (!open && !visible.value.includes(tab.value)) tab.value = lastSection;
});

async function select(item: string) {
  const replaced = visible.value.shift();
  visible.value.push(item);
  more.value = more.value.filter((section) => section !== item);
  if (replaced) more.value.push(replaced);

  await nextTick();
  tab.value = item;
}
</script>

<template>
  <div class="m-auto max-w-[560px]">
    <CdsTabs v-model="tab">
      <CdsTab v-for="item in visible" :key="item" :value="item">{{ item }}</CdsTab>

      <CdsMenu v-if="more.length" v-model="menu">
        <template #activator="{ props }">
          <CdsTab append-icon="chevron-down" v-bind="props">Ещё</CdsTab>
        </template>

        <CdsList>
          <CdsListItem v-for="item in more" :key="item" :title="item" @click="select(item)" />
        </CdsList>
      </CdsMenu>
    </CdsTabs>

    <CdsTabsView :model-value="section" class="mt-2">
      <CdsTabsViewItem v-for="item in [...visible, ...more]" :key="item" :value="item">
        Показатели раздела «{{ item }}» за текущий квартал.
      </CdsTabsViewItem>
    </CdsTabsView>
  </div>
</template>
```

## API

### CdsTabs

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `align` | `"title" \| "start" \| "end" \| "center" \| undefined` | `'start'` | no | Alignment of the tabs inside the bar |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerActive` | `boolean \| undefined` | — | no | Forces the active component to be aligned to the center. |
| `color` | `string \| undefined` | — | no | Component color |
| `contentClass` | `any` | — | no | Adds classes to the slide group container |
| `contentStyle` | `any` | — | no | Adds inline styles to the slide group container |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `fixedTabs` | `boolean \| undefined` | — | no | Makes all tabs the same width regardless of the length of their labels |
| `grow` | `boolean \| undefined` | — | no | Stretches the tabs across the whole available width of the container |
| `height` | `string \| number \| undefined` | — | no | Height of the tab bar. A number is in pixels, a string takes any CSS unit |
| `hideSlider` | `boolean \| undefined` | — | no | Hides the underline indicator of the active tab |
| `inset` | `boolean \| undefined` | — | no | Styling with a background: the active tab is highlighted with a filled pill instead of an underline |
| `insetPadding` | `string \| number \| undefined` | — | no | Padding of the background in `inset` mode. A number is in pixels, a string takes any CSS unit |
| `insetRadius` | `string \| number \| undefined` | — | no | Corner radius of the background in `inset` mode. A number is in pixels, a string takes any CSS unit |
| `items` | `readonly TabItem[] \| undefined` | `[]` | no | List of tabs. A string or a number is a label, an object is a tab with arbitrary `CdsTab` props |
| `mandatory` | `boolean \| "force" \| undefined` | `'force'` | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `mobile` | `boolean \| null \| undefined` | `null` | no | Determines the display mode of the component: `true` renders it in mobile mode, `false` in desktop mode, `null` makes the mode depend on the current breakpoint. |
| `mobileBreakpoint` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | — | no | Sets the breakpoint at which the component switches to mobile mode. Accepts a number (for example, 600) or the name of a predefined breakpoint (`xs`, `sm`, `md`, `lg`, `xl`). |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `nextIcon` | `IconValue \| undefined` | `'chevron-right'` | no | Icon for the “next” button. |
| `prevIcon` | `IconValue \| undefined` | `'chevron-left'` | no | Icon for the “previous” button. |
| `required` | `boolean \| "force" \| undefined` | `'force'` | no | Requires at least one item to stay selected |
| `scrollToActive` | `boolean \| undefined` | `true` | no | When `true`, the container scrolls the active component into view whenever it changes. |
| `selectedClass` | `string \| undefined` | `'cds-tabs--selected'` | no | CSS class applied in the selected state |
| `showArrows` | `string \| boolean \| undefined` | — | no | Changes how the arrows are shown. By default the arrows appear on desktop devices when the container overflows and stay hidden on mobile devices. `true` also shows them on mobile on overflow, `desktop` always shows them on desktop, `mobile` always on mobile, `always` on both, and `never` disables the arrows. |
| `sliderTransition` | `"shift" \| "grow" \| "fade" \| undefined` | — | no | Animation of the underline indicator of the active tab |
| `sliderTransitionDuration` | `string \| number \| undefined` | — | no | Duration of the indicator animation in milliseconds. `0` disables the flight; by default it follows the motion scale |
| `spaced` | `"both" \| "start" \| "end" \| undefined` | — | no | Pushes the prepend and append slots apart to the edges of the button. |
| `stacked` | `boolean \| undefined` | — | no | Lays out the icon and the label of the tab vertically — the icon above the text |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: unknown]` | Fires when the tab is switched. Passes the value of the new active tab |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Tabs and content when they are declared by hand instead of the `items` prop |
| `item` | `CdsTabsSlot<any>` | Template for the tab content. The slot props carry the element from `items` |
| `next` | `any` | Button that scrolls the tab bar forward |
| `prev` | `any` | Button that scrolls the tab bar backward |
| `tab` | `CdsTabsSlot<any>` | Template for the tab label. The slot props carry the element from `items` |
| `view` | `any` | The whole tab content area — replaces the automatic `CdsTabsView` |

### CdsTab

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appearance` _(deprecated)_ | `"inverse" \| "primary" \| "secondary" \| "tertiary" \| "transparent" \| undefined` | — | no | Visual appearance of the component. Deprecated: use `variant` and `color` |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `block` | `boolean \| undefined` | — | no | Stretches the button to the full width of its container |
| `color` | `(string & {}) \| "neutral" \| "brand" \| "accent" \| "danger" \| "inverse" \| undefined` | `'brand'` | no | Component color: a role, a palette alias, a theme token or a CSS color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `fixed` | `boolean \| undefined` | — | no | Fixes the width of the tab so it does not stretch to the length of its label |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `hideSlider` | `boolean \| undefined` | — | no | Hides the underline indicator of the active tab |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `icon` | `boolean \| IconValue \| undefined` | — | no | Icon to display; the component renders as an icon-only button |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `selectedClass` | `string \| undefined` | `'cds-tab--selected'` | no | CSS class applied in the selected state |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `sliderTransition` | `"shift" \| "grow" \| "fade" \| undefined` | — | no | Animation of the underline indicator of the active tab |
| `sliderTransitionDuration` | `string \| number \| undefined` | — | no | Duration of the indicator animation in milliseconds. `0` disables the flight; by default it follows the motion scale |
| `spaced` | `"both" \| "start" \| "end" \| undefined` | — | no | Pushes the prepend and append slots apart to the edges of the button. |
| `stacked` | `boolean \| undefined` | — | no | Stacks the icon above the text instead of placing them side by side |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'button'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `value` | `any` | — | no | Value of the component within the group |
| `variant` | `"solid" \| "soft" \| "outline" \| "surface" \| "ghost" \| undefined` | `'solid'` | no | Component variant: `solid`, `soft`, `outline`, `surface`, `ghost` |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `any` | Content after the text |
| `default` | `any` | Content inside the button |
| `loader` | `any` | Loading indicator |
| `prepend` | `any` | Content before the text |

### CdsTabsView

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `crossfade` | `boolean \| undefined` | — | no | Slides change with a smooth crossfade instead of a shift |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `reverse` | `boolean \| undefined` | — | no | Inverts the direction of the transition animation between slides |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transitionDuration` | `number \| undefined` | — | no | Duration of the transition animation between slides, in milliseconds |
| `verticalArrows` | `boolean \| "left" \| "right" \| undefined` | — | no | Places the navigation arrows vertically: `'left'` or `'right'` — the side, `true` — the default side |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: any]` | Fires when the shown content changes. Passes the value of the new active tab |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `additional` | `{ group: GroupProvide; }` | Extra content above the slides — indicator dots or your own navigation, for example |
| `default` | `{ group: GroupProvide; }` | Slides. The slot props carry the group state for controlling the active slide |
| `next` | `{ props: ControlProps; }` | Button that moves to the next slide. The slot props are ready to bind to your own button |
| `prev` | `{ props: ControlProps; }` | Button that moves to the previous slide. The slot props are ready to bind to your own button |

### CdsTabsViewItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `reverseTransition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the reverse direction. A transition component name, or `false` to turn the animation off |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `transition` | `string \| boolean \| undefined` | — | no | Transition used when the slide appears in the forward direction. A transition component name, or `false` to turn the animation off |
| `value` | `any` | — | no | Value of the component within the group |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the slide |

---

# CdsTag

_Category: Content · since 4.0.0_

_Tests: API 41/41 · 67 unit · 5 known bugs · lines 96.5% (v4.0.0-alpha.13) · a11y: 2 axe recommendations (v4.0.0-alpha.11)_

A tag is a compact label next to an object: the status of a request, a product category, a selected filter. It takes a color from the palette, carries an icon or an avatar, can be closed with a cross and can work as a link.

**See also:** To build a toggle or a filter with selection out of tags, take CdsTagGroup. For a counter or a dot indicator on top of another element use CdsBadge, and trigger actions with CdsButton — a tag only labels.

## Anatomy

A tag consists of a container and content areas: `prepend` and `append` carry an
icon or an avatar, the text lives in the center, and the close button appears
with `closable`.

## Variations

### Colors

The `color` prop paints the tag in one of the 11 palette aliases; without it the
tag stays neutral gray. The text color can be overridden with `text-color` when
needed. The `disabled` prop swaps the tag colors for the service colors of the
disabled state and removes the reaction to clicks.

**Example — `Colors.vue`:**

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

const colors = CdsTag.constants.colors;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsTag v-for="color in colors" :key="color" :text="color" :color="color" />
  </div>
</template>
```

### Sizes

The `size` prop offers five sizes from `xs` to `xl`. The default size is `md`.

**Example — `Sizes.vue`:**

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

const sizes = CdsTag.constants.sizes;
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTag v-for="size in sizes" :key="size" :text="size" :size="size" />
  </div>
</template>
```

### Shape

The `pill` prop rounds the corners completely — this shape emphasizes that the
label stands on its own and looks good in a tag cloud.

**Example — `Pill.vue`:**

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

<template>
  <div class="flex justify-center gap-2">
    <CdsTag text="Обычный тег" />
    <CdsTag pill text="Тег pill" />
  </div>
</template>
```

### Icons and avatars

The `prepend-icon` and `append-icon` props add an icon before and after the
text, `prepend-avatar` and `append-avatar` add a round avatar. The size of the
icon and the avatar follows the size of the tag.

**Example — `Icons.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTag prepend-icon="star" text="Избранное" />
    <CdsTag append-icon="external-link" text="b2b-center.ru" />
    <CdsTag prepend-avatar="https://i.pravatar.cc/80?img=12" text="Анна Ветрова" pill />
  </div>
</template>
```

### Slots

Slots replace the content coming from props when you need full control over the
markup.

| Slot      | Description                                                                         |
| --------- | ----------------------------------------------------------------------------------- |
| `default` | Content of the tag. Replaces the text from `text`                                   |
| `prepend` | Content before the text. Replaces `prepend-icon` / `prepend-avatar`                 |
| `append`  | Content after the text. Replaces `append-icon` / `append-avatar`                    |
| `close`   | Content of the close button. Replaces the icon from `close-icon`                    |
| `filter`  | Content of the selection indicator in a group. Replaces the icon from `filter-icon` |

**Example — `Slots.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsTag color="green">Скидка <b>−20%</b></CdsTag>
    <CdsTag text="Избранное">
      <template #prepend>
        <CdsIcon icon="star-fill" start />
      </template>
    </CdsTag>
    <CdsTag text="Черновик" closable>
      <template #close>
        <CdsIcon icon="delete" />
      </template>
    </CdsTag>
  </div>
</template>
```

### Link tag

Pass `href` (or `to` with a `RouteLocationRaw` object from vue-router) and the
tag renders as an `a` tag: it gets a cursor, keyboard focus and navigation on
Enter, keeping the look of a tag.

**Example — `AsLink.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsTag href="https://www.b2b-center.ru" target="_blank" append-icon="external-link" text="b2b-center.ru" />
    <CdsTag href="#" pill text="vue" />
    <CdsTag href="#" pill text="design-system" />
  </div>
</template>
```

### Closing

The `closable` prop (or its alias `removable`) adds a close button. A click on it
hides the tag and emits the `click:close` event, and the visibility can be
controlled from the outside through `v-model`. The `close-icon` prop changes the
icon of the button, `close-label` changes the accessible label.

**Example — `Closable.vue`:**

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

const visible = ref(true);
</script>

<template>
  <div class="flex items-center justify-center gap-4">
    <CdsTag v-model="visible" closable text="Закрываемый тег" />
    <CdsButton v-if="!visible" variant="soft" color="brand" size="sm" text="Вернуть тег" @click="visible = true" />
  </div>
</template>
```

### Selection in a group

Inside CdsTagGroup a tag becomes a toggle: `value`
sets its value in the group, the selected state is marked with the
`cds-tag--selected` class, and the `group:selected` event reports the change of
selection. With `filter` the selected tag gets an indicator — `filter-icon`
changes the icon, the `filter` slot changes the whole markup. The `default` slot
exposes `isSelected`, `toggle` and `select` — a handy base for your own tag
markup.

The color of the selected tag comes from `active-color`: without it the group
itself paints the selection with the brand color, and `color` stays the color of
the unselected tag.

**Example — `InGroup.vue`:**

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

const statuses = ['Черновики', 'На проверке', 'Опубликованные'];
const selected = ref('На проверке');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" filter>
      <CdsTag v-for="status in statuses" :key="status" :value="status" :text="status" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected ?? '—' }}</span>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A label is one or two words: it reads at a glance and does not break the line. | A long phrase turns the label into a sentence and gets cut off on narrow screens. |
| Tie a color to a meaning: one status — one color across the whole interface. | Random colors make people guess whether the coloring means anything at all. |
| A tag labels an object, while the action stays with the button. | A tag named after an action looks clickable but does nothing. |

## Scenarios

### Selected filters

Applied search filters read well as a row of closable tags: each tag removes its
own filter on `click:close`, and the neighboring `tertiary` button resets
everything at once.

**Example — `SelectedFilters.vue`:**

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

const initial = ['Электроника', 'До 10 000 ₽', 'В наличии', 'Доставка завтра', 'Рейтинг 4+'];
const filters = ref([...initial]);

const remove = (filter: string) => {
  filters.value = filters.value.filter((item) => item !== filter);
};
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTag v-for="filter in filters" :key="filter" :text="filter" closable @click:close="remove(filter)" />
    <CdsButton
      v-if="filters.length"
      variant="soft"
      color="neutral"
      size="sm"
      text="Сбросить всё"
      @click="filters = []"
    />
    <CdsButton v-else variant="soft" color="brand" size="sm" text="Вернуть фильтры" @click="filters = [...initial]" />
  </div>
</template>
```

### Record statuses

In lists and tables a colored tag shows the state of a record instantly. Assign
colors to statuses once: `green` — success, `lemon` — pending, `red` —
rejection, `neutral` — draft. The compact `size="sm"` does not compete with the
text of the row.

**Example — `Statuses.vue`:**

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

const requests = [
  { id: 4821, title: 'Закупка ноутбуков', status: 'Согласована', color: 'green' },
  { id: 4820, title: 'Ремонт офиса', status: 'На рассмотрении', color: 'lemon' },
  { id: 4819, title: 'Аренда склада', status: 'Отклонена', color: 'red' },
  { id: 4818, title: 'Поставка канцелярии', status: 'Черновик', color: 'neutral' }
];
</script>

<template>
  <div class="flex flex-col gap-2 w-[360px] m-auto">
    <div v-for="request in requests" :key="request.id" class="flex items-center justify-between gap-4">
      <span>{{ request.title }}</span>
      <CdsTag :text="request.status" :color="request.color" size="sm" />
    </div>
  </div>
</template>
```

### Adding labels

An input field together with tags makes a label editor: Enter adds a new label,
the cross (`closable` + `click:close`) removes an extra one. Duplicates are cut
off before they get into the list.

**Example — `TagInput.vue`:**

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

const input = ref('');
const tags = ref(['vue', 'design-system']);

const add = () => {
  const value = input.value.trim();

  if (value && !tags.value.includes(value)) {
    tags.value.push(value);
  }

  input.value = '';
};

const remove = (tag: string) => {
  tags.value = tags.value.filter((item) => item !== tag);
};
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsTextInput v-model="input" label="Метки" placeholder="Введите метку и нажмите Enter" @keydown.enter="add" />
    <div class="flex flex-wrap gap-2">
      <CdsTag v-for="tag in tags" :key="tag" :text="tag" closable @click:close="remove(tag)" />
    </div>
  </div>
</template>
```

## API

### CdsTag

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeClass` | `string \| undefined` | — | no | CSS class applied to the active (selected) link tag. |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendAvatar` | `string \| undefined` | — | no | Avatar displayed after (to the right of) the tag content. |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon displayed after (to the right of) the tag content. |
| `closable` | `boolean \| undefined` | — | no | Adds a close button that hides the tag. |
| `closeIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the close button. |
| `closeLabel` | `string \| undefined` | `'$cds.close'` | no | Accessible label (aria-label) for the close button. |
| `color` | `string \| undefined` | — | no | Component color |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `draggable` | `boolean \| undefined` | — | no | Makes the tag draggable (native drag-and-drop). |
| `exact` | `boolean \| undefined` | — | no | If true, the active state applies only on an exact route match |
| `filter` | `boolean \| undefined` | — | no | Shows the selection indicator icon when the tag is used inside a group (CdsTagGroup). |
| `filterIcon` | `IconValue \| undefined` | `'check'` | no | Icon of the selection indicator (relevant together with `filter`). |
| `href` | `string \| undefined` | — | no | The `href` attribute of the link. When set, the component behaves as a regular link |
| `label` | `boolean \| undefined` | — | no | Applies the “label” style with a smaller corner radius. |
| `link` | `boolean \| undefined` | — | no | Gives the tag the styles and the behavior of a link. |
| `modelValue` | `boolean \| undefined` | `true` | no | Visibility of the tag (v-model). When `false` the tag is not rendered. |
| `pill` | `boolean \| undefined` | — | no | Makes the corners of the tag fully rounded. |
| `prependAvatar` | `string \| undefined` | — | no | Avatar displayed before (to the left of) the tag content. |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon displayed before (to the left of) the tag content. |
| `removable` | `boolean \| undefined` | — | no | Adds a remove button (alias for `closable`). |
| `replace` | `boolean \| undefined` | — | no | If true, navigation replaces the current history entry instead of pushing a new one |
| `selectedClass` | `string \| undefined` | — | no | CSS class applied in the selected state |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'span'` | no | Custom HTML tag or component to render |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `to` | `LinkTo \| undefined` | — | no | Target route or route location object for RouterLink. When set, the component behaves as a RouterLink |
| `value` | `any` | — | no | Value of the component within the group |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click` | `[e: MouseEvent \| KeyboardEvent]` | Click on the tag (with a mouse or from the keyboard). |
| `click:close` | `[e: MouseEvent]` | Click on the close button of the tag. |
| `group:selected` | `[value: { value: boolean; }]` | Change of the tag selection state inside a group. |
| `update:modelValue` | `[value: boolean]` | Change of the tag visibility (v-model). |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `any` | Content after the main content (in place of the append icon/avatar). |
| `close` | `any` | Custom content of the close button. |
| `default` | `{ isSelected: boolean \| undefined; selectedClass: boolean \| (string \| undefined)[] \| undefined; select: ((value: boolean) => void) \| undefined; toggle: (() => void) \| undefined; value: unknown; disabled: boolean; }` | Default content of the tag. The slot props expose the group state (selection, toggling). |
| `filter` | `any` | Custom content of the selection indicator (relevant together with `filter`). |
| `label` | `any` | Content of the tag label. |
| `prepend` | `any` | Content before the main content (in place of the prepend icon/avatar). |

---

# CdsTagGroup

_Category: Content · since 4.0.0 · status: new_

_Tests: API 30/30 · 39 unit · lines 100% (v4.0.0-alpha.13) · a11y: 13 axe recommendations (v4.0.0-alpha.11)_

A tag group turns a set of CdsTag into a toggle: the selected tag is highlighted, the value is available through `v-model`, and the tags that do not fit move into a horizontal scroll. Fits catalog filters, category pickers and quick period switches.

**See also:** If the choice should look like buttons, take CdsButtonToggle. For a choice out of a long list use CdsSelect, and for separate independent tags without selection just use CdsTag.

## Variations

### Selection

Give every tag a `value` — exactly this value lands in `v-model`. Without
`value` the index of the tag in the group becomes its value. A repeated click on
the selected tag clears the selection.

**Example — `Default.vue`:**

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

const categories = ['Электроника', 'Одежда', 'Мебель', 'Спорт', 'Книги'];
const selected = ref('Электроника');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected">
      <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected ?? '—' }}</span>
  </div>
</template>
```

### Multiple selection

The `multiple` prop allows selecting several tags — `v-model` becomes an array
of values.

**Example — `Multiple.vue`:**

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

const deliveries = ['Самовывоз', 'Курьер', 'Почта', 'Транспортная компания'];
const selected = ref(['Курьер', 'Почта']);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" multiple>
      <CdsTag v-for="delivery in deliveries" :key="delivery" :value="delivery" :text="delivery" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected.join(', ') || '—' }}</span>
  </div>
</template>
```

The `max` prop limits the number of selected tags: once the limit is reached,
clicks on the remaining tags do not add to the selection.

**Example — `Max.vue`:**

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

const deliveries = ['Самовывоз', 'Курьер', 'Почта', 'Транспортная компания'];
const selected = ref(['Курьер']);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" multiple :max="2">
      <CdsTag v-for="delivery in deliveries" :key="delivery" :value="delivery" :text="delivery" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано {{ selected.length }} из 2</span>
  </div>
</template>
```

### Mandatory selection

The `mandatory` prop does not let you clear the last selection: a tag can only
be switched. With the `'force'` value the first available tag is selected
automatically, even when `v-model` is empty.

**Example — `Mandatory.vue`:**

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

const periods = ['Неделя', 'Месяц', 'Квартал', 'Год'];
const selected = ref('Месяц');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" mandatory>
      <CdsTag v-for="period in periods" :key="period" :value="period" :text="period" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">
      Период: {{ selected }} — снять выбор нельзя, можно только переключить
    </span>
  </div>
</template>
```

### Selection indicator

The `filter` prop adds a check icon to the selected tags — the selection reads
not only from the fill. The `filter-icon` prop of the tag changes the icon, and
the `filter` slot replaces it with your own markup.

**Example — `Filter.vue`:**

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

const statuses = ['Черновики', 'На проверке', 'Опубликованные', 'В архиве'];
const selected = ref(['На проверке']);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTagGroup v-model="selected" multiple filter>
      <CdsTag v-for="status in statuses" :key="status" :value="status" :text="status" />
    </CdsTagGroup>

    <span class="text-100 text-content-secondary">Выбрано: {{ selected.join(', ') || '—' }}</span>
  </div>
</template>
```

### Color and disabling

The group passes the `color`, `active-color`, `disabled` and `filter` props to
its tags as defaults — there is no need to repeat them on every tag. `color`
paints the unselected tags, `active-color` paints the selected one; without it
the selected tag stays in the brand color so that the selection reads with any
palette. `disabled` blocks the whole group: the selection is visible but cannot
be switched. A prop set directly on a tag wins over the value of the group.

**Example — `TagDefaults.vue`:**

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

const formats = ['Отчёт', 'Презентация', 'Таблица'];
const colored = ref('Отчёт');
const active = ref('Отчёт');
const locked = ref('Презентация');
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">color — цвет невыбранных тегов</span>

      <CdsTagGroup v-model="colored" color="red">
        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
      </CdsTagGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">active-color — цвет выбранного тега</span>

      <CdsTagGroup v-model="active" color="green" active-color="red">
        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
      </CdsTagGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-100 text-content-secondary">disabled — выбор сохраняется, но недоступен</span>

      <CdsTagGroup v-model="locked" disabled>
        <CdsTag v-for="format in formats" :key="format" :value="format" :text="format" />
      </CdsTagGroup>
    </div>
  </div>
</template>
```

### Layout

By default the tags stand in a single row, and the extra ones move into a
horizontal scroll with arrows: the group is built on
CdsSlideGroup and accepts its props —
`show-arrows`, `direction`, `center-active`. The `column` prop wraps the tags
into rows instead of scrolling — that way all the options are visible at once.

**Example — `Column.vue`:**

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

const categories = ['Электроника', 'Бытовая техника', 'Одежда', 'Обувь', 'Мебель', 'Спорт', 'Книги', 'Игрушки'];

const scrolled = ref('Электроника');
const wrapped = ref('Электроника');
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-1 text-content-secondary">По умолчанию — горизонтальная прокрутка со стрелками</span>

      <CdsTagGroup v-model="scrolled">
        <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
      </CdsTagGroup>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-1 text-content-secondary">column — перенос по строкам</span>

      <CdsTagGroup v-model="wrapped" column>
        <CdsTag v-for="category in categories" :key="category" :value="category" :text="category" />
      </CdsTagGroup>
    </div>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| One group — one attribute: the values exclude each other and read as a row of equals. | Different attributes in one group: you cannot pick a category and a price at the same time. |
| In a narrow block use column: all the options are visible at once. | A horizontal scroll in a narrow column hides half of the options behind an arrow. |
| A tag group holds a few popular values — they are visible without expanding anything. | Dozens of values turn into a tag cloud: picking from such a list is more convenient in CdsSelect. |

## Scenarios

### Catalog filter

A row of categories above the results is the most common job for a tag group.
`column` shows all the categories at once, `mandatory` prevents ending up
without a filter, and `v-model` gives you a ready key for the product request.

**Example — `CatalogFilter.vue`:**

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

const products = [
  { name: 'Ноутбук Alfa 14', category: 'Ноутбуки', price: '68 900 ₽' },
  { name: 'Ноутбук Beta Pro', category: 'Ноутбуки', price: '94 500 ₽' },
  { name: 'Смартфон Gamma 5', category: 'Смартфоны', price: '32 400 ₽' },
  { name: 'Смартфон Delta Mini', category: 'Смартфоны', price: '21 900 ₽' },
  { name: 'Монитор Epsilon 27"', category: 'Мониторы', price: '27 300 ₽' }
];

const categories = ['Все', 'Ноутбуки', 'Смартфоны', 'Мониторы'];
const category = ref('Все');

const filtered = computed(() =>
  category.value === 'Все' ? products : products.filter((product) => product.category === category.value)
);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsTagGroup v-model="category" column mandatory>
      <CdsTag v-for="item in categories" :key="item" :value="item" :text="item" />
    </CdsTagGroup>

    <div class="flex flex-col gap-1">
      <div
        v-for="product in filtered"
        :key="product.name"
        class="flex items-center justify-between rounded-200 bg-surface-secondary p-2"
      >
        <span>{{ product.name }}</span>
        <span class="text-100 text-content-secondary">{{ product.price }}</span>
      </div>
    </div>

    <span class="text-100 text-content-secondary">Найдено товаров: {{ filtered.length }}</span>
  </div>
</template>
```

### Picking several topics

When the values do not exclude each other, turn on `multiple`. `max` keeps the
selection within reasonable bounds, `filter` marks the selected topics with a
check, and the hint under the group explains the limit.

**Example — `Interests.vue`:**

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

const topics = ['Аналитика', 'Дизайн', 'Разработка', 'Маркетинг', 'Продажи', 'Логистика', 'Поддержка'];
const selected = ref(['Дизайн']);

const isFull = computed(() => selected.value.length >= 3);
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <span>Выберите до трёх тем — по ним будем присылать дайджест</span>

    <CdsTagGroup v-model="selected" column multiple filter :max="3">
      <CdsTag v-for="topic in topics" :key="topic" :value="topic" :text="topic" />
    </CdsTagGroup>

    <span class="text-100" :class="isFull ? 'text-content-secondary' : 'text-content-tertiary'">
      {{ isFull ? 'Лимит достигнут — снимите тему, чтобы выбрать другую' : `Выбрано ${selected.length} из 3` }}
    </span>
  </div>
</template>
```

### Switching the period

The group exposes the `next`, `prev` and `select` methods and the `selected`
list — get them through a `ref` on the component. This is how tags get the
back / forward arrows that walk through the periods in order.

**Example — `PeriodStepper.vue`:**

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

const revenue: Record<string, string> = {
  'I квартал': '1,2 млн ₽',
  'II квартал': '1,8 млн ₽',
  'III квартал': '2,4 млн ₽',
  'IV квартал': '3,1 млн ₽'
};

const quarters = Object.keys(revenue);
const quarter = ref('II квартал');
const group = ref<InstanceType<typeof CdsTagGroup> | null>(null);
</script>

<template>
  <div class="m-auto flex w-[420px] flex-col items-center gap-2">
    <div class="flex items-center gap-1">
      <CdsFunctionalButton icon="chevron-left" aria-label="Предыдущий квартал" @click="group?.prev()" />

      <CdsTagGroup ref="group" v-model="quarter" mandatory>
        <CdsTag v-for="item in quarters" :key="item" :value="item" :text="item" />
      </CdsTagGroup>

      <CdsFunctionalButton icon="chevron-right" aria-label="Следующий квартал" @click="group?.next()" />
    </div>

    <div class="flex w-full flex-col items-center rounded-200 bg-surface-secondary p-4">
      <span class="text-900">{{ revenue[quarter] }}</span>
      <span class="text-content-secondary">выручка за {{ quarter.toLowerCase() }}</span>
    </div>
  </div>
</template>
```

## API

### CdsTagGroup

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `centerActive` | `boolean \| undefined` | — | no | Forces the active component to be aligned to the center. |
| `color` | `string \| undefined` | — | no | Component color |
| `column` | `boolean \| undefined` | — | no | Lays the tags out in several rows with wrapping instead of a horizontal scroll. |
| `contentClass` | `any` | — | no | Adds classes to the slide group container |
| `contentStyle` | `any` | — | no | Adds inline styles to the slide group container |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `filter` | `boolean \| undefined` | — | no | Shows a check icon on the selected tags (passed down to `CdsTag`). |
| `mandatory` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `max` | `number \| undefined` | — | no | Maximum number of items that can be selected |
| `mobile` | `boolean \| null \| undefined` | `null` | no | Determines the display mode of the component: `true` renders it in mobile mode, `false` in desktop mode, `null` makes the mode depend on the current breakpoint. |
| `mobileBreakpoint` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | — | no | Sets the breakpoint at which the component switches to mobile mode. Accepts a number (for example, 600) or the name of a predefined breakpoint (`xs`, `sm`, `md`, `lg`, `xl`). |
| `modelValue` | `any` | — | no | Value of the selected items of the group |
| `multiple` | `boolean \| undefined` | — | no | Allows selecting several items at once |
| `nextIcon` | `IconValue \| undefined` | `'chevron-right'` | no | Icon for the “next” button. |
| `prevIcon` | `IconValue \| undefined` | `'chevron-left'` | no | Icon for the “previous” button. |
| `required` | `boolean \| "force" \| undefined` | — | no | Requires at least one item to stay selected |
| `scrollToActive` | `boolean \| undefined` | `false` | no | When `true`, the container scrolls the active component into view whenever it changes. |
| `selectedClass` | `string \| undefined` | `'cds-tag--selected'` | no | CSS class applied in the selected state |
| `showArrows` | `string \| boolean \| undefined` | — | no | Changes how the arrows are shown. By default the arrows appear on desktop devices when the container overflows and stay hidden on mobile devices. `true` also shows them on mobile on overflow, `desktop` always shows them on desktop, `mobile` always on mobile, `always` on both, and `never` disables the arrows. |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'div'` | no | Custom HTML tag or component to render |
| `theme` | `string \| undefined` | — | no | Component theme |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: unknown]` | Fires when the selected value changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `CdsTagGroupSlotProps` | Tags of the group. The slot props expose the group state (selection, navigation). |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isSelected` | `(id: string) => boolean` | Check whether a tag with the given id is selected |
| `next` | `() => void` | Select the next tag |
| `prev` | `() => void` | Select the previous tag |
| `select` | `(id: string, value: boolean) => void` | Select a tag by id |
| `selected` | `readonly string[]` | Ids of the selected tags |

---

# CdsTextArea

_Category: Controls · since 4.0.0_

_Tests: API 85/85 · 95 unit · 2 e2e · 9 known bugs · lines 97.9% (v4.0.0-alpha.13) · a11y: 4 axe recommendations (v4.0.0-alpha.11)_

A text area is a field for multiline text: a comment, a description, a support request. Around the native `textarea` the component gathers everything a form needs: a label, a description, hints, error messages, clearing and a character counter, and with `auto-grow` it grows together with the text.

**See also:** For a short single-line value use CdsTextInput, to pick from a ready list of options — CdsSelect.

## Anatomy

On top are the label and the description, in the center is the multiline field
with the clear button, under the field are the messages line and the character
counter. The structure matches CdsTextInput: the
same `prepend` / `append` zones outside and inside the border are available — as
`*-icon` props and as slots of the same name.

## Variations

### Label and description

The `label` prop names the field, `description` adds a supporting text under the
label. The slots of the same name accept arbitrary markup.

**Example — `Default.vue`:**

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

<template>
  <CdsTextArea
    label="Заголовок"
    description="Описание для элемента формы или вспомогательный текст"
    placeholder="Введите текст"
    class="max-w-sm m-auto"
  />
</template>
```

### Number of rows

The `rows` prop sets the height of the area in rows — 5 by default. Choose the
height to match the expected length of the answer: two or three rows are enough
for a comment.

**Example — `Rows.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextArea label="rows: 2" :rows="2" placeholder="Введите текст" />
    <CdsTextArea label="rows: 5 (по умолчанию)" placeholder="Введите текст" />
    <CdsTextArea label="rows: 8" :rows="8" placeholder="Введите текст" />
  </div>
</template>
```

### Automatic height

The `auto-grow` prop increases the height of the area as you type — the text does
not have to be scrolled. `max-rows` limits the growth by a number of rows,
`max-height` — by a height in pixels; beyond that a scrollbar appears.

**Example — `AutoGrow.vue`:**

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

const value = ref('Съешь ещё этих мягких французских булок,\nда выпей чаю.');
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsTextArea v-model="value" label="autoGrow" auto-grow :rows="2" placeholder="Начните вводить текст" />
    <CdsTextArea
      v-model="value"
      label="autoGrow + maxRows: 4"
      auto-grow
      :rows="2"
      :max-rows="4"
      placeholder="Начните вводить текст"
    />
  </div>
</template>
```

### Resizing

By default the user can stretch the area by its bottom right corner. The
`no-resize` prop turns that off; with `auto-grow` manual resizing is disabled
automatically.

**Example — `NoResize.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextArea label="Обычная область (resize доступен)" :rows="3" placeholder="Введите текст" />
    <CdsTextArea label="noResize" no-resize :rows="3" placeholder="Введите текст" />
  </div>
</template>
```

### Clearing

The `clearable` prop shows the clear icon on hover or focus,
`persistent-clearable` keeps it visible at all times.

**Example — `Clearable.vue`:**

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

const value = ref('Очисти меня!');
</script>

<template>
  <CdsTextArea
    v-model="value"
    placeholder="Введите значение"
    hint="Это поле можно очистить"
    clearable
    persistent-clearable
    :rows="3"
    class="max-w-sm m-auto"
  />
</template>
```

### Counter

The `counter` prop shows a character counter: `true` — without a limit, a number
— with a limit. `counter-value` accepts your own counting formula,
`persistent-counter` keeps the counter visible outside of focus. To make the
limit impossible to exceed, add the `maxlength` attribute.

**Example — `Counter.vue`:**

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

const wordCount = (value: unknown) => (value ?? '').toString().trim().split(/\s+/).filter(Boolean).length;
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsTextArea label="counter true" placeholder="Просто счётчик" counter :rows="3" />
    <CdsTextArea label="counter с лимитом" placeholder="До 200 символов" counter="200" maxlength="200" :rows="3" />
    <CdsTextArea label="persistentCounter" placeholder="Счётчик всегда виден" counter persistent-counter :rows="3" />
    <CdsTextArea
      label="counterValue (слова)"
      placeholder="Считаем слова"
      counter
      :counter-value="wordCount"
      :rows="3"
    />
  </div>
</template>
```

### States

`disabled` blocks the input and lowers the contrast, `readonly` forbids changes
but keeps focus and copying, `loading` shows a loading indicator — as a bar or as
a circle (`loading="circle"`).

**Example — `States.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextArea label="Disabled" model-value="Значение" :rows="2" disabled />
    <CdsTextArea label="Readonly" model-value="Только для чтения" :rows="2" readonly />
    <CdsTextArea label="Loading" model-value="Загрузка" :rows="2" loading />
    <CdsTextArea label="Loading circle" model-value="Загрузка" :rows="2" loading="circle" />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The height of the area hints at the expected length: two or three rows are enough for a comment. | An area too tall for a short answer looks like a demand to write an essay. |
| A counter with a limit shows the restriction upfront, and maxlength keeps it from being exceeded. | An error after the input forces the user to cut down text that is already written. |
| For a short single-line value use a text field. | A text area for the subject of a request takes up space and hints at a long answer. |

## Scenarios

### Sending a request

The form is made of `CdsForm`, a short subject in a text field and the message in
a text area. The `rules` prop checks that the message is detailed enough, and
`counter` together with `maxlength` show the limit upfront. The button gets
`loading` for the duration of the request.

**Example — `FeedbackForm.vue`:**

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

const subject = ref('');
const message = ref('');
const loading = ref(false);
const sent = ref(false);

const rules = {
  subject: [(value: string) => !!value || 'Введите тему обращения'],
  message: [
    (value: string) => !!value || 'Опишите вопрос',
    (value: string) => value.trim().length >= 20 || 'Расскажите подробнее — не меньше 20 символов'
  ]
};

async function onSubmit(event: SubmitEventPromise) {
  sent.value = false;

  const { valid } = await event;

  if (!valid) return;

  loading.value = true;

  setTimeout(() => {
    loading.value = false;
    sent.value = true;
  }, 1500);
}
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="onSubmit">
    <CdsTextInput v-model="subject" :rules="rules.subject" label="Тема" placeholder="Кратко о сути вопроса" />
    <CdsTextArea
      v-model="message"
      :rules="rules.message"
      label="Сообщение"
      placeholder="Что случилось и как это воспроизвести"
      :rows="4"
      counter="500"
      maxlength="500"
    />
    <div class="mt-2">
      <CdsButton :loading="loading" type="submit">Отправить</CdsButton>
    </div>
    <div v-if="sent" class="text-sm text-content-secondary">Сообщение отправлено — ответим в течение дня.</div>
  </CdsForm>
</template>
```

### A comment in a discussion

A compact comment field: `rows="1"` and `auto-grow` with `max-rows` — the area
starts with a single row and grows together with the text, `hide-details` removes
the bottom block. The send button is a `CdsFunctionalButton` in the `append-inner`
slot; Enter sends the comment, Shift+Enter inserts a line break.

**Example — `CommentReply.vue`:**

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

const draft = ref('');
const comments = ref(['Отличная идея, поддерживаю.']);

const send = () => {
  const text = draft.value.trim();

  if (!text) return;

  comments.value.push(text);
  draft.value = '';
};
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-3 m-auto">
    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="(comment, index) in comments" :key="index">{{ comment }}</li>
    </ul>

    <CdsTextArea
      v-model="draft"
      placeholder="Написать комментарий"
      auto-grow
      :rows="1"
      :max-rows="6"
      hide-details
      @keydown.enter.exact.prevent="send"
    >
      <template #append-inner>
        <CdsFunctionalButton icon="arrow-up" aria-label="Отправить комментарий" @click="send" />
      </template>
    </CdsTextArea>
  </div>
</template>
```

### An error from the server

The server response goes into `error-messages` as is — validation through `rules`
is not needed for that. Reset the error when the value changes, so that the field
does not complain about a text that is already fixed.

**Example — `ServerError.vue`:**

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

const description = ref('Надёжная компания, подробности на example.com');
const loading = ref(false);
const serverErrors = ref<string[]>([]);

const publish = async () => {
  loading.value = true;
  serverErrors.value = [];

  // Имитация ответа сервера
  await new Promise((resolve) => setTimeout(resolve, 1000));

  loading.value = false;
  serverErrors.value = ['Уберите ссылки из описания — модерация их не пропустит'];
};
</script>

<template>
  <form class="flex w-full max-w-md flex-col gap-4 m-auto" @submit.prevent="publish">
    <CdsTextArea
      v-model="description"
      label="Описание компании"
      :rows="3"
      :error-messages="serverErrors"
      @update:model-value="serverErrors = []"
    />

    <CdsButton class="self-start" type="submit" text="Опубликовать" :loading="loading" />
  </form>
</template>
```

## API

### CdsTextArea

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the field |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
| `autocomplete` | `string \| undefined` | — | no | 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` | — | no | Enables autofocus |
| `autoGrow` | `boolean \| undefined` | — | no | Automatic growth of the text area height as you type |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
| `color` | `string \| undefined` | — | no | Component color |
| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum height of the text area |
| `maxRows` | `string \| number \| undefined` | — | no | Maximum number of rows while the height grows automatically |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | The v-model modifiers passed by Vue to process the field value |
| `modelValue` | `any` | — | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `noResize` | `boolean \| undefined` | — | no | Turn off the ability to resize the text area |
| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
| `rows` | `string \| number \| undefined` | `5` | no | Number of rows of the text area |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:control` | `[e: MouseEvent]` | Fires on a click in the main area of the control |
| `mousedown:control` | `[e: MouseEvent]` | Fires on a mouse button press in the main area of the control |
| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus |
| `update:modelValue` | `[value: string]` | Fires when the model of the component changes |
| `update:rows` | `[rows: number]` | Fires when the computed number of rows changes while the height grows automatically |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
| `counter` | `CdsCounterSlot` | Slot for a custom counter |
| `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 |
| `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). |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |
| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
| `fieldIconColor` | `string \| undefined` | Icon color |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsTextInput

_Category: Controls · since 4.0.0_

_Tests: API 87/87 · 86 unit · 3 e2e · 6 known bugs · lines 97.2% (v4.0.0-alpha.13) · a11y: 12 axe recommendations (v4.0.0-alpha.11)_

A text field is the basic way to get data from the user: a name, an email, an amount, a search query. Around the native `input` the component gathers everything a form needs: a label, a description, hints, error messages, icons, clearing and a character counter.

**See also:** For multiline text use CdsTextArea, to pick from a ready list of options use CdsSelect.

## Anatomy

The first diagram shows the frame of the component: the label, the description,
the field and the bottom block with messages and the counter. The second one
shows how the field itself is built: the `prepend` and `append` zones outside
the border, `prepend-inner` and `append-inner` inside it, and the clear button.
Every zone is available both as a `*-icon` prop and as a slot of the same name.

## Variations

### Label and description

The `label` prop names the field, `description` adds a supporting text under the
label. The slots of the same name accept arbitrary markup.

**Example — `LabelAndDescription.vue`:**

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

<template>
  <CdsTextInput
    label="Заголовок"
    description="Описание для элемента формы или вспомогательный текст"
    placeholder="Введите текст"
    class="max-w-sm m-auto"
  />
</template>
```

### Messages and hints

There is a single text line under the field, and props split it by state:
`messages` is visible at rest, `hint` — on focus, `error-messages` — on an error
and on top of the rest. The `messages` and `details` slots override the content.

**Example — `HintAndMessages.vue`:**

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

<template>
  <CdsTextInput
    label="Заголовок"
    placeholder="Введите текст"
    hint="Сообщение подсказка"
    messages="Пользовательское сообщение"
    class="max-w-sm m-auto"
  />
</template>
```

### Hiding the details

The `hide-details` prop removes the bottom block entirely — fields can then sit
right next to each other. The `auto` value hides the block only while there is
nothing to show: as soon as an error or a hint appears, the block is rendered and
pushes the content below.

**Example — `HideDetails.vue`:**

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

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto">
    <template #default="{ reset }">
      <CdsTextInput
        label="Логин"
        placeholder="Очистите поле!"
        hide-details="auto"
        :rules="[(value: string) => !!value || 'Логин не может быть пустым']"
        clearable
      />
      <CdsTextInput
        label="Пароль"
        placeholder="Введите пароль"
        type="password"
        hide-details="auto"
        :rules="[(value: string) => !!value || 'Пароль не может быть пустым']"
      />

      <div class="flex gap-2 mt-2 justify-end">
        <CdsButton text="Сбросить" variant="soft" color="neutral" @click="reset" />
        <CdsButton type="submit" text="Отправить" />
      </div>
    </template>
  </CdsForm>
</template>
```

### Icons

The `prepend-icon` and `append-icon` props put an icon outside the field,
`prepend-inner-icon` and `append-inner-icon` — inside it.

**Example — `Icons.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput prepend-icon="user" placeholder="prepend-icon" />
    <CdsTextInput append-icon="add" placeholder="append-icon" />
    <CdsTextInput prepend-inner-icon="user" placeholder="prepend-inner-icon" />
    <CdsTextInput append-inner-icon="add" placeholder="append-inner-icon" />
    <CdsTextInput prepend-icon="user" append-icon="add" placeholder="prepend-icon & append-icon" />
    <CdsTextInput
      prepend-inner-icon="user"
      append-inner-icon="add"
      placeholder="prepend-inner-icon & append-inner-icon"
    />
  </div>
</template>
```

### Prefix and suffix

The `prefix` and `suffix` props add an immutable text at the edges of the entered
value — a currency, a country code, a domain.

**Example — `PrefixAndSuffix.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput type="number" label="Число" prefix="$" value="100" />
    <CdsTextInput type="email" label="Электронная почта" suffix="@email.com" value="example" />
    <CdsTextInput type="tel" label="Телефон" prefix="+7" placeholder="(000) 000-00-00" />
    <CdsTextInput type="time" label="Время" model-value="10:45:00" prefix="UTC" />
  </div>
</template>
```

### Clearing

The `clearable` prop shows the clear icon on hover or focus,
`persistent-clearable` keeps it visible at all times.

**Example — `Clearable.vue`:**

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

const value = ref('Очисти меня!');
</script>

<template>
  <CdsTextInput
    v-model="value"
    placeholder="Введите значение"
    hint="Это поле можно очистить"
    clearable
    persistent-clearable
    class="max-w-sm m-auto"
  />
</template>
```

### States

`disabled` blocks the input and lowers the contrast, `readonly` forbids changes
but keeps focus and copying, `loading` shows a loading indicator — as a bar or as
a circle (`loading="circle"`).

**Example — `States.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput label="Disabled" value="Значение" disabled />
    <CdsTextInput label="Readonly" value="Только для чтения" readonly />
    <CdsTextInput label="Loading" value="Загрузка" loading />
    <CdsTextInput label="Loading circle" value="Загрузка" loading="circle" />
  </div>
</template>
```

### Validation

The `rules` prop accepts an array of validator functions: each one returns either
`true` or a string with an error message. `validate-on` sets the moment they run
— `blur`, `input` or `submit` (only on a `validate()` call).

**Example — `Validation.vue`:**

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

const title = ref('Удалите значение');
</script>

<template>
  <CdsTextInput
    v-model="title"
    :rules="[
      (value: string) => !!value || 'Не может быть пустым',
      (value: string) => value.length <= 10 || 'Допустимое значение 10 символов'
    ]"
    label="Заголовок"
    placeholder="Введите текст"
    required
    class="max-w-sm m-auto"
  />
</template>
```

Validators are plain functions: declare them once and reuse them across the
fields of a form. Here the title is checked for being required and for its length
(together with `maxlength` and the counter), and the email — for its format.

**Example — `ValidationForm.vue`:**

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

const title = ref('Предварительный отчёт');
const email = ref('');

const rules = {
  required: (value: string) => !!value || 'Обязательное поле',
  counter: (value: string) => value.length <= 20 || 'Не больше 20 символов',
  email: (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) || 'Некорректная почта'
};
</script>

<template>
  <CdsForm class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsTextInput
      v-model="title"
      label="Заголовок"
      :rules="[rules.required, rules.counter]"
      persistent-counter
      maxlength="20"
      counter="20"
    />

    <CdsTextInput
      v-model="email"
      label="Электронная почта"
      placeholder="name@company.ru"
      :rules="[rules.required, rules.email]"
    />
  </CdsForm>
</template>
```

### Errors from outside

The `error-messages` prop shows ready messages — the ones coming from the server,
for example — independently of `rules`. `error` turns on the visual error state
without any text, `max-errors` limits the number of messages.

**Example — `ErrorState.vue`:**

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

<template>
  <div class="flex flex-col max-w-sm m-auto gap-2">
    <CdsTextInput
      label="Состояние ошибки"
      placeholder="errorMessages (string)"
      error-messages="Поле заполнено некорректно"
    />
    <CdsTextInput
      label="Состояние ошибки"
      placeholder="errorMessages (array)"
      :error-messages="['Ошибка 1', 'Ошибка 2']"
      :max-errors="2"
    />
    <CdsTextInput label="Состояние ошибки" placeholder="Без сообщения, но error: true" error />
  </div>
</template>
```

### Counter

The `counter` prop shows a character counter: `true` — without a limit, a number
— with a limit. `counter-value` accepts your own counting formula,
`persistent-counter` keeps the counter visible outside of focus.

**Example — `Counter.vue`:**

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

const wordCount = (value: unknown) => (value ?? '').toString().trim().split(/\s+/).filter(Boolean).length;
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput label="counter true" placeholder="Просто счётчик" counter />
    <CdsTextInput label="counter с лимитом" placeholder="До 20 символов" counter="20" maxlength="20" />
    <CdsTextInput label="persistentCounter" placeholder="Счётчик всегда виден" counter persistent-counter />
    <CdsTextInput label="counterValue (слова)" placeholder="Считаем слова" counter :counter-value="wordCount" />
  </div>
</template>
```

### Colors

The `color` prop sets the main color, `active-color` — the color on focus,
`icon-color` — the color of the icons, `bg-color` — the background of the field.

**Example — `Colors.vue`:**

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

<template>
  <div class="max-w-sm m-auto">
    <CdsTextInput label="color" value="Цвет компонента" color="green" />
    <CdsTextInput label="activeColor" placeholder="Цвет при фокусе" active-color="purple" />
    <CdsTextInput label="iconColor" placeholder="Цвет иконки" prepend-inner-icon="user" icon-color="brand-primary" />
    <CdsTextInput label="bgColor" placeholder="Цвет фона" bg-color="status-success-fill" />
  </div>
</template>
```

### Slots

When props are not enough, the content of any block is replaced by a slot.
`prepend` / `append` put elements outside the field, `prepend-inner` /
`append-inner` — inside it; unlike the `*-icon` props, slots accept any
components — buttons, links, badges.

| Slot name       | Description                                          |
| :-------------- | :--------------------------------------------------- |
| `label`         | Label content (replaces `label`)                     |
| `description`   | Description content (replaces `description`)         |
| `prepend`       | Element before the input                             |
| `append`        | Element after the input                              |
| `prepend-inner` | Element at the start of the field, inside the border |
| `append-inner`  | Element at the end of the field, inside the border   |
| `clear`         | Your own clear icon (with `clearable`)               |
| `loader`        | Your own loading indicator (with `loading`)          |
| `counter`       | Counter content                                      |
| `details`       | The whole bottom block — messages and counter        |
| `messages`      | Content of the messages block                        |

**Example — `CustomSlots.vue`:**

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

const showed = ref(false);
</script>

<template>
  <CdsTextInput loading placeholder="Введите текст" class="max-w-sm m-auto">
    <template #label>
      <span class="inline-flex items-center gap-1">
        <CdsIcon name="user" />
        <strong>Кастомный заголовок</strong>
      </span>
    </template>
    <template #description>
      <em>Описание через <span class="text-purple-500 font-bold">слот</span></em>
    </template>
    <template #messages>
      <span class="text-green-500">✓ Кастомное сообщение</span>
    </template>

    <template #prepend="props">
      <CdsButton variant="soft" color="neutral" icon="add" :size="props.size.value" />
    </template>
    <template #append="props">
      <CdsButton variant="solid" color="brand" text="OK" :size="props.size.value" />
    </template>

    <template #prepend-inner="props">
      <CdsIcon name="user" :size="props.size.value" />
    </template>
    <template #append-inner>
      <CdsFunctionalButton :icon="showed ? 'visibility-off' : 'visibility'" @click="showed = !showed" />
    </template>

    <template #loader>
      <CdsProgressBar color="purple" height="4" indeterminate />
    </template>
  </CdsTextInput>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The label is always visible and names the field, the placeholder shows a sample value. | A placeholder used instead of a label disappears on input — the user forgets what they are filling in. |
| The error message says exactly what to fix. | “Invalid value” does not help: it is unclear what is wrong and what to do. |
| The placeholder is a short sample value in the right format. | Instructions in the placeholder duplicate the label and vanish on input. |

## Scenarios

### Searching through a list

A search field is made of the `prepend-inner-icon="search"` icon and
`clearable` — the user resets the query in one click and sees the full list
again. A label is not needed here: the role of the field is obvious from the icon
and the placeholder.

**Example — `SearchFilter.vue`:**

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

const query = ref('');

const items = ['Договор поставки', 'Договор аренды', 'Акт сверки', 'Счёт на оплату'];

const filtered = computed(() => items.filter((item) => item.toLowerCase().includes(query.value.trim().toLowerCase())));
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-3 m-auto">
    <CdsTextInput v-model="query" placeholder="Поиск по документам" prepend-inner-icon="search" clearable />

    <ul class="m-0 flex list-none flex-col gap-1 p-0">
      <li v-for="item in filtered" :key="item">{{ item }}</li>
      <li v-if="filtered.length === 0">Ничего не найдено</li>
    </ul>
  </div>
</template>
```

### Password with a preview

The `append-inner` slot accepts interactive elements — a button that toggles
`type` between `password` and `text`, for example. The hint in `hint` states the
password requirements before the user makes a mistake.

**Example — `PasswordToggle.vue`:**

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

const password = ref('qwerty123');
const visible = ref(false);
</script>

<template>
  <CdsTextInput
    v-model="password"
    class="w-full max-w-md m-auto"
    label="Пароль"
    :type="visible ? 'text' : 'password'"
    hint="Минимум 8 символов"
  >
    <template #append-inner>
      <CdsFunctionalButton
        :icon="visible ? 'visibility-off' : 'visibility'"
        :aria-label="visible ? 'Скрыть пароль' : 'Показать пароль'"
        @click="visible = !visible"
      />
    </template>
  </CdsTextInput>
</template>
```

### An error from the server

The server response goes into `error-messages` as is — validation through `rules`
is not needed for that. Reset the error when the value changes, so that the field
does not complain about an input that is already fixed.

**Example — `ServerError.vue`:**

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

const email = ref('taken@company.ru');
const loading = ref(false);
const serverErrors = ref<string[]>([]);

const save = async () => {
  loading.value = true;
  serverErrors.value = [];

  // Имитация ответа сервера
  await new Promise((resolve) => setTimeout(resolve, 1000));

  loading.value = false;
  serverErrors.value = ['Эта почта уже занята — укажите другую'];
};
</script>

<template>
  <form class="flex w-full max-w-md flex-col gap-4 m-auto" @submit.prevent="save">
    <CdsTextInput
      v-model="email"
      label="Электронная почта"
      placeholder="name@company.ru"
      :error-messages="serverErrors"
      @update:model-value="serverErrors = []"
    />

    <CdsButton class="self-start" type="submit" text="Сохранить" :loading="loading" />
  </form>
</template>
```

### Events

Every icon zone emits its own click event: `click:prepend`, `click:append`,
`click:prepend-inner`, `click:append-inner` and `click:clear` (the last one fires
after the value has already been reset). Here the icon on the left cycles through
the options, the lock inside the field toggles, and the submit button clears the
message. When you need a complex element instead of an icon — a button, a badge —
use the slots of the same name, like in the password example above.

**Example — `Events.vue`:**

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

const message = ref('Привет!');
const locked = ref(false);
const iconIndex = ref(0);

const icons = ['message', 'star', 'flag', 'bookmark'];
const icon = computed(() => icons[iconIndex.value]);

const changeIcon = () => {
  iconIndex.value = (iconIndex.value + 1) % icons.length;
};

const toggleLock = () => {
  locked.value = !locked.value;
};

const resetIcon = () => {
  iconIndex.value = 0;
};

const sendMessage = () => {
  resetIcon();
  message.value = '';
};
</script>

<template>
  <CdsTextInput
    v-model="message"
    class="w-[350px] m-auto"
    label="Сообщение"
    :prepend-icon="icon"
    :append-inner-icon="locked ? 'lock' : 'unlock'"
    append-icon="telegram"
    clearable
    @click:prepend="changeIcon"
    @click:append-inner="toggleLock"
    @click:append="sendMessage"
    @click:clear="resetIcon"
  />
</template>
```

## API

### CdsTextInput

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Active state of the field |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `appendInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner append slot, after the content of the field |
| `autocomplete` | `string \| undefined` | — | no | 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` | — | no | Enables autofocus |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `centerAffix` | `boolean \| undefined` | — | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `clearable` | `boolean \| undefined` | — | no | Shows the clear button |
| `clearIcon` | `IconValue \| undefined` | `'remove'` | no | Icon of the clear button |
| `color` | `string \| undefined` | — | no | Component color |
| `counter` | `string \| number \| boolean \| undefined` | — | no | Character counter. Accepts a boolean, a number or a string |
| `counterValue` | `number \| ((value: any) => number) \| undefined` | — | no | Custom counter value. Either a number or a function computing it from the current value |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `dirty` | `boolean \| undefined` | — | no | Marks that the value of the field was changed by the user |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `loading` | `string \| boolean \| undefined` | — | no | Loading indicator for the component |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelModifiers` | `Record<string, boolean> \| undefined` | — | no | v-model modifiers passed by Vue to process the field value |
| `modelValue` | `any` | — | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
| `name` | `string \| undefined` | — | no | Name of the input |
| `persistentClearable` | `boolean \| undefined` | — | no | Always show the clear button, not only on hover or focus |
| `persistentCounter` | `boolean \| undefined` | — | no | Always show the counter, not only while the field is in use |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `persistentPlaceholder` | `boolean \| undefined` | — | no | Always show the placeholder instead of hiding it while the field is in use |
| `placeholder` | `string \| undefined` | — | no | Placeholder text shown in an empty field |
| `prefix` | `string \| undefined` | — | no | Text prefix shown before the field value |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `prependInnerIcon` | `IconValue \| undefined` | — | no | Icon in the inner prepend slot, before the content of the field |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `reverse` | `boolean \| undefined` | — | no | Reverses the order of the elements inside the field |
| `role` | `string \| undefined` | — | no | ARIA role for the native input element |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `suffix` | `string \| undefined` | — | no | Text suffix shown after the field value |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `type` | `string \| undefined` | `'text'` | no | Type of the native input |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `click:append` | `[e: MouseEvent]` | Click on the outer append icon (`append-icon` prop) |
| `click:appendInner` | `[e: MouseEvent]` | Click on the inner append icon (`append-inner-icon` prop) |
| `click:clear` | `[e: MouseEvent]` | Click on the clear icon (`clearable`); fires after the value has been reset |
| `click:control` | `[e: MouseEvent]` | Fires on a click in the main area of the control |
| `click:prepend` | `[e: MouseEvent]` | Click on the outer prepend icon (`prepend-icon` prop) |
| `click:prependInner` | `[e: MouseEvent]` | Click on the inner prepend icon (`prepend-inner-icon` prop) |
| `mousedown:control` | `[e: MouseEvent]` | Fires on a mouse button press in the main area of the control |
| `update:focused` | `[focused: boolean]` | Fires when the element gains or loses focus |
| `update:modelValue` | `[value: string]` | Fires when the model of the component changes |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `append-inner` | `CdsInputDefaultSlot` | Slot added at the end of the input |
| `clear` | `CdsInputDefaultSlot & { props: Record<string, any>; }` | Slot for a custom clear icon (shown when the clearable prop is true). |
| `counter` | `CdsCounterSlot` | Slot for a custom counter |
| `default` | `{ id: Readonly<Ref<string, string>>; }` | Default slot |
| `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 |
| `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). |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |
| `prepend-inner` | `CdsInputDefaultSlot` | Slot added at the start of the input |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `controlRef` | `HTMLElement \| undefined` | Ref to the control of the input |
| `fieldIconColor` | `string \| undefined` | Icon color |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsTimePicker

_Category: Controls · since 4.0.0_

_Tests: API 21/21 · 39 unit · 2 e2e · 7 known bugs · lines 97.2% (v4.0.0-alpha.13) · a11y: 17 axe recommendations (v4.0.0-alpha.11)_

Time selection: hours, minutes and — if you want — seconds. The value can be typed on the keyboard or stepped through with the arrows, and `v-model` receives a string in the given format (`HH:mm` by default), which is convenient to store and to send to the server.

**See also:** To pick a date use CdsDatePicker, and if you need a field with a date and a time at once — the ready CdsDateInput with the `with-time` prop: it puts this clock under the calendar and brings everything together into one string itself.

## Anatomy

Every block of the time is a field with arrows: the value can be typed on the
keyboard or stepped through one unit at a time. The seconds, the AM/PM switch and
the "Now" button are added by the `with-seconds`, `format12h` and `now-btn`
props.

## Variations

### Value and format

The time arrives in `v-model` as a string in the `mask` format — `HH:mm` by
default. As the second argument of the `update:model-value` event the component
gives out the parsed date as an object: the year, the month, the day, the hours,
the minutes, the seconds. While no value is chosen, the fields are empty and show
the `00` hint.

**Example — `Default.vue`:**

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

const time = ref<string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" />

    <span class="text-200 text-content-secondary">v-model: {{ time ?? '—' }}</span>
  </div>
</template>
```

The mask may include the date as well: then the component changes the time only
and carries the date over from the current value — that is how one string is
shared between a calendar and a clock. The `with-time` prop of
CdsDateInput is built on the same idea. If the
model is empty, the date for the new string is taken from `default-date` (the
`YYYY/MM/DD` format), otherwise it is today.

**Example — `Mask.vue`:**

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

const withDate = ref('01.09.2026 09:30');
const empty = ref<string | null>(null);
</script>

<template>
  <div class="flex flex-wrap items-start justify-center gap-4">
    <div class="flex flex-col items-center gap-2">
      <CdsTimePicker v-model="withDate" mask="DD.MM.YYYY HH:mm" />

      <span class="text-200 text-content-secondary">v-model: {{ withDate }}</span>
    </div>

    <div class="flex flex-col items-center gap-2">
      <CdsTimePicker v-model="empty" mask="DD.MM.YYYY HH:mm" default-date="2026/09/01" />

      <span class="text-200 text-content-secondary">v-model: {{ empty ?? '—' }}</span>
    </div>
  </div>
</template>
```

### Seconds

`with-seconds` adds a third block. The mask is extended automatically: the
component appends `:ss` to `HH:mm` by itself.

**Example — `WithSeconds.vue`:**

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

const time = ref('15:22:30');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" with-seconds />

    <span class="text-200 text-content-secondary">v-model: {{ time }}</span>
  </div>
</template>
```

### The 12-hour format

`format12h` shows the hours from 1 to 12 and the AM/PM switch. This does not
affect the value in the model — the format is set by the mask, so for a string
with AM/PM use `hh:mm A`.

**Example — `Format12h.vue`:**

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

const time = ref('14:00');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" format12h />

    <span class="text-200 text-content-secondary">v-model: {{ time }}</span>
  </div>
</template>
```

### The "Now" button

`now-btn` adds a button under the clock that sets the current time — the user
does not have to step through the values with the arrows.

**Example — `NowBtn.vue`:**

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

const time = ref('18:00');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" now-btn />

    <span class="text-200 text-content-secondary">v-model: {{ time }}</span>
  </div>
</template>
```

### Available time

`allowed-hours`, `allowed-minutes` and `allowed-seconds` accept arrays of the
allowed values: the arrows step through those only, and a value outside the list
is pulled by the component to the nearest allowed one.

**Example — `LimitedTime.vue`:**

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

const time = ref('12:30');

const allowedHours = [9, 10, 11, 12, 13, 14];
const allowedMinutes = [0, 15, 30, 45];
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" :allowed-hours="allowedHours" :allowed-minutes="allowedMinutes" />

    <span class="text-200 text-content-secondary">v-model: {{ time }}</span>
  </div>
</template>
```

When the restriction depends on the already chosen time, pass the `allowed-time`
function instead of the arrays. It is called separately for the hours, the
minutes and the seconds: the parts that are not being checked arrive as `null`.

**Example — `AllowedTime.vue`:**

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

const time = ref('10:30');

// Часы и минуты проверяются по отдельности: сначала приходит только час,
// затем час вместе с минутой. Обед с 13:00 до 14:00 недоступен.
const allowedTime = (hour: number | null, minute: number | null) => {
  if (hour === null) return true;
  if (hour < 9 || hour > 17) return false;
  if (minute === null) return true;

  return hour !== 13;
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" :allowed-time="allowedTime" />

    <span class="text-200 text-content-secondary">v-model: {{ time }}</span>
  </div>
</template>
```

### Localization

`locale` accepts a locale name (`ru` | `en`) or your own object of translations;
without the prop the locale of the application is taken. The caption of the "Now"
button and the default format depend on the locale: in `en` the time is 12-hour,
so the hours are shown from 1 to 12 even without `format12h` — only the AM/PM
switch is added by it.

**Example — `Localization.vue`:**

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

const time = ref('09:35 AM');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsTimePicker v-model="time" locale="en" format12h now-btn mask="hh:mm A" />

    <span class="text-200 text-content-secondary">v-model: {{ time }}</span>
  </div>
</template>
```

### States

`disabled` turns the clock off and dims it, `readonly` keeps the usual look but
forbids changing the value — both with the arrows and from the keyboard.

**Example — `DisabledAndReadonly.vue`:**

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

const time = ref('15:22');
</script>

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsTimePicker v-model="time" disabled now-btn />
    <CdsTimePicker v-model="time" readonly now-btn />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The minute step is set through allowed-minutes — the needed value is reached in a couple of clicks. | Free minutes give 60 options where meetings are scheduled by quarters of an hour. |
| Show the seconds only where they matter: in logs, timings, trading rules. | An extra field in a meeting booking makes the user fill in what nobody needs. |
| In a Russian interface the 24-hour format is more familiar — it is the default one. | AM/PM asks the user to convert the time in their head and adds an extra switch. |

## Scenarios

### Booking a meeting

Meetings are scheduled within working hours and by quarters of an hour —
`allowed-hours` and `allowed-minutes` leave only such values. The user cannot
pick a time that would have to be rejected later.

**Example — `MeetingTime.vue`:**

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

const time = ref('10:30');

// Встречи назначают в рабочие часы и по четвертям часа.
const allowedHours = [9, 10, 11, 12, 13, 14, 15, 16, 17];
const allowedMinutes = [0, 15, 30, 45];

const pad = (value: number) => String(value).padStart(2, '0');

const finish = computed(() => {
  const [hour, minute] = time.value.split(':').map(Number);
  const end = hour * 60 + minute + 30;

  return `${pad(Math.floor(end / 60))}:${pad(end % 60)}`;
});
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsTimePicker v-model="time" :allowed-hours="allowedHours" :allowed-minutes="allowedMinutes" />
    </CdsCard>

    <span class="text-200 text-content-secondary">Встреча: {{ time }} — {{ finish }} (30 минут)</span>
  </div>
</template>
```

### A field with a time

Most often the clock lives not on the page but in a menu next to a text field.
There is no ready field for the time alone in the system — assemble the control
out of CdsTextInput, a
CdsMenu with `activator="parent"` and the clock: all
the props and slots of the field and the menu stay available to you. For the
manual input add a mask: we recommend the lightweight (2.5 KB)
[Maska](https://github.com/beholdr/maska) library. If you need the date together
with the time, the field already exists —
CdsDateInput with `with-time`.

**Example — `TimeField.vue`:**

```vue
<script setup lang="ts">
import { CdsMenu, CdsTextInput, CdsTimePicker } from '@central-design-system/components';
import { vMaska } from 'maska/vue';
import { ref } from 'vue';

const time = ref('12:00');
</script>

<template>
  <div class="w-[250px] m-auto">
    <CdsTextInput v-model="time" v-maska="'##:##'" label="Время" placeholder="Выберите время" append-inner-icon="time">
      <CdsMenu activator="parent" :close-on-content-click="false">
        <CdsTimePicker v-model="time" now-btn />
      </CdsMenu>
    </CdsTextInput>
  </div>
</template>
```

### A "from — to" interval

Two clocks can share one rule: the `allowed-time` of the end looks at the start
and does not let an earlier time be picked. When the start is moved past the end,
the demo moves the end too — the rule and the code work in pairs.

**Example — `WorkingHours.vue`:**

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

const start = ref('09:00');
const end = ref('18:00');

const pad = (value: number) => String(value).padStart(2, '0');
const toMinutes = (time: string) => {
  const [hour, minute] = time.split(':').map(Number);

  return hour * 60 + minute;
};

// Окончание не может быть раньше начала. Часы и минуты проверяются по отдельности:
// сначала приходит только час, затем час вместе с выбранной минутой.
const allowedEnd = (hour: number | null, minute: number | null) => {
  if (hour === null) return true;
  if (minute === null) return hour >= Math.floor(toMinutes(start.value) / 60);

  return hour * 60 + minute > toMinutes(start.value);
};

// Начало сдвинули за окончание — переносим окончание на час вперёд.
watch(start, () => {
  if (toMinutes(end.value) > toMinutes(start.value)) return;

  const shifted = Math.min(toMinutes(start.value) + 60, 23 * 60 + 59);
  end.value = `${pad(Math.floor(shifted / 60))}:${pad(shifted % 60)}`;
});

const duration = computed(() => {
  const total = toMinutes(end.value) - toMinutes(start.value);

  return `${Math.floor(total / 60)} ч ${pad(total % 60)} мин`;
});
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <div class="flex flex-wrap items-start justify-center gap-4">
      <div class="flex flex-col items-center gap-1">
        <span class="text-200 text-content-secondary">Начало</span>

        <CdsCard class="w-fit">
          <CdsTimePicker v-model="start" />
        </CdsCard>
      </div>

      <div class="flex flex-col items-center gap-1">
        <span class="text-200 text-content-secondary">Окончание</span>

        <CdsCard class="w-fit">
          <CdsTimePicker v-model="end" :allowed-time="allowedEnd" />
        </CdsCard>
      </div>
    </div>

    <span class="text-200 text-content-secondary">Рабочий день: {{ duration }}</span>
  </div>
</template>
```

### Date and time

The calendar does not pick the time and the clock does not pick the date — put
them next to each other with a shared model and the same `DD.MM.YYYY HH:mm` mask:
every component changes its own part of the string. In a field this pair is
already assembled — turn on `with-time` on
CdsDateInput.

**Example — `DateAndTime.vue`:**

```vue
<script setup lang="ts">
import { CdsDatePicker, CdsDivider, CdsMenu, CdsTextInput, CdsTimePicker } from '@central-design-system/components';
import { vMaska } from 'maska/vue';
import { ref } from 'vue';

const mask = 'DD.MM.YYYY HH:mm';
const dateTime = ref('01.09.2026 09:30');
</script>

<template>
  <div class="w-[250px] m-auto">
    <CdsTextInput
      v-model="dateTime"
      v-maska="'##.##.#### ##:##'"
      label="Дата и время"
      placeholder="Выберите дату и время"
      append-inner-icon="calendar"
    >
      <CdsMenu activator="parent" :close-on-content-click="false">
        <div class="flex flex-col">
          <CdsDatePicker v-model="dateTime" :mask="mask" />

          <CdsDivider />

          <CdsTimePicker v-model="dateTime" :mask="mask" now-btn />
        </div>
      </CdsMenu>
    </CdsTextInput>
  </div>
</template>
```

## API

### CdsTimePicker

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `allowedHours` | `number[] \| undefined` | — | no | Configures which hours are available for selection. |
| `allowedMinutes` | `number[] \| undefined` | — | no | Configures which minutes are available for selection. |
| `allowedSeconds` | `number[] \| undefined` | — | no | Configures which seconds are available for selection. |
| `allowedTime` | `((hr: number \| null, min: number \| null, sec: number \| null) => boolean) \| undefined` | — | no | Configures which time is available for selection. |
| `defaultDate` | `string \| undefined` | — | no | Date used by default when the model is empty (in the YYYY/MM/DD format). |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `format12h` | `boolean \| undefined` | — | no | Shows the time in the 12-hour AM/PM format. |
| `locale` | `string \| TDateLocale \| undefined` | — | no | Locale for the dates. A locale name ('ru' \| 'en') or a `TDateLocale` object. The current locale from `useLocale` is taken by default, otherwise `ru`. |
| `mask` | `string \| undefined` | `'HH:mm'` | no | Date/time format |
| `modelValue` | `string \| TDatetimeValueRange \| (string \| TDatetimeValueRange)[] \| null \| undefined` | `null` | no | Value of the model |
| `nowBtn` | `boolean \| undefined` | — | no | Shows the "Now" button. |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `theme` | `string \| undefined` | — | no | Component theme |
| `withSeconds` | `boolean \| undefined` | — | no | Adds seconds to the time selection. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: string \| undefined, date: IRawDate]` | The value changed (v-model). Passes the formatted value and the date object. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `setAm` | `() => void` | Switches the 12-hour format to the first half of the day (AM). |
| `setHour` | `(hour: number) => void` | Sets the hours. |
| `setMinute` | `(minute: number) => void` | Sets the minutes. |
| `setNow` | `() => void` | Sets the current system time. |
| `setPm` | `() => void` | Switches the 12-hour format to the second half of the day (PM). |
| `setSecond` | `(second: number) => void` | Sets the seconds. |

---

# CdsToast

_Category: Feedback · since 4.0.0 · status: new_

_Tests: API 69/69 · 68 unit · 6 known bugs · lines 100% (v4.0.0-alpha.13) · a11y: 9 axe recommendations (v4.0.0-alpha.11)_

A toast is a pop-up notification about the result of an action: the changes are saved, the file is uploaded, the request failed. It appears above the page, does not interrupt the work and closes itself once `timeout` runs out.

**See also:** For a stream of events where notifications arrive one after another use CdsToastQueue. A message that has to stay on the page belongs in CdsNotification, and a question that requires a decision from the user — in the CdsModal dialog.

## Anatomy

A toast consists of a container and three zones: prepend with the status icon,
an avatar or a loading indicator; the content with a heading and text; and the
actions zone. The `timer` prop adds a bar of the remaining time.

## Variations

### Controlling the visibility

Show the toast through `v-model` or the `activator` slot — in the second case
the component manages its own state. The toast closes automatically after
`timeout` (5000 ms by default); hovering the cursor or focusing inside the toast
pauses the countdown, and on touch screens the toast can be swiped away.

**Example — `Visibility.vue`:**

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

const visible = ref(false);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton text="Открыть через v-model" @click="visible = true" />
    <CdsToast v-model="visible" text="Изменения сохранены" />

    <CdsToast text="Черновик восстановлен">
      <template #activator="{ props }">
        <CdsButton text="Открыть через activator" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsToast>
  </div>
</template>
```

### Status

The `status` prop picks the color and the icon by the meaning of the message:
`info`, `success`, `warning`, `danger`, `progress`. The icon can be replaced by
the `icon` prop or hidden with the value `false`.

**Example — `Statuses.vue`:**

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

const statuses = ['info', 'success', 'warning', 'danger', 'progress'] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton v-for="status in statuses" :key="status" :color="`status-${status}-surface`" variant="solid">
      {{ status }}
      <CdsToast activator="parent" :status="status" :text="`Уведомление со статусом ${status}`" />
    </CdsButton>
  </div>
</template>
```

### Timer

The `timeout` prop sets the delay before auto-closing in milliseconds, and `-1`
turns it off. The bar of the remaining time is enabled by the `timer` prop
(`true`/`top` — on top, `bottom` — at the bottom), `reverse-timer` flips its
direction and `timer-color` changes its color.

**Example — `Timer.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsToast timer :timeout="4000" text="Тост закроется через 4 секунды">
      <template #activator="{ props }">
        <CdsButton text="Таймер сверху" v-bind="props" />
      </template>
    </CdsToast>

    <CdsToast timer="bottom" reverse-timer :timeout="4000" text="Обратная шкала снизу">
      <template #activator="{ props }">
        <CdsButton text="Таймер снизу" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsToast>
  </div>
</template>
```

### Position

The `location` prop puts the toast into one of the six positions: the side
(`top`, `bottom`) plus the alignment (`left`, `center`, `right`). The toast is
rendered above the page content by CdsOverlay.

**Example — `Location.vue`:**

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

const locations = ['top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'] as const;
</script>

<template>
  <div class="grid grid-cols-3 justify-items-center gap-2">
    <CdsButton v-for="location in locations" :key="location" variant="soft" color="neutral">
      {{ location }}
      <CdsToast activator="parent" :location="location" :text="`Тост в позиции ${location}`" />
    </CdsButton>
  </div>
</template>
```

### Content and actions

The heading and the text come from the `title` and `text` props, the avatar
before the content from `prepend-avatar`, and `loading` replaces the icon with a
loading indicator. The `actions` slot adds buttons: inside it they get
`variant="solid"`, `color="inverse"` and `size="sm"` by default. The vertical layout
(`vertical`) moves the actions below the content.

**Example — `ContentAndActions.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsToast
      title="Черновик удалён"
      text="Черновик заявки №42 удалён без возможности восстановления"
      status="warning"
      :timeout="8000"
    >
      <template #activator="{ props }">
        <CdsButton text="С заголовком и действиями" v-bind="props" />
      </template>
      <template #actions="{ isActive }">
        <CdsButton text="Отменить" variant="soft" color="neutral" @click="isActive.value = false" />
      </template>
    </CdsToast>

    <CdsToast
      prepend-avatar="https://i.pravatar.cc/80?img=32"
      title="Ирина Соколова"
      text="Добавила комментарий к заказу"
    >
      <template #activator="{ props }">
        <CdsButton text="С аватаром" variant="soft" color="brand" v-bind="props" />
      </template>
    </CdsToast>

    <CdsToast vertical title="Файл загружается" text="Не закрывайте вкладку до завершения" loading :timeout="-1">
      <template #activator="{ props }">
        <CdsButton text="Вертикальный с загрузкой" variant="soft" color="brand" v-bind="props" />
      </template>
      <template #actions="{ isActive }">
        <CdsButton text="Скрыть" variant="soft" color="neutral" @click="isActive.value = false" />
      </template>
    </CdsToast>
  </div>
</template>
```

### Slots

Slots replace the content coming from props when you need your own markup.

| Slot        | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| `activator` | The element that opens the toast                                                 |
| `header`    | A header across the full width of the toast                                      |
| `prepend`   | Content before the text. Replaces the icon, the avatar and the loading indicator |
| `title`     | Heading. Replaces the text from `title`                                          |
| `text`      | Text. Replaces the text from `text`                                              |
| `default`   | Main content after the text                                                      |
| `actions`   | Actions of the toast                                                             |

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The toast text is a short summary of the action, readable in a second. | Details and instructions cannot be read before the toast closes itself. |
| A toast reports an action that already happened and offers to undo it. | A toast does not wait for an answer — ask questions that need a decision in a modal. |
| An error stays on the screen (timeout: -1) until the user reacts. | An error with a timer disappears before the user can deal with it. |

## Scenarios

### Undoing an action

The toast confirms the deletion and gives time to change one's mind: the
"Отменить" button in the `actions` slot brings the document back, and the
`timer` bar shows how much time is left to decide.

**Example — `UndoAction.vue`:**

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

const documents = ref(['Договор поставки', 'Счёт №112', 'Акт сверки']);
const visible = ref(false);
const removed = ref<{ name: string; index: number } | null>(null);

const remove = (index: number) => {
  removed.value = { name: documents.value[index], index };
  documents.value.splice(index, 1);
  visible.value = true;
};

const undo = () => {
  if (removed.value) {
    documents.value.splice(removed.value.index, 0, removed.value.name);
  }
  visible.value = false;
};
</script>

<template>
  <div class="flex w-[320px] m-auto flex-col gap-2">
    <div v-for="(name, index) in documents" :key="name" class="flex items-center justify-between">
      {{ name }}
      <CdsButton
        icon="delete"
        variant="soft"
        color="neutral"
        size="sm"
        :aria-label="`Удалить ${name}`"
        @click="remove(index)"
      />
    </div>

    <CdsToast v-model="visible" timer :timeout="6000" :text="removed ? `Документ «${removed.name}» удалён` : ''">
      <template #actions>
        <CdsButton text="Отменить" @click="undo" />
      </template>
    </CdsToast>
  </div>
</template>
```

### A background task

A single toast accompanies the task from the start to the result. While the
processing runs, `loading` shows the indicator and `timeout: -1` keeps the
notification from disappearing; once it is done the same toast switches to
`status="success"` and closes itself.

**Example — `BackgroundTask.vue`:**

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

const visible = ref(false);
const loading = ref(false);

const generate = () => {
  visible.value = true;
  loading.value = true;

  setTimeout(() => {
    loading.value = false;
  }, 2500);
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Сформировать отчёт" :disabled="visible && loading" @click="generate" />

    <CdsToast
      v-model="visible"
      :loading="loading"
      :status="loading ? undefined : 'success'"
      :timeout="loading ? -1 : 4000"
      :title="loading ? 'Формируем отчёт' : 'Отчёт готов'"
      :text="loading ? 'Это займёт несколько секунд' : 'Файл сохранён в разделе «Документы»'"
    />
  </div>
</template>
```

### An error with a retry

Do not hide an error automatically: `timeout: -1` keeps the toast until the user
reacts, and the "Повторить" button in `actions` runs the request again.

**Example — `ErrorRetry.vue`:**

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

const sending = ref(false);
const failed = ref(false);
const sent = ref(false);
let attempt = 0;

const send = () => {
  sending.value = true;
  failed.value = false;

  setTimeout(() => {
    sending.value = false;
    attempt += 1;

    if (attempt % 2 === 1) {
      failed.value = true;
    } else {
      sent.value = true;
    }
  }, 1500);
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Отправить заявку" :loading="sending" @click="send" />

    <CdsToast
      v-model="failed"
      status="danger"
      :timeout="-1"
      title="Не удалось отправить заявку"
      text="Сервер не ответил. Попробуйте ещё раз"
    >
      <template #actions>
        <CdsButton text="Повторить" @click="send" />
      </template>
    </CdsToast>

    <CdsToast v-model="sent" status="success" text="Заявка отправлена" />
  </div>
</template>
```

## API

### CdsToast

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the element absolutely instead of fixed. This is useful for overlays that must stay inside a certain area, for example inside a container with `position: relative`. |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `closeDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeOnBack` | `boolean \| undefined` | `false` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | — | no | Hide the component on a click on the content |
| `collapsed` | `{ width: number; height: number; } \| undefined` | — | no | Collapsed state of a toast in the queue: the size the toast collapses to. Managed by the CdsToastQueue component. |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `icon` | `false \| IconValue \| undefined` | `null` | no | Icon before the content. Taken from `status` by default; `false` hides the icon. |
| `loading` | `boolean \| undefined` | — | no | Shows a loading indicator instead of the icon. |
| `location` | `Anchor \| null \| undefined` | `'top center'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'static'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | — | no | The v-model value of the component. If the component supports the **multiple** prop, an empty array is used by default. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | — | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | — | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'auto'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
| `prependAvatar` | `string \| undefined` | — | no | Source of the avatar image before the content. Takes priority over the icon. |
| `queueGap` | `number \| undefined` | — | no | Gap between the toasts in the queue, in pixels. Managed by the CdsToastQueue component. |
| `queueIndex` | `number \| undefined` | — | no | Index of the toast in the queue. Managed by the CdsToastQueue component. |
| `reverseTimer` | `boolean \| undefined` | — | no | Reverses the timer bar: it fills up instead of draining. |
| `status` | `"progress" \| "danger" \| "success" \| "warning" \| "info" \| undefined` | `'info'` | no | Semantic status — drives the color and the default icon. |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `timeout` | `string \| number \| undefined` | `5000` | no | Delay in milliseconds before the toast hides automatically. The value `-1` turns auto-closing off. |
| `timer` | `boolean \| "top" \| "bottom" \| undefined` | `false` | no | Shows the timer bar until auto-closing: `true`/`top` — on top, `bottom` — at the bottom. |
| `timerColor` | `string \| undefined` | — | no | Color of the timer bar. |
| `title` | `string \| undefined` | — | no | Heading of the toast. |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'cds-toast-transition'` | no | Transition animation |
| `vertical` | `boolean \| undefined` | — | no | Vertical layout: the actions move below the content. |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2000` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `afterEnter` | `[]` | The enter animation finished. |
| `afterLeave` | `[]` | The leave animation finished. |
| `update:modelValue` | `[value: boolean]` | The visibility of the toast changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `{ isActive: Ref<boolean, boolean>; }` | Slot for the actions of the toast. |
| `activator` | `{ isActive: boolean; props: Record<string, any>; }` | Slot for the element that acts as the activator of the toast. |
| `default` | `any` | Main content of the toast. |
| `header` | `any` | Slot for the full-width header of the toast. |
| `prepend` | `any` | Slot before the content (icon, avatar or loading indicator). |
| `text` | `any` | Text slot. |
| `title` | `any` | Heading slot. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activatorEl` | `HTMLElement \| undefined` | The DOM element of the activator. |
| `activatorRef` | `TemplateRef` | Template ref for assigning the activator manually. |
| `animateClick` | `() => void` | Runs the bounce animation of the content — the same as on a click outside a `persistent` overlay. |
| `contentEl` | `HTMLElement \| undefined` | The DOM element of the overlay content. |
| `globalTop` | `boolean` | Whether the overlay is the top one in the global stack of open overlays. |
| `rootEl` | `HTMLElement \| undefined` | The root DOM element of the overlay. |
| `scrimEl` | `HTMLElement \| undefined` | The DOM element of the scrim that dims the page. |
| `targetEl` | `HTMLElement \| undefined` | The DOM element of the positioning target. |
| `targetRef` | `TemplateRef` | Template ref for assigning the positioning target manually. |
| `updateLocation` | `((e: Event) => void) \| undefined` | Recalculates the position of the content relative to the target. |

---

# CdsToastQueue

_Category: Feedback · since 4.0.0 · status: new_

_Tests: API 58/58 · 34 unit · 2 e2e · 2 known bugs · lines 99.2% (v4.0.0-alpha.13) · a11y: 6 axe recommendations (v4.0.0-alpha.11)_

A queue of pop-up notifications built on CdsToast. Put the messages into the `v-model` array — the queue will show them one by one or as a stack, respect the limit of simultaneously visible toasts and close the ones that are done.

**See also:** For a single notification — a save confirmation, for example — CdsToast is enough.

## Variations

### The message queue

A message is a string or an object with toast props. Add messages to the
`v-model` array: the queue shows them one by one, and the rest wait for their
place. The `closable` prop adds a close button with the `close-text` label to
every toast. Props shared by the toasts — `location`, `timer`, `status` and
others — are set right on the queue: they apply to every message. While the
browser tab is hidden, auto-closing is paused.

**Example — `Messages.vue`:**

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

const messages = ref<ToastMessage[]>([]);
let count = 0;

const push = () => {
  messages.value = [...messages.value, `Сообщение №${++count}`];
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Добавить сообщение" @click="push" />
    <CdsToastQueue v-model="messages" closable />
  </div>
</template>
```

### Limit and overflow

The `total-visible` prop caps the number of simultaneously visible toasts: a new
one takes the place at the edge of the screen and pushes the previous ones
aside. The `display-strategy` prop decides what to do with the extra ones:
`hold` (the default) keeps them in the queue until a place frees up, `overflow`
closes the oldest ones.

**Example — `Overflow.vue`:**

```vue
<script setup lang="ts">
import type { ToastMessage } from '@central-design-system/components';
import { CdsButton, CdsRadio, CdsRadioGroup, CdsToastQueue } from '@central-design-system/components';
import { ref } from 'vue';

const strategy = ref<'hold' | 'overflow'>('hold');
const messages = ref<ToastMessage[]>([]);
let count = 0;

const push = () => {
  messages.value = [...messages.value, { text: `Сообщение №${++count}`, timeout: 8000 }];
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <CdsRadioGroup v-model="strategy" label="Стратегия переполнения" direction="horizontal" hide-details>
      <CdsRadio value="hold" label="hold — ждать места" />
      <CdsRadio value="overflow" label="overflow — вытеснять старые" />
    </CdsRadioGroup>

    <CdsButton text="Добавить сообщение" @click="push" />
    <CdsToastQueue v-model="messages" :total-visible="3" :display-strategy="strategy" closable />
  </div>
</template>
```

### The stack

The `collapsed` prop folds all the toasts except the last one into a compact
stack. Hover the cursor — the stack unfolds, and the timers pause while the
cursor is inside.

**Example — `Collapsed.vue`:**

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

const messages = ref<ToastMessage[]>([]);
let count = 0;

const push = () => {
  messages.value = [
    ...messages.value,
    {
      title: `Событие №${++count}`,
      text: 'Описание события в очереди',
      status: 'success'
    }
  ];
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Добавить в стопку" @click="push" />
    <CdsToastQueue v-model="messages" collapsed closable :total-visible="10" :timeout="6000" location="bottom right" />
  </div>
</template>
```

### Slots

The slots customize every toast of the queue; each of them receives the `item`
object of the current message.

| Slot      | Description                                                                               |
| --------- | ----------------------------------------------------------------------------------------- |
| `header`  | Header of the toast                                                                       |
| `text`    | Text of the toast. Replaces the `text` of the message                                     |
| `actions` | Actions of the toast. `props` carries an `onClick` handler that closes the toast          |
| `item`    | Full replacement of the toast. The message props are passed through `CdsDefaultsProvider` |

## Scenarios

### Background operations

Pass a `promise` in the message — the toast gets a loading indicator and does
not close until the operation is done. The `success` and `error` callbacks
return the toast props for the result: the status, the text and the auto-close
delay.

**Example — `AsyncOperations.vue`:**

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

const messages = ref<ToastMessage[]>([]);

const save = (shouldFail: boolean) => {
  const request = new Promise((resolve, reject) => {
    setTimeout(() => (shouldFail ? reject(new Error('Сервер не ответил')) : resolve(undefined)), 2000);
  });

  messages.value = [
    ...messages.value,
    {
      text: 'Сохраняем изменения…',
      promise: request,
      success: () => ({ status: 'success', text: 'Изменения сохранены', timeout: 4000 }),
      error: (err) => ({ status: 'danger', text: err?.message ?? 'Не удалось сохранить', timeout: 6000 })
    }
  ];
};
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton text="Успешное сохранение" @click="save(false)" />
    <CdsButton text="Сохранение с ошибкой" variant="soft" color="brand" @click="save(true)" />
    <CdsToastQueue v-model="messages" :total-visible="3" />
  </div>
</template>
```

### Notification center

The events of the application pile up into a single queue in the corner of the
screen: `location="bottom right"` moves the toasts out of the working area,
`collapsed` hides the older ones in a stack, and `closable` lets the user close
every notification.

**Example — `EventFeed.vue`:**

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

const events: ToastMessage[] = [
  { title: 'Новый заказ', text: 'Заказ №1042 ожидает подтверждения', status: 'info' },
  { title: 'Оплата получена', text: 'Счёт №112 оплачен полностью', status: 'success' },
  { title: 'Заканчивается место', text: 'Хранилище заполнено на 90%', status: 'warning' },
  { title: 'Сбой синхронизации', text: 'Не удалось обновить данные. Повторим автоматически', status: 'danger' }
];

const messages = ref<ToastMessage[]>([]);
let next = 0;

const push = () => {
  messages.value = [...messages.value, events[next++ % events.length]];
};
</script>

<template>
  <div class="flex justify-center">
    <CdsButton text="Новое событие" @click="push" />
    <CdsToastQueue v-model="messages" location="bottom right" collapsed closable :total-visible="5" :timeout="8000" />
  </div>
</template>
```

### Controlling the queue

The `onDismiss` callback of a message receives the reason it was closed — `auto`,
`dismissed`, `overflow` or `cleared` — and the exposed `clear()` method closes
all the toasts and empties the queue.

**Example — `QueueControl.vue`:**

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

const queue = ref<InstanceType<typeof CdsToastQueue>>();
const messages = ref<ToastMessage[]>([]);
const log = ref<string[]>([]);
let count = 0;

const push = () => {
  const id = ++count;

  messages.value = [
    ...messages.value,
    {
      text: `Задача №${id} выполнена`,
      status: 'success',
      onDismiss: (reason) => {
        log.value = [`Тост №${id} закрыт: ${reason}`, ...log.value].slice(0, 4);
      }
    }
  ];
};
</script>

<template>
  <div class="flex flex-col items-center gap-4">
    <div class="flex gap-2">
      <CdsButton text="Добавить" @click="push" />
      <CdsButton text="Закрыть все" variant="soft" color="neutral" @click="queue?.clear()" />
    </div>

    <div class="h-[96px] text-center">
      <div v-for="line in log" :key="line">{{ line }}</div>
    </div>

    <CdsToastQueue ref="queue" v-model="messages" :total-visible="3" closable />
  </div>
</template>
```

## API

### CdsToastQueue

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `absolute` | `boolean \| undefined` | — | no | Positions the element absolutely instead of fixed. This is useful for overlays that must stay inside a certain area, for example inside a container with `position: relative`. |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `closable` | `string \| boolean \| undefined` | — | no | Adds a close button to every toast. A string value sets the color of the button. |
| `closeDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeOnBack` | `boolean \| undefined` | `false` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | — | no | Hide the component on a click on the content |
| `closeText` | `string \| undefined` | `'$cds.dismiss'` | no | Text of the close button. |
| `collapsed` | `boolean \| undefined` | — | no | Folds the inactive toasts into a stack under the last visible one. |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `content` | `string \| number \| undefined` | — | no | Content displayed in the component. |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `displayStrategy` | `"overflow" \| "hold" \| undefined` | `'hold'` | no | Strategy when `totalVisible` is exceeded: `hold` — wait until a toast closes, `overflow` — push the oldest ones out. |
| `eager` | `boolean \| undefined` | — | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `gap` | `string \| number \| undefined` | `8` | no | Gap between the toasts, in pixels. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `icon` | `false \| IconValue \| undefined` | `null` | no | Icon before the content. Taken from `status` by default; `false` hides the icon. |
| `loading` | `boolean \| undefined` | — | no | Shows a loading indicator instead of the icon. |
| `location` | `Anchor \| null \| undefined` | `'top center'` | no | Position of the element relative to its container, for example "top left", "center", "bottom right". |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'static'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `readonly ToastMessage[] \| undefined` | `[]` | no | The queue of messages (v-model). A string or an object with toast props. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | — | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | — | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'auto'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `position` | `"absolute" \| "static" \| "fixed" \| "relative" \| "sticky" \| undefined` | — | no | CSS positioning of the component — the value of the `position` property |
| `prependAvatar` | `string \| undefined` | — | no | Source of the avatar image before the content. Takes priority over the icon. |
| `reverseTimer` | `boolean \| undefined` | — | no | Reverses the timer bar: it fills up instead of draining. |
| `status` | `"progress" \| "danger" \| "success" \| "warning" \| "info" \| undefined` | `'info'` | no | Semantic status — drives the color and the default icon. |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `text` | `string \| number \| undefined` | — | no | Text displayed in the component. |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `timeout` | `string \| number \| undefined` | `5000` | no | Delay in milliseconds before the toast hides automatically. The value `-1` turns auto-closing off. |
| `timer` | `boolean \| "top" \| "bottom" \| undefined` | `false` | no | Shows the timer bar until auto-closing: `true`/`top` — on top, `bottom` — at the bottom. |
| `timerColor` | `string \| undefined` | — | no | Color of the timer bar. |
| `title` | `string \| undefined` | — | no | Heading of the toast. |
| `totalVisible` | `string \| number \| undefined` | `1` | no | Maximum number of simultaneously visible toasts. |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `'cds-toast-transition'` | no | Transition animation |
| `vertical` | `boolean \| undefined` | — | no | Vertical layout: the actions move below the content. |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2000` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: ToastMessage[]]` | The queue of messages changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `actions` | `{ item: ToastMessage; props: { onClick: () => void; }; }` | Slot for the actions of the toast. |
| `header` | `{ item: ToastMessage; }` | Slot for the header of the toast. |
| `item` | `{ item: ToastMessage; }` | Slot that fully replaces the toast. The toast props are passed through CdsDefaultsProvider. |
| `text` | `{ item: ToastMessage; }` | Slot for the text of the toast. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `clear` | `() => void` | Empties the queue and closes all the visible toasts. |

---

# CdsToggle

_Category: Controls · since 4.0.0_

_Tests: API 69/69 · 66 unit · lines 100% (v4.0.0-alpha.13) · a11y: 2 axe recommendations (v4.0.0-alpha.11)_

A toggle is an on/off switch for a setting that applies immediately, without a "Save" button: notifications, auto-renewal, profile visibility. It is built on CdsInput: it can do a label and a description, messages and errors, loading and the indeterminate state.

**See also:** A toggle changes the setting instantly. If the choice is applied together with the rest of the form by a button, take CdsCheckbox, and to pick one option out of a set — CdsRadioGroup.

## Anatomy

On the left is the track with the thumb: their position and color show the state.
On the right are the label and the description of the setting, at the bottom is
the messages block. A click on the label toggles the switch exactly like a click
on the track.

## Variations

### Label and description

`label` names the setting, `description` explains what turning it on leads to.
Phrase the label so that it is clear what happens in the on position.

**Example — `LabelAndDescription.vue`:**

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

const notifications = ref(true);
const autoRenew = ref(false);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="notifications" label="Уведомления о новых закупках" hide-details />
    <CdsToggle
      v-model="autoRenew"
      label="Автопродление подписки"
      description="Спишем оплату за день до окончания периода"
      hide-details
    />
  </div>
</template>
```

### Sizes

Five sizes on the `size` scale — from `xs` to `xl`, `md` by default.

**Example — `Sizes.vue`:**

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

const sizes = CdsToggle.constants.sizes;
const enabled = ref(true);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-for="size in sizes" :key="size" v-model="enabled" :size="size" :label="size" hide-details />
  </div>
</template>
```

### States

`disabled` blocks the toggle and lowers the contrast, `readonly` forbids changing
the value, `error` paints the track with the error color. `indeterminate` is the
undefined state: the thumb stops in the middle while the value is unknown — when
only some of the nested options are on, for example. The first toggle removes it.

**Example — `States.vue`:**

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

const on = ref(true);
const off = ref(false);
const mixed = ref(false);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="off" label="Выключен" hide-details />
    <CdsToggle v-model="on" label="Включён" hide-details />
    <CdsToggle v-model="off" label="Disabled (выключен)" disabled hide-details />
    <CdsToggle v-model="on" label="Disabled (включён)" disabled hide-details />
    <CdsToggle v-model="on" label="Readonly" readonly hide-details />
    <CdsToggle v-model="off" label="Ошибка" error hide-details />
    <CdsToggle v-model="mixed" :indeterminate="true" label="Неопределённое состояние" hide-details />
  </div>
</template>
```

### Loading and icons

`loading` shows an indicator inside the thumb — handy while the setting is being
saved on the server; a string value sets the color of the loader. `true-icon` and
`false-icon` add an icon to the thumb for each position.

**Example — `LoadingAndIcons.vue`:**

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

const loading = ref(true);
const icon = ref(true);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="loading" loading label="Загрузка" hide-details />
    <CdsToggle v-model="icon" true-icon="success-fill" false-icon="error-fill" label="Иконки в бегунке" hide-details />
  </div>
</template>
```

### Colors

`color` paints the track of a switched-on toggle, `base-color` — of a switched-off
one, `thumb-color` — the thumb. The values are the names of the palette colors.

**Example — `Colors.vue`:**

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

const on = ref(true);
const off = ref(false);
const thumb = ref(false);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle
      v-model="on"
      color="brand-primary"
      label="Основной цвет дорожки во включённом положении (color)"
      hide-details
    />
    <CdsToggle v-model="off" base-color="purple" label="Фиолетовая дорожка в выключенном (base-color)" hide-details />
    <CdsToggle v-model="thumb" thumb-color="red" label="Красный бегунок (thumb-color)" hide-details />
  </div>
</template>
```

### Your own values

By default the model is `true`/`false`. `true-value` and `false-value` bind the
toggle to your own values — to an API field with a string status, for example.

**Example — `CustomValues.vue`:**

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

const status = ref('public');
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsToggle v-model="status" true-value="public" false-value="private" label="Открытый профиль" hide-details />
    <span>Значение модели: «{{ status }}»</span>
  </div>
</template>
```

### Messages

`messages` shows a hint under the toggle, `error-messages` — a ready error
message together with the error state. `hide-details` removes the bottom block
entirely.

**Example — `Messages.vue`:**

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

const backup = ref(true);
const newsletter = ref(false);
</script>

<template>
  <div class="flex flex-col gap-3 w-[350px] m-auto">
    <CdsToggle v-model="backup" label="Резервное копирование" messages="Копия создаётся каждую ночь в 03:00" />
    <CdsToggle
      v-model="newsletter"
      label="Рассылка по подписчикам"
      :error-messages="['Подтвердите домен, чтобы включить рассылку']"
    />
  </div>
</template>
```

### Slots

When the text props are not enough, parts of the component are replaced by slots.

| Slot name                    | Description                                            |
| :--------------------------- | :----------------------------------------------------- |
| `label`                      | Label content (replaces `label`)                       |
| `description`                | Description content (replaces `description`)           |
| `thumb`                      | Thumb content; receives the current icon and the model |
| `track-true` / `track-false` | Track content in the on / off position                 |
| `loader`                     | Custom loading indicator                               |
| `prepend` / `append`         | Elements before and after the control                  |
| `messages` / `details`       | Content of the messages block / the whole bottom block |

In the demo the `thumb` slot changes the icon of the thumb depending on the
value, and `track-true` and `track-false` show icons on the track.

**Example — `Slots.vue`:**

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

const visible = ref(true);
const annual = ref(true);
</script>

<template>
  <div class="flex flex-col gap-3 w-fit m-auto">
    <CdsToggle v-model="visible" label="Профиль виден в поиске" hide-details>
      <template #thumb>
        <CdsIcon :icon="visible ? 'visibility' : 'visibility-off'" />
      </template>
    </CdsToggle>

    <CdsToggle v-model="annual" size="xl" label="Годовая оплата" hide-details>
      <template #track-true>
        <CdsIcon icon="success-fill" :size="16" />
      </template>
      <template #track-false>
        <CdsIcon icon="error-fill" :size="16" />
      </template>
    </CdsToggle>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A toggle is for a setting that applies right after it is switched. | Consents and choices that go to the server together with the form are a checkbox, not a toggle. |
| Phrase the label positively: the on position turns the capability on. | A negation in the label forces the user to decode a double “no” when the toggle is off. |
| The label names the setting — the state is visible from the position and the color of the thumb. | A label repeating the state changes on every click: it is unclear what exactly is turned on. |

## Scenarios

### Notification settings

The main toggle controls the whole group: while notifications are off, the
channels are blocked through `disabled`. The choice of channels is kept though —
after switching back on the group returns to its previous values.

**Example — `NotificationSettings.vue`:**

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

const enabled = ref(true);
const channels = ref({ email: true, push: false, sms: false });
</script>

<template>
  <div class="flex flex-col gap-3 w-[320px] m-auto">
    <CdsToggle v-model="enabled" label="Уведомления" description="Сообщим о событиях в ваших закупках" hide-details />

    <div class="flex flex-col gap-3 pl-8">
      <CdsToggle v-model="channels.email" :disabled="!enabled" size="sm" label="Электронная почта" hide-details />
      <CdsToggle v-model="channels.push" :disabled="!enabled" size="sm" label="Push в браузере" hide-details />
      <CdsToggle v-model="channels.sms" :disabled="!enabled" size="sm" label="СМС" hide-details />
    </div>
  </div>
</template>
```

### Saving on the server

The setting is saved right after the switch: while the request is in flight the
toggle shows `loading` and does not accept clicks because of `readonly`. If the
server rejected the change, the value comes back and the reason is shown in
`error-messages`. Try switching the toggle off.

**Example — `ServerSave.vue`:**

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

const enabled = ref(true);
const loading = ref(false);
const errors = ref<string[]>([]);

const save = async (value: unknown) => {
  loading.value = true;
  errors.value = [];

  // Имитация запроса к серверу
  await new Promise((resolve) => setTimeout(resolve, 1000));

  loading.value = false;

  if (!value) {
    enabled.value = true;
    errors.value = ['Отключить двухфакторную аутентификацию может только администратор'];
  }
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsToggle
      v-model="enabled"
      label="Двухфакторная аутентификация"
      description="Код из приложения при каждом входе"
      :loading="loading"
      :readonly="loading"
      :error-messages="errors"
      @update:model-value="save"
    />
  </div>
</template>
```

### Paid options

Every toggle adds an option to the plan, and the total is recalculated at once —
the user sees the consequences of the choice before paying.

**Example — `PaidOptions.vue`:**

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

const options = [
  { key: 'analytics', label: 'Расширенная аналитика', description: 'Отчёты по закупкам и конкурентам', price: 900 },
  { key: 'support', label: 'Приоритетная поддержка', description: 'Ответ в течение часа', price: 500 },
  { key: 'api', label: 'Доступ к API', description: 'Интеграция с вашей ERP', price: 1500 }
] as const;

const selected = ref<Record<string, boolean>>({ analytics: true, support: false, api: false });

const total = computed(() => options.reduce((sum, option) => sum + (selected.value[option.key] ? option.price : 0), 0));
</script>

<template>
  <div class="flex flex-col gap-3 w-[350px] m-auto">
    <CdsToggle
      v-for="option in options"
      :key="option.key"
      v-model="selected[option.key]"
      :label="`${option.label} — ${option.price} ₽/мес`"
      :description="option.description"
      hide-details
    />

    <span class="font-semibold">Итого: {{ total }} ₽/мес</span>
  </div>
</template>
```

## API

### CdsToggle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `color` | `string \| undefined` | — | no | Component color |
| `defaultsTarget` | `string \| undefined` | — | no | Name of the child component the group prop values are passed to as defaults |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `error` | `boolean \| undefined` | — | no | Puts the component into the visual error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `falseIcon` | `IconValue \| undefined` | — | no | Icon of the unselected state |
| `falseValue` | `any` | — | no | Value for the false state. |
| `focused` | `boolean \| undefined` | — | no | 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` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `indeterminate` | `boolean \| undefined` | — | no | Indeterminate state of the toggle. |
| `inline` | `boolean \| undefined` | — | no | Renders the control as an inline element — the container does not stretch to the full width |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `loading` | `string \| boolean \| undefined` | `false` | no | Loading indicator. Accepts a boolean or a string with the color of the loader. |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `any` | — | no | Value of the component (v-model). In a group it is the value of the selected control, with `multiple` — an array of the selected values |
| `multiple` | `boolean \| null \| undefined` | `null` | no | Allows selecting several values — the model becomes an array. Turns on automatically when an array is passed to `modelValue` |
| `name` | `string \| undefined` | — | no | The `name` attribute of the native input element. In a group one name joins all the nested controls |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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'` | no | Size of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `thumbColor` | `string \| undefined` | — | no | Color of the thumb. |
| `trueIcon` | `IconValue \| undefined` | — | no | Icon of the selected state |
| `trueValue` | `any` | — | no | Value for the true state. |
| `type` | `string \| undefined` | — | no | Type of the native input element — `radio` or `checkbox`, for example |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `value` | `any` | — | no | Value used when the component is selected inside a group. When it is not set, a unique identifier is used. |
| `valueComparator` | `ValueComparator \| undefined` | `true` | no | Function comparing the model value with the `value` of the control. Deep comparison by default |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:focused` | `[focused: boolean]` | Fires when the focus state of the component changes. |
| `update:indeterminate` | `[value: boolean]` | Fires when the indeterminate state changes. |
| `update:modelValue` | `[value: any]` | Fires when the model of the component changes. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `CdsInputSlot` | Adds an element after the input |
| `default` | `{ backgroundColorClasses: Ref<string[], string[]>; backgroundColorStyles: Ref<CSSProperties, CSSProperties>; }` | Default slot |
| `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 |
| `input` | `SelectionControlSlot` | Slot for the default input element. |
| `label` | `{ label: string \| undefined; props: Record<string, any>; }` | Default slot of the CdsLabel component |
| `loader` | `LoaderSlotProps` | Slot for a custom loading indicator. |
| `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 |
| `prepend` | `CdsInputSlot` | Adds an element before the input |
| `thumb` | `{ icon: IconValue \| undefined; } & CdsToggleSlot` | Slot for the content of the thumb. |
| `track-false` | `CdsToggleSlot` | Slot for the content of the off part of the track. |
| `track-true` | `CdsToggleSlot` | Slot for the content of the on part of the track. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `isDirty` | `boolean` | Whether the input is dirty |
| `isDisabled` | `boolean` | Whether the input is disabled |
| `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 |
| `validate` | `(silent?: boolean) => Promise<string[]>` | Validates the input |

---

# CdsToolbar

_Category: Layouts · since 4.0.0_

_Tests: API 10/10 · 11 unit · lines 100% (v4.0.0-alpha.13) · a11y: 5 axe recommendations (v4.0.0-alpha.11)_

A horizontal bar with a title and actions: it fills the header and the footer of the application, and on a page it assembles the title of a section together with its buttons. `CdsToolbarTitle` stretches and pushes the left and the right groups to the edges on its own.

**See also:** The toolbar only lays the content out — the place in the layout is reserved by CdsHeader and CdsFooter. For navigating the subsections take CdsTabs; for an action bar over a record take CdsButtonGroup.

## Anatomy

The toolbar lines the content up in a row and centers it vertically. The
`CdsToolbarTitle` title takes all the free space, so the elements before it
stick to the left edge and the ones after it stick to the right.

## Variations

### Title

`CdsToolbarTitle` stretches and truncates long text with an ellipsis without
breaking the line. The `shrink` prop turns the stretching off: the title shrinks
to its content and stays next to the neighboring element — a handy way to put a
status or a counter right after the name.

**Example — `Title.vue`:**

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

<template>
  <div class="flex flex-col gap-4">
    <CdsToolbar bordered>
      <CdsToolbarTitle>Заголовок растягивается и разводит группы по краям</CdsToolbarTitle>
      <CdsButton size="sm">Действие</CdsButton>
    </CdsToolbar>

    <CdsToolbar bordered>
      <CdsToolbarTitle shrink>Заголовок с shrink остаётся рядом с кнопкой</CdsToolbarTitle>
      <CdsButton size="sm">Действие</CdsButton>
    </CdsToolbar>

    <CdsToolbar bordered>
      <CdsToolbarTitle>Очень длинный заголовок раздела, который не помещается в одну строку тулбара</CdsToolbarTitle>
      <CdsButton size="sm">Действие</CdsButton>
    </CdsToolbar>
  </div>
</template>
```

### Paddings

The `no-gutters` prop removes the inner paddings entirely — the toolbar aligns
with the content of the page. The `no-gutter` prop removes the padding on one
side: `start` or `end`. The `inset` prop does the opposite and adds a padding on
the left — that is how a nested second-level toolbar is set off.

**Example — `Spacing.vue`:**

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

<template>
  <div class="m-auto flex w-full max-w-[560px] flex-col gap-4">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">По умолчанию</span>
      <div class="rounded-200 border border-dashed border-line-primary">
        <CdsToolbar bordered>
          <CdsToolbarTitle>Заголовок раздела</CdsToolbarTitle>
          <CdsButton size="sm">Действие</CdsButton>
        </CdsToolbar>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">no-gutters</span>
      <div class="rounded-200 border border-dashed border-line-primary">
        <CdsToolbar bordered no-gutters>
          <CdsToolbarTitle>Заголовок раздела</CdsToolbarTitle>
          <CdsButton size="sm">Действие</CdsButton>
        </CdsToolbar>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">no-gutter="start"</span>
      <div class="rounded-200 border border-dashed border-line-primary">
        <CdsToolbar bordered no-gutter="start">
          <CdsToolbarTitle>Заголовок раздела</CdsToolbarTitle>
          <CdsButton size="sm">Действие</CdsButton>
        </CdsToolbar>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">no-gutter="end"</span>
      <div class="rounded-200 border border-dashed border-line-primary">
        <CdsToolbar bordered no-gutter="end">
          <CdsToolbarTitle>Заголовок раздела</CdsToolbarTitle>
          <CdsButton size="sm">Действие</CdsButton>
        </CdsToolbar>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">inset</span>
      <div class="rounded-200 border border-dashed border-line-primary">
        <CdsToolbar bordered inset>
          <CdsToolbarTitle>Заголовок раздела</CdsToolbarTitle>
          <CdsButton size="sm">Действие</CdsButton>
        </CdsToolbar>
      </div>
    </div>
  </div>
</template>
```

### Separator and color

The `bordered` prop draws the bottom border — it separates the title of a
section from its content. The `bg-color` and `color` props paint the background
and the text. Inside `CdsHeader` and `CdsFooter` the toolbar does not draw its
own background: the color comes from the part of the layout, so the bar does not
cover it.

**Example — `Colors.vue`:**

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

const bgColor = ref('default');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="bgColor" direction="horizontal" hide-details>
      <CdsRadio value="default" label="Цвет темы" />
      <CdsRadio value="neutral" label="neutral" />
      <CdsRadio value="indigo" label="indigo" />
      <CdsRadio value="lemon" label="lemon" />
    </CdsRadioGroup>

    <CdsToolbar bordered :bg-color="bgColor === 'default' ? undefined : bgColor">
      <CdsToolbarTitle>Заголовок раздела</CdsToolbarTitle>
      <CdsButton variant="soft" color="neutral" size="sm">Действие</CdsButton>
    </CdsToolbar>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A title in CdsToolbarTitle pushes the left and the right groups to the edges on its own. | A title as plain text does not stretch — the actions stick to the name. |
| One primary action and a couple of secondary icons — the toolbar stays readable. | Five buttons of equal weight in a row: it is unclear what matters here. |

## Scenarios

### Section title on a page

The name, the status and the actions in a single row: `shrink` keeps the status
next to the name, `mr-auto` pushes the buttons to the right edge, `no-gutters`
aligns the toolbar with the content of the card, and `bordered` separates the
header of the section from the text.

**Example — `PageHeader.vue`:**

```vue
<script setup lang="ts">
import {
  CdsButton,
  CdsCard,
  CdsFunctionalButton,
  CdsStatus,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <CdsCard class="m-auto w-full max-w-[640px] p-4">
    <CdsToolbar no-gutters bordered class="mb-4 gap-2">
      <CdsToolbarTitle shrink class="text-xl font-bold">Закупка №2401</CdsToolbarTitle>
      <CdsStatus status="success" text="Активна" variant="text" class="ml-2 mr-auto" />
      <CdsFunctionalButton icon="edit" aria-label="Редактировать" />
      <CdsButton size="sm" prepend-icon="download">Скачать</CdsButton>
    </CdsToolbar>

    <p class="text-content-secondary">Поставка серверного оборудования, приём заявок до 12 марта.</p>
  </CdsCard>
</template>
```

### Application header and footer

In `CdsHeader` the toolbar holds the menu button, the title and the profile; in
`CdsFooter` it holds the copyright. The background is set on the parts of the
layout, and the toolbar inherits it together with the contrasting text color.

**Example — `HeaderToolbar.vue`:**

```vue
<script setup lang="ts">
import {
  CdsAvatar,
  CdsFooter,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered bg-color="indigo">
        <CdsToolbar>
          <CdsFunctionalButton icon="menu" class="mr-2" aria-label="Открыть навигацию" />
          <CdsToolbarTitle>Портал закупок</CdsToolbarTitle>
          <CdsAvatar icon="user" />
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
        </CdsPage>
      </CdsMain>

      <CdsFooter bordered>
        <CdsToolbar>
          <CdsToolbarTitle>© 2026 Портал закупок</CdsToolbarTitle>
        </CdsToolbar>
      </CdsFooter>
    </CdsLayout>
  </div>
</template>
```

## API

### CdsToolbar

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `bordered` | `boolean \| undefined` | `false` | no | Shows the bottom border. |
| `color` | `string \| undefined` | — | no | Component color |
| `inset` | `boolean \| undefined` | `false` | no | Nested toolbar (indented from the left). |
| `noGutter` | `"start" \| "end" \| undefined` | — | no | Removes the padding on one side: `start` or `end`. |
| `noGutters` | `boolean \| undefined` | `false` | no | Removes all inner paddings. |
| `theme` | `string \| undefined` | — | no | Component theme |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Content of the toolbar. |

### CdsToolbarTitle

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `shrink` | `boolean \| undefined` | `false` | no | Shrinks the title to its content instead of stretching it. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Text of the title. |

---

# CdsTooltip

_Category: Content · since 4.0.0_

_Tests: API 55/55 · 50 unit · 7 e2e · lines 100% (v4.0.0-alpha.13) · a11y: 11 axe recommendations (v4.0.0-alpha.11)_

A tooltip briefly explains an interface element on hover or focus: it names an icon button, shows the full text of a truncated line, explains why an action is unavailable. It appears and disappears on its own — the user does not have to press or close anything.

**See also:** A tooltip is for a short text without interaction. A list of actions on click is the job of CdsMenu, and a dialog with a form and buttons is the job of CdsModal.

## Variations

### Activator

The element the tooltip is attached to is set through the `activator` slot: the
slot props (`v-bind="props"`) put the hover handlers and the `aria-describedby`
attribute on it. The content of the tooltip comes from the `text` prop or from
the default slot when you need markup. If the activator is already there and you
would rather not wrap it, put `CdsTooltip` inside it with `activator="parent"` —
that is how the examples in “Placement” and in the scenarios below are built.

**Example — `Default.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTooltip text="Текст всплывающей подсказки">
      <template #activator="{ props }">
        <CdsButton text="Проп text" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip>
      <template #activator="{ props }">
        <CdsButton variant="soft" color="brand" text="Слот default" v-bind="props" />
      </template>
      Подсказка с <strong>разметкой</strong> внутри
    </CdsTooltip>
  </div>
</template>
```

### Placement

The `location` prop sets the side of the activator the tooltip appears on: `top`
by default, `bottom`, `left`, `right` — and their combinations with an alignment
(`top left`, `bottom right`). If there is not enough room, the tooltip flips to
the opposite side by itself. The `offset` prop tunes the distance to the
activator.

**Example — `Location.vue`:**

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

const locations = [
  { location: 'left', icon: 'arrow-left' },
  { location: 'top', icon: 'arrow-up' },
  { location: 'bottom', icon: 'arrow-down' },
  { location: 'top left', icon: 'arrow-up-right' },
  { location: 'top right', icon: 'arrow-up-left' },
  { location: 'bottom left', icon: 'arrow-down-right' },
  { location: 'bottom right', icon: 'arrow-down-left' },
  { location: 'right', icon: 'arrow-right' }
] as const;
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <CdsButton
      v-for="{ location, icon } in locations"
      :key="location"
      variant="soft"
      color="neutral"
      :icon="icon"
      :aria-label="location"
    >
      <CdsTooltip activator="parent" :location="location">Всплывающая подсказка</CdsTooltip>
    </CdsButton>
  </div>
</template>
```

### Arrow

The arrow points at the activator and follows the actual position of the
tooltip — including after an automatic flip near the edge of the screen. The
`hide-arrow` prop hides it.

**Example — `HideArrow.vue`:**

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

<template>
  <div class="flex flex-wrap justify-center gap-4">
    <CdsTooltip location="top" text="Со стрелкой">
      <template #activator="{ props }">
        <CdsButton text="Со стрелкой" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip location="top" hide-arrow text="Без стрелки">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="neutral" text="Без стрелки" v-bind="props" />
      </template>
    </CdsTooltip>
  </div>
</template>
```

### Opening behavior

By default the tooltip opens on hover and on keyboard focus, with no delay. The
`open-delay` and `close-delay` props add a pause — the tooltip does not blink
when the cursor passes by. The `open-on-click` prop together with
`:open-on-hover="false"` switches opening to a click.

**Example — `OpenBehavior.vue`:**

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

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <CdsTooltip text="Открылась сразу по наведению">
      <template #activator="{ props }">
        <CdsButton text="Наведение" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip open-delay="300" close-delay="200" text="Открылась после паузы 300 мс">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="brand" text="С задержкой" v-bind="props" />
      </template>
    </CdsTooltip>

    <CdsTooltip open-on-click :open-on-hover="false" text="Открылась по клику">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="brand" text="По клику" v-bind="props" />
      </template>
    </CdsTooltip>
  </div>
</template>
```

### Controlling the display

`v-model` opens and closes the tooltip from code — this is how you show it in
response to interface events, not only on hover.

**Example — `VModel.vue`:**

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

const active = ref(false);
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-4">
    <CdsButton
      variant="soft"
      color="brand"
      :text="active ? 'Скрыть подсказку' : 'Показать подсказку'"
      @click="active = !active"
    />

    <CdsTooltip v-model="active" text="Подсказкой управляет v-model">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="neutral" icon="info" aria-label="Информация" v-bind="props" />
      </template>
    </CdsTooltip>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The tooltip names the action of an icon button — without it the icon is easy to misread. | The tooltip repeats the visible text word for word and adds nothing new. |
| A short phrase reads in a second — the tooltip does not hold the user up. | An instruction of several sentences does not get read inside a tooltip: move it into the interface or into a modal. |
| For a disabled button the tooltip explains why the action is closed and what to do about it. | A disabled button without an explanation leaves the user guessing. |

## Scenarios

### Icon button bar

A tooltip gives an icon button back the name of its action. `CdsTooltip` lives
inside the button with `activator="parent"` — there is no need to wrap the
markup. `aria-label` is still required: the tooltip appears on hover, while the
name of the action must be available at all times.

**Example — `IconToolbar.vue`:**

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

const actions = [
  { icon: 'edit', label: 'Редактировать' },
  { icon: 'copy', label: 'Дублировать' },
  { icon: 'download', label: 'Скачать' },
  { icon: 'delete', label: 'Удалить' }
];
</script>

<template>
  <div class="flex justify-center gap-1">
    <CdsButton
      v-for="action in actions"
      :key="action.icon"
      size="sm"
      variant="soft"
      color="neutral"
      :icon="action.icon"
      :aria-label="action.label"
    >
      <CdsTooltip activator="parent" :text="action.label" />
    </CdsButton>
  </div>
</template>
```

### Truncated text

When space is limited, long titles are cut off with `truncate` — the tooltip
shows the full text on hover over the line. The same `text` prop serves both as
the content of the line and as the content of the tooltip.

**Example — `TruncatedText.vue`:**

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

const documents = [
  'Договор поставки оборудования № 42-СТ от 14 марта',
  'Счёт на оплату № 5512 от 2 апреля',
  'Акт сверки взаиморасчётов за первый квартал'
];
</script>

<template>
  <div class="m-auto flex w-[240px] flex-col gap-1">
    <div v-for="doc in documents" :key="doc" class="truncate text-100">
      {{ doc }}
      <CdsTooltip activator="parent" :text="doc" />
    </div>
  </div>
</template>
```

### Unavailable action

A disabled button should not stay silent — the tooltip explains why the action
is closed. A button with `disabled` has its mouse events turned off, so the
tooltip is attached to a wrapper through `activator="parent"`. The `disabled`
prop of the tooltip itself turns it off as soon as the action becomes available.

**Example — `DisabledHint.vue`:**

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

const ready = ref(false);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCheckbox v-model="ready" label="Документы прикреплены" hide-details />

    <div class="inline-block">
      <CdsTooltip activator="parent" :disabled="ready" text="Прикрепите документы, чтобы отправить заявку" />
      <CdsButton :disabled="!ready" text="Отправить заявку" />
    </div>
  </div>
</template>
```

### Confirming an action

A tooltip can confirm an instant action when there is no room for a message —
copying to the clipboard, for example. The display is driven by `v-model` on
click, and `:open-on-hover="false"` keeps the tooltip from opening on a plain
hover. After a second and a half a timer closes it on its own.

**Example — `CopyFeedback.vue`:**

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

const copied = ref(false);

let timer: ReturnType<typeof setTimeout>;

function copy() {
  copied.value = true;
  clearTimeout(timer);
  timer = setTimeout(() => (copied.value = false), 1500);
}
</script>

<template>
  <div class="flex justify-center">
    <CdsTooltip v-model="copied" :open-on-hover="false" text="Ссылка скопирована">
      <template #activator="{ props }">
        <CdsButton
          variant="soft"
          color="brand"
          prepend-icon="link"
          text="Скопировать ссылку"
          v-bind="props"
          @click="copy"
        />
      </template>
    </CdsTooltip>
  </div>
</template>
```

### Onboarding

The `interactive` prop allows interaction with the content: hovering the tooltip
does not close it, and the elements inside stay clickable. So that the pointer
can cross the gap from the activator to the tooltip, an interactive tooltip
closes after a 250 ms delay; an explicit `close-delay` overrides it. Together with
`open-on-click` and `v-model` this makes an onboarding tooltip: a “Learn more”
link and a button that closes the tooltip. The `width` prop keeps the text width
comfortable to read.

**Example — `Onboarding.vue`:**

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

const active = ref(false);
</script>

<template>
  <div class="flex justify-center">
    <CdsTooltip v-model="active" interactive location="end" open-on-click :open-on-hover="false" width="268">
      <template #activator="{ props }">
        <CdsButton variant="soft" color="neutral" icon="message" aria-label="Что нового" v-bind="props" />
      </template>

      <div class="flex flex-col py-1">
        <div class="mb-1">
          <strong>Комментарии к заявке</strong>
        </div>
        <p>Теперь вопросы поставщику можно задавать прямо в карточке заявки — нажмите на иконку комментария.</p>
        <div class="mt-4 flex items-center justify-between">
          <a href="#" class="underline">Узнать больше</a>
          <CdsButton variant="solid" color="inverse" text="Понятно" @click="active = false" />
        </div>
      </div>
    </CdsTooltip>
  </div>
</template>
```

## API

### CdsTooltip

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| undefined` | — | no | The element that activates the component |
| `activatorProps` | `Record<string, any> \| undefined` | `{}` | no | Props for the activator element |
| `attach` | `string \| boolean \| Element \| undefined` | — | no | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
| `closeDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
| `closeOnBack` | `boolean \| undefined` | `false` | no | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. `persistent` overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
| `closeOnContentClick` | `boolean \| undefined` | — | no | Hide the component on a click on the content |
| `color` | `string \| undefined` | — | no | Background color of the tooltip. |
| `contained` | `boolean \| undefined` | — | no | Limits the size of the component and of its grid to the offset parent. Implies the `absolute` and `attach` props. (Note: the parent element must have `position: relative`.) |
| `contentClass` | `any` | — | no | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless `attach` is set) and cannot be selected with classes passed to the component directly. |
| `contentProps` | `any` | — | no | Applies custom props to the moved content |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `eager` | `boolean \| undefined` | `true` | no | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `hideArrow` | `boolean \| undefined` | — | no | Hides the arrow pointing at the activator. The arrow is shown by default. |
| `id` | `string \| undefined` | — | no | Unique id that links the tooltip to its activator. Generated automatically when omitted. |
| `interactive` | `boolean \| undefined` | — | no | Allows interaction with the tooltip content: hovering the content does not close it. The tooltip closes after a 250 ms delay unless `closeDelay` is set, so the pointer can cross the gap between the activator and the tooltip. |
| `location` | `Anchor \| undefined` | `'top'` | no | Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions |
| `locationStrategy` | `"static" \| "connected" \| LocationStrategyFunction \| undefined` | `'connected'` | no | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | `0` | no | Minimum component width |
| `modelValue` | `boolean \| undefined` | — | no | The v-model value of the component. If the component supports the **multiple** prop, an empty array is used by default. |
| `noClickAnimation` | `boolean \| undefined` | — | no | Disables the bounce effect on a click outside the content element when `persistent` is set. |
| `offset` | `string \| number \| number[] \| undefined` | `10` | no | Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target. |
| `opacity` | `string \| number \| undefined` | — | no | Opacity of the scrim element. Applies only when `scrim=true`. |
| `openDelay` | `string \| number \| undefined` | — | no | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
| `openOnClick` | `boolean \| undefined` | `false` | no | Show the component on a click on the activator |
| `openOnFocus` | `boolean \| undefined` | — | no | Show the component when the activator gets focus |
| `openOnHover` | `boolean \| undefined` | `true` | no | Show the component on hover over the activator |
| `origin` | `Anchor \| "auto" \| "overlap" \| undefined` | `'auto'` | no | Sets the anchor point of the overlay content that is aligned with the `location` anchor of the target. With "auto" the opposite side of the `location` point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS `transform-origin` property for the enter/leave transitions. |
| `persistent` | `boolean \| undefined` | — | no | A click outside the element or the Esc key does not close it. |
| `scrim` | `string \| boolean \| undefined` | `false` | no | Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color. |
| `scrollStrategy` | `"none" \| "close" \| "block" \| "reposition" \| ScrollStrategyFunction \| undefined` | `'reposition'` | no | Strategy applied when the component is active and the user scrolls the page. |
| `stickToTarget` | `boolean \| undefined` | — | no | Lets the overlay content go off screen while scrolling. |
| `target` | `(string & {}) \| Element \| "parent" \| ComponentPublicInstance \| "cursor" \| [x: number, y: number] \| undefined` | — | no | When `locationStrategy` is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
| `text` | `string \| undefined` | — | no | Text of the tooltip. Used when the default slot is not passed. |
| `theme` | `string \| undefined` | — | no | Component theme |
| `transition` | `string \| boolean \| (TransitionProps & { component?: Component \| undefined; }) \| null \| undefined` | `null` | no | Transition animation |
| `viewportMargin` | `string \| number \| undefined` | `12` | no | Sets a custom viewport margin for the overlay content |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `zIndex` | `string \| number \| undefined` | `2000` | no | The z-index value of the component. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: boolean]` | Fires when the tooltip is shown or hidden. Passes the new visibility state |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `activator` | `{ isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; }` | Slot for the element that acts as the activator of the overlay. |
| `default` | `{ isActive: Ref<boolean, boolean>; }` | Slot for the overlay content. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `activatorEl` | `HTMLElement \| undefined` | The DOM element of the activator. |
| `activatorRef` | `TemplateRef` | Template ref for assigning the activator manually. |
| `animateClick` | `() => void` | Runs the bounce animation of the content — the same as on a click outside a `persistent` overlay. |
| `contentEl` | `HTMLElement \| undefined` | The DOM element of the overlay content. |
| `globalTop` | `boolean` | Whether the overlay is the top one in the global stack of open overlays. |
| `rootEl` | `HTMLElement \| undefined` | The root DOM element of the overlay. |
| `scrimEl` | `HTMLElement \| undefined` | The DOM element of the scrim that dims the page. |
| `targetEl` | `HTMLElement \| undefined` | The DOM element of the positioning target. |
| `targetRef` | `TemplateRef` | Template ref for assigning the positioning target manually. |
| `updateLocation` | `((e: Event) => void) \| undefined` | Recalculates the position of the content relative to the target. |

---

# CdsTree

_Category: Content · since 4.0.0_

_Tests: API 116/116 · 152 unit · 8 e2e · 23 known bugs · lines 81.5% (v4.0.0-alpha.13) · a11y: 38 axe recommendations (v4.0.0-alpha.11)_

A tree shows a hierarchy: catalog sections, project files, an org structure. Nodes expand, get selected by a click or with checkboxes, load from the server and can be dragged, while virtual scrolling keeps everything smooth even with thousands of nodes.

**See also:** For a flat set without nesting take CdsList, for navigation between sections take CdsMenu, and for collapsible sections of content take CdsExpandablePanel.

## Anatomy

A tree node is made of the nesting indent, the expand switcher and the content
with the title. The checkbox appears with the `checkable` prop, the node icon
with `show-icon`.

## Variations

### Expanding nodes

The data of the tree is an array of `{ title, key, children }` nodes in the
`tree-data` prop. The expanded state is driven by `v-model:expanded-keys`; if
you do not need to control it, set the initial state through
`default-expanded-keys` or `default-expand-all`.

**Example — `Default.vue`:**

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

const basicTreeData: NTree.IDataNode[] = [
  {
    title: 'Родительский узел 1',
    key: '0-0',
    children: [
      {
        title: 'Родительский узел 1-0',
        key: '0-0-0',
        children: [
          { title: 'Вложенный узел', key: '0-0-0-0' },
          { title: 'Вложенный узел', key: '0-0-0-1' }
        ]
      },
      {
        title: 'Родительский узел 1-1',
        key: '0-0-1',
        children: [{ title: 'Вложенный узел', key: '0-0-1-0' }]
      }
    ]
  }
];

const expandedKeys = ref<string[]>(['0-0-0']);
const treeData = basicTreeData;
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <CdsTree v-model:expanded-keys="expandedKeys" :tree-data="treeData" />
  </div>
</template>
```

The `expand-action` prop expands a node by a click on the whole row: `click` for
a single click, `dblclick` for a double one. Without it a node expands only from
the switcher.

**Example — `ExpandAction.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsTree } from '@central-design-system/components';

const treeData = (action: NTree.TExpandAction): NTree.IDataNode[] => [
  {
    title: action === 'click' ? 'Нажми на меня' : 'Дважды нажми на меня',
    key: '0-0',
    children: [
      {
        title: 'Родительский узел 1-0',
        key: '0-0-0',
        children: [
          { title: 'Вложенный узел', key: '0-0-0-0' },
          { title: 'Вложенный узел', key: '0-0-0-1' }
        ]
      },
      {
        title: 'Родительский узел 1-1',
        key: '0-0-1',
        children: [{ title: 'Вложенный узел', key: '0-0-1-0' }]
      }
    ]
  }
];
</script>

<template>
  <div class="m-auto flex max-w-[320px] flex-col gap-4">
    <CdsTree :tree-data="treeData('click')" expand-action="click" />
    <CdsTree :tree-data="treeData('dblclick')" expand-action="dblclick" />
  </div>
</template>
```

### Selecting nodes and checkboxes

The `selectable` prop turns on selecting a node by a click
(`v-model:selected-keys`), `multiple` allows selecting several nodes. The
`checkable` prop adds checkboxes with their own `v-model:checked-keys` state:
checking a parent checks all its descendants, and a partially checked parent
goes into the indeterminate state (turned off with the `check-strictly` prop).
Individual nodes are disabled with the `disabled` and `disableCheckbox` flags
right in the data.

**Example — `Checkable.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsToggle, CdsTree } from '@central-design-system/components';
import { ref } from 'vue';

const treeData: NTree.IDataNode[] = [
  {
    title: 'Родительский узел 1',
    key: '0-0',
    children: [
      {
        title: 'Родительский узел 1-0',
        key: '0-0-0',
        children: [
          { title: 'Заблокированный узел', key: '0-0-0-0', disabled: true },
          { title: 'Заблокированный чекбокс', key: '0-0-0-1', disableCheckbox: true },
          { title: 'Вложенный узел', key: '0-0-0-2' }
        ]
      },
      {
        title: 'Родительский узел 1-1',
        key: '0-0-1',
        children: [
          { title: 'Вложенный узел', key: '0-0-1-0' },
          { title: 'Вложенный узел', key: '0-0-1-1' },
          { title: 'Вложенный узел', key: '0-0-1-2' }
        ]
      }
    ]
  }
];

const expandedKeys = ref<string[]>(['0-0-0']);
const selectedKeys = ref<string[]>(['0-0-0']);
const checkedKeys = ref<string[]>(['0-0-0']);
const isMultiple = ref(false);
</script>

<template>
  <div class="m-auto max-w-[420px]">
    <div class="mb-2">
      <CdsToggle v-model="isMultiple" label="Мультивыбор selectedKeys" hide-messages />
    </div>

    <CdsTree
      v-model:expanded-keys="expandedKeys"
      v-model:selected-keys="selectedKeys"
      v-model:checked-keys="checkedKeys"
      :tree-data="treeData"
      :multiple="isMultiple"
      checkable
      selectable
    />

    <div class="mt-4 flex justify-between gap-2 text-content-secondary">
      <div>
        <span>expandedKeys:</span>
        <pre>{{ expandedKeys }}</pre>
      </div>
      <div>
        <span>selectedKeys:</span>
        <pre>{{ selectedKeys }}</pre>
      </div>
      <div>
        <span>checkedKeys:</span>
        <pre>{{ checkedKeys }}</pre>
      </div>
    </div>
  </div>
</template>
```

### Connecting lines

The `show-line` prop draws lines between the nodes — in deep trees this makes it
easier to follow the levels. The `{ showLeafIcon }` object controls the icon of
the leaf nodes.

**Example — `ShowLine.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsToggle, CdsTree } from '@central-design-system/components';
import { ref } from 'vue';

const treeData: NTree.IDataNode[] = [
  {
    title: 'Родительский узел 1',
    key: '0-0',
    children: [
      {
        title: 'Родительский узел 1-0',
        key: '0-0-0',
        children: [
          { title: 'Вложенный узел 1', key: '0-0-0-0' },
          { title: 'Многострочный вложенный узел 2', key: '0-0-0-1' },
          { title: 'Вложенный узел 3', key: '0-0-0-2' }
        ]
      },
      {
        title: 'Родительский узел 1-1',
        key: '0-0-1',
        children: [{ title: 'Вложенный узел 1', key: '0-0-1-0' }]
      }
    ]
  },
  {
    title: 'Родительский узел 2',
    key: '0-1',
    children: [
      {
        title: 'Родительский узел 2-0',
        key: '0-1-0',
        children: [
          { title: 'Вложенный узел', key: '0-1-0-0' },
          { title: 'Вложенный узел', key: '0-1-0-1' }
        ]
      }
    ]
  }
];

const showLeafIcon = ref(false);

const onSelect = (selectedKeys: NTree.TKey[], info: unknown) => {
  console.log('selected', selectedKeys, info);
};
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <div class="mb-2">
      <CdsToggle v-model="showLeafIcon" label="Иконка листа" hide-messages />
    </div>
    <CdsTree :tree-data="treeData" :default-expanded-keys="['0-0-0']" :show-line="{ showLeafIcon }" @select="onSelect">
      <template #title="{ title, key }">
        <template v-if="key === '0-0-0-1'">
          <div>{{ title }}</div>
          <div>{{ title }}</div>
        </template>
        <template v-else>{{ title }}</template>
      </template>
    </CdsTree>
  </div>
</template>
```

### Icons and slots

Slots customize every part of a node; they receive the node context — `key`,
`title`, `expanded`, `selected` and other fields.

| Slot           | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `default`      | Declarative description of the nodes in markup instead of `tree-data` |
| `icon`         | Icon of the node. Shown with `show-icon`                              |
| `switcherIcon` | Icon of the expand switcher                                           |
| `title`        | Content of the node title                                             |

**Example — `Slots.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsIcon, CdsTree } from '@central-design-system/components';

const treeData: NTree.IDataNode[] = [
  {
    title: 'Родительский узел 1',
    key: '0-0',
    children: [
      {
        title: 'Родительский узел 1-0',
        key: '0-0-0',
        disabled: true,
        children: [
          { title: 'Вложенный узел', key: '0-0-0-0' },
          { title: 'Вложенный узел', key: '0-0-0-1' }
        ]
      },
      {
        title: 'Родительский узел 1-1',
        key: '0-0-1',
        children: [
          { title: 'Вложенный узел', key: '0-0-1-0' },
          { title: 'Вложенный узел', key: '0-0-1-1' }
        ]
      }
    ]
  }
];
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <CdsTree :tree-data="treeData" default-expand-all show-icon checkable>
      <template #switcherIcon="{ switcherCls, expanded }">
        <CdsIcon :name="expanded ? 'minus' : 'add'" :class="switcherCls" />
      </template>

      <template #icon="{ key, selected }">
        <CdsIcon v-if="key === '0-0'" name="add" />
        <CdsIcon v-else-if="key === '0-0-0'" name="settings" />
        <CdsIcon v-else-if="selected" name="info-fill" />
        <CdsIcon v-else name="info" />
      </template>

      <template #title="{ title, key }">
        <div v-if="key === '0-0-1-0'" class="flex items-center gap-1">
          <strong>{{ title }}</strong>
          <CdsIcon name="star" />
        </div>
        <template v-else>{{ title }}</template>
      </template>
    </CdsTree>
  </div>
</template>
```

### Asynchronous loading

The `load-data` prop loads the child nodes on the first expand: the function
receives the node, returns a promise and adds `children` to the data. Until the
promise resolves, the node shows a loading indicator.

**Example — `LoadData.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsTree } from '@central-design-system/components';
import { ref, unref } from 'vue';

const treeData = ref<NTree.IDataNode[]>([
  { title: 'Родительский асинхронный узел', key: '0' },
  { title: 'Родительский асинхронный узел', key: '1' },
  { title: 'Родительский узел', key: '2', isLeaf: true }
]);

const expandedKeys = ref<string[]>([]);
const selectedKeys = ref<string[]>([]);

const onLoadData = (treeNode: NTree.IEventDataNode) =>
  new Promise<void>((resolve) => {
    if (treeNode.dataRef && treeNode.dataRef.children) {
      resolve();
      return;
    }

    setTimeout(() => {
      if (!treeNode.dataRef) return;

      treeNode.dataRef.children = [
        { title: 'Вложенный асинхронный узел', key: `${treeNode.eventKey}-0` },
        { title: 'Вложенный асинхронный узел', key: `${treeNode.eventKey}-1` }
      ];

      treeData.value = [...unref(treeData)];

      resolve();
    }, 1000);
  });
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <CdsTree
      v-model:expanded-keys="expandedKeys"
      v-model:selected-keys="selectedKeys"
      :tree-data="treeData"
      :load-data="onLoadData"
    />
  </div>
</template>
```

### Dragging

The `draggable` prop allows dragging the nodes; the `{ icon: true }` variant
shows a drag handle. The tree does not change the data by itself — the `@drop`
handler rebuilds `tree-data`, and `allow-drop` limits the valid drop targets.

**Example — `Draggable.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsTree } from '@central-design-system/components';
import { ref, unref } from 'vue';

const generatedData: NTree.IDataNode[] = [];

const x = 5;
const y = 3;
const z = 2;

const generateData = (level: number, preKey = '0', treeNode: NTree.IDataNode[] = generatedData) => {
  const children: string[] = [];
  for (let i = 0; i < x; i++) {
    const key = `${preKey}-${i}`;
    treeNode.push({ title: key, key });
    if (i < y) {
      children.push(key);
    }
  }
  if (level < 0) {
    return treeNode;
  }
  const nextLevel = level - 1;
  children.forEach((key, index) => {
    treeNode[index].children = [];
    generateData(nextLevel, key, treeNode[index].children);
  });
};

generateData(z);

const treeData = ref<NTree.IDataNode[]>(generatedData);

const onDrop = (info: any) => {
  const dropKey = info.node.key;
  const dragKey = info.dragNode!.key;
  const dropPos = info.node.pos!.split('-');
  const dropPosition = info.dropPosition - Number(dropPos[dropPos.length - 1]);

  const loop = (data: NTree.IDataNode[] | undefined, key: string | number, callback: any) => {
    if (!data) return;
    data.forEach((item, index) => {
      if (item.key === key) {
        return callback(item, index, data);
      }
      if (item.children) {
        return loop(item.children, key, callback);
      }
    });
  };

  const data = [...unref(treeData)];
  let dragObj: NTree.IDataNode;

  loop(data, dragKey!, (item: NTree.IDataNode, index: number, arr: NTree.IDataNode[]) => {
    arr.splice(index, 1);
    dragObj = item;
  });

  if (!info.dropToGap) {
    loop(data, dropKey!, (item: NTree.IDataNode) => {
      item.children = item.children || [];
      item.children.unshift(dragObj);
    });
  } else if ((info.node.children || []).length > 0 && info.node.expanded && dropPosition === 1) {
    loop(data, dropKey!, (item: NTree.IDataNode) => {
      item.children = item.children || [];
      item.children.unshift(dragObj);
    });
  } else {
    let ar: NTree.IDataNode[] = [];
    let i = 0;
    loop(data, dropKey!, (_item: NTree.IDataNode, index: number, arr: NTree.IDataNode[]) => {
      ar = arr;
      i = index;
    });
    if (dropPosition === -1) {
      ar.splice(i, 0, dragObj!);
    } else {
      ar.splice(i + 1, 0, dragObj!);
    }
  }

  treeData.value = data;
};
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <CdsTree :tree-data="treeData" :draggable="{ icon: true }" block-node @drop="onDrop" />
  </div>
</template>
```

### Virtual scrolling

The virtual list is on by default (the `virtual` prop). Set `height` and the
tree scrolls inside a fixed height, rendering only the visible nodes: thousands
of rows do not slow the page down.

**Example — `VirtualScroll.vue`:**

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

const selectedKeys = ref<string[]>(['0-0-0', '0-0-1']);
const checkedKeys = ref<string[]>(['0-0-0', '0-0-1']);

watch(selectedKeys, () => console.log('selectedKeys', unref(selectedKeys)));
watch(checkedKeys, () => console.log('checkedKeys', unref(checkedKeys)));

const dig = (path = '0', level = 3): NTree.IDataNode[] => {
  const list: NTree.IDataNode[] = [];
  for (let i = 0; i < 10; i += 1) {
    const key = `${path}-${i}`;
    const treeNode: NTree.IDataNode = { title: key, key };
    if (level > 0) {
      treeNode.children = dig(key, level - 1);
    }
    list.push(treeNode);
  }
  return list;
};
const treeData = dig();
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <CdsTree
      v-model:selected-keys="selectedKeys"
      v-model:checked-keys="checkedKeys"
      :tree-data="treeData"
      :height="300"
      default-expand-all
      checkable
    />
  </div>
</template>
```

### Directory mode

`CdsTreeDirectory` is a tree with presets for files and folders: directory
icons, expanding on click and full-width nodes. It accepts the same props as
`CdsTree`.

**Example — `Directory.vue`:**

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

const treeData: NTree.IDataNode[] = [
  {
    title: 'Новая папка',
    key: '0-0',
    children: [
      { title: 'index.ts', key: '0-0-0', isLeaf: true },
      { title: 'index.html', key: '0-0-1', isLeaf: true }
    ]
  },
  {
    title: 'Другая папка',
    key: '0-1',
    children: [
      { title: 'skuff.png', key: '0-1-0', isLeaf: true },
      { title: 'newFile.md', key: '0-1-1', isLeaf: true }
    ]
  }
];

const expandedKeys = ref<string[]>(['0-0']);
const selectedKeys = ref<string[]>([]);
</script>

<template>
  <div class="m-auto max-w-[320px]">
    <CdsTreeDirectory
      v-model:expanded-keys="expandedKeys"
      v-model:selected-keys="selectedKeys"
      :tree-data="treeData"
      multiple
    />
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A tree reveals nesting: its nodes have child levels. | A flat set without a hierarchy is a list — take CdsList. |
| For selecting many nodes turn on checkboxes — the selection state is visible at once. | Multiple selection by clicking nodes is invisible and expects the user to know about Ctrl. |
| Short node titles read like a table of contents. | Long phrases wrap onto several lines and break the rhythm of the tree. |

## Scenarios

### Picking sections for an export

Checkboxes collect a set of sections, and the counter in the button hints at the
size of the selection. The `loading` prop of the button shows the export in
progress, `disabled` prevents starting it with an empty selection.

**Example — `CategoryExport.vue`:**

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

const treeData: NTree.IDataNode[] = [
  {
    title: 'Электроника',
    key: 'electronics',
    children: [
      { title: 'Ноутбуки', key: 'laptops' },
      { title: 'Мониторы', key: 'monitors' }
    ]
  },
  {
    title: 'Мебель',
    key: 'furniture',
    children: [
      { title: 'Столы', key: 'tables' },
      { title: 'Кресла', key: 'chairs' }
    ]
  },
  { title: 'Канцтовары', key: 'stationery' }
];

const checkedKeys = ref<NTree.TKey[]>([]);
const loading = ref(false);
const exportedCount = ref(0);

const count = computed(() => checkedKeys.value.length);

const onExport = () => {
  loading.value = true;
  exportedCount.value = 0;

  setTimeout(() => {
    exportedCount.value = count.value;
    checkedKeys.value = [];
    loading.value = false;
  }, 1500);
};
</script>

<template>
  <div class="m-auto flex w-[280px] flex-col gap-2">
    <CdsTree v-model:checked-keys="checkedKeys" :tree-data="treeData" default-expand-all checkable />

    <CdsButton :text="`Выгрузить разделы (${count})`" :loading="loading" :disabled="!count" @click="onExport" />

    <span v-if="exportedCount" class="text-center text-content-secondary">
      Выгружено разделов: {{ exportedCount }}
    </span>
  </div>
</template>
```

### Search across the tree

An input field filters `tree-data` on the fly: the matches and their parents stay
in the tree, and `v-model:expanded-keys` expands the branches with the found
nodes. When there are no matches, show an empty state instead of the tree.

**Example — `TreeSearch.vue`:**

```vue
<script setup lang="ts">
import type { NTree } from '@central-design-system/components';
import { CdsTextInput, CdsTree } from '@central-design-system/components';
import { computed, ref, watch } from 'vue';

const structure: NTree.IDataNode[] = [
  {
    title: 'Компания',
    key: 'company',
    children: [
      {
        title: 'Коммерческий департамент',
        key: 'commercial',
        children: [
          { title: 'Отдел продаж', key: 'sales' },
          { title: 'Отдел закупок', key: 'purchases' }
        ]
      },
      {
        title: 'ИТ-департамент',
        key: 'it',
        children: [
          { title: 'Разработка', key: 'development' },
          { title: 'Поддержка', key: 'support' }
        ]
      },
      {
        title: 'Финансовый департамент',
        key: 'finance',
        children: [{ title: 'Бухгалтерия', key: 'accounting' }]
      }
    ]
  }
];

const query = ref('');
const expandedKeys = ref<NTree.TKey[]>(['company']);

const filterNodes = (nodes: NTree.IDataNode[], text: string): NTree.IDataNode[] =>
  nodes.flatMap((node) => {
    const children = filterNodes(node.children ?? [], text);
    const matched = String(node.title).toLowerCase().includes(text);

    if (!matched && !children.length) return [];

    return [{ ...node, children: children.length ? children : node.children }];
  });

const treeData = computed(() => {
  const text = query.value.trim().toLowerCase();

  return text ? filterNodes(structure, text) : structure;
});

const collectParentKeys = (nodes: NTree.IDataNode[]): NTree.TKey[] =>
  nodes.flatMap((node) =>
    node.children?.length && node.key != null ? [node.key, ...collectParentKeys(node.children)] : []
  );

watch(treeData, (nodes) => {
  if (query.value.trim()) {
    expandedKeys.value = collectParentKeys(nodes);
  }
});
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-2">
    <CdsTextInput
      v-model="query"
      placeholder="Найти подразделение"
      prepend-inner-icon="search"
      clearable
      hide-messages
    />

    <CdsTree v-if="treeData.length" v-model:expanded-keys="expandedKeys" :tree-data="treeData" />

    <span v-else class="text-center text-content-secondary">Ничего не найдено</span>
  </div>
</template>
```

### Project files

`CdsTreeDirectory` with `v-model:selected-keys` works as a file explorer: a
click on a folder expands it, a click on a file selects it. The node keys hold
the path to the file, so the selected item is ready to be shown or requested
right away.

**Example — `FileExplorer.vue`:**

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

const treeData: NTree.IDataNode[] = [
  {
    title: 'src',
    key: 'src',
    children: [
      {
        title: 'components',
        key: 'src/components',
        children: [
          { title: 'AppHeader.vue', key: 'src/components/AppHeader.vue', isLeaf: true },
          { title: 'AppFooter.vue', key: 'src/components/AppFooter.vue', isLeaf: true }
        ]
      },
      { title: 'main.ts', key: 'src/main.ts', isLeaf: true }
    ]
  },
  {
    title: 'public',
    key: 'public',
    children: [{ title: 'favicon.svg', key: 'public/favicon.svg', isLeaf: true }]
  },
  { title: 'package.json', key: 'package.json', isLeaf: true }
];

const expandedKeys = ref<NTree.TKey[]>(['src']);
const selectedKeys = ref<NTree.TKey[]>([]);

const findNode = (nodes: NTree.IDataNode[], key: NTree.TKey): NTree.IDataNode | undefined => {
  for (const node of nodes) {
    if (node.key === key) return node;

    const child = findNode(node.children ?? [], key);
    if (child) return child;
  }

  return undefined;
};

const selectedFile = computed(() => {
  const key = selectedKeys.value[0];
  if (key === undefined) return undefined;

  const node = findNode(treeData, key);

  return node?.isLeaf ? String(key) : undefined;
});
</script>

<template>
  <div class="m-auto flex w-[320px] flex-col gap-2">
    <CdsTreeDirectory v-model:expanded-keys="expandedKeys" v-model:selected-keys="selectedKeys" :tree-data="treeData" />

    <span class="text-center text-content-secondary">
      {{ selectedFile ? `Открыт файл: ${selectedFile}` : 'Выберите файл' }}
    </span>
  </div>
</template>
```

## API

### CdsTree

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `allowDrop` | `NTree.TAllowDrop<NTree.IDataNode> \| undefined` | `true` | no | Decides whether a node accepts a drop |
| `autoExpandParent` | `boolean \| undefined` | `false` | no | Expands the parent node automatically |
| `blockNode` | `boolean \| undefined` | `false` | no | The tree node fills all the remaining horizontal space |
| `checkable` | `boolean \| undefined` | `false` | no | Adds a checkbox before the tree nodes |
| `checkedKeys` | `NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; } \| undefined` | — | no | (v-model) Keys of the checked tree nodes. When the key of a parent node is given, all its child nodes become checked; and the other way around, when the key of a child node is given, its parent node becomes checked too. When `checkable` and `checkStrictly` are both true, the object has the `checked` and `halfChecked` fields, and checking a child or a parent node no longer affects the other. |
| `checkStrictly` | `boolean \| undefined` | `false` | no | Checks only the node itself, without its parents and children. |
| `defaultExpandAll` | `boolean \| undefined` | `false` | no | Expands all the nodes by default |
| `defaultExpandedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Expands all the nodes by default |
| `defaultExpandParent` | `boolean \| undefined` | `true` | no | Expands the parent nodes by default |
| `defaultSelectedKeys` | `NTree.TKey[] \| undefined` | — | no | Tree nodes selected by default |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `draggable` | `boolean \| NTree.TDraggableConfig \| undefined` | `false` | no | Allows dragging the tree nodes |
| `expandAction` | `NTree.TExpandAction \| undefined` | — | no | Action that expands or collapses the tree nodes |
| `expandedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the expanded tree nodes. |
| `fieldNames` | `NTree.IFieldNames \| undefined` | — | no | Maps the title, key and children fields of a tree node to the matching fields of treeData |
| `filterTreeNode` | `((treeNode: NTree.IEventDataNode) => boolean) \| undefined` | — | no | Function that filters (highlights) the tree nodes. When it returns true, the node is highlighted. |
| `height` | `number \| undefined` | — | no | Height of the virtual scrolling list |
| `icon` | `((nodeProps: NTree.ITreeNodeAttribute) => any) \| undefined` | — | no | Icon of the tree node (also available through slot#icon) |
| `loadData` | `((treeNode: NTree.IEventDataNode) => Promise<any>) \| undefined` | — | no | Loads the data of a tree node asynchronously |
| `loadedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Keys of the already loaded tree nodes. Required to work with loadData |
| `multiple` | `boolean \| undefined` | `false` | no | Allows selecting several tree nodes |
| `openAnimation` | `Function \| undefined` | — | no | Animation function for expanding and collapsing a tree node |
| `selectable` | `boolean \| undefined` | `false` | no | Makes the tree nodes selectable |
| `selectedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the selected tree nodes. |
| `showIcon` | `boolean \| undefined` | `false` | no | Shows the icon of the tree node |
| `showLine` | `boolean \| { showLeafIcon: string \| boolean; } \| undefined` | — | no | Shows the lines between the tree nodes |
| `switcherIcon` | `((nodeProps: SwitcherIconProps) => any) \| undefined` | — | no | Icon of the expand/collapse switcher (also available through slot#switcherIcon) |
| `theme` | `string \| undefined` | — | no | Component theme |
| `treeData` | `NTree.IDataNode[] \| undefined` | — | no | Data of the tree |
| `virtual` | `boolean \| undefined` | `true` | no | Enables virtual scrolling of the list inside the tree; enabled by default |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `check` | `[checked: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }, info: NTree.ICheckInfo]` | A node was checked with its checkbox. |
| `click` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Click on a node. |
| `dblclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node. |
| `doubleclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node (alias). |
| `dragend` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node finished. |
| `dragenter` | `[info: NTree.TNodeDragEventParams & { expandedKeys: NTree.TKey[]; }]` | A dragged node entered the drop area. |
| `dragleave` | `[info: NTree.TNodeDragEventParams]` | A dragged node left the drop area. |
| `dragover` | `[info: NTree.TNodeDragEventParams]` | A dragged node moves inside the drop area. |
| `dragstart` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node started. |
| `drop` | `[info: NTree.TNodeDragEventParams & { dragNode: NTree.IEventDataNode; dragNodesKeys: NTree.TKey[]; dropPosition: number; dropToGap: boolean; }]` | A node was dropped. |
| `expand` | `[expandedKeys: NTree.TKey[], info: { node: NTree.IEventDataNode; expanded: boolean; nativeEvent: MouseEvent; }]` | A node was expanded or collapsed. |
| `load` | `[loadedKeys: NTree.TKey[], info: { event: "load"; node: NTree.IEventDataNode; }]` | Children of a node were loaded (async loadData). |
| `rightClick` | `[info: { event: MouseEvent; node: NTree.IEventDataNode; }]` | Right click on a node. |
| `select` | `[selectedKeys: NTree.TKey[], info: { event: "select"; selected: boolean; node: NTree.IEventDataNode; selectedNodes: NTree.IDataNode[]; nativeEvent: MouseEvent; }]` | A node was selected. |
| `update:checkedKeys` | `[checkedKeys: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }]` | Checking of a node changed (v-model). |
| `update:expandedKeys` | `[expandedKeys: NTree.TKey[]]` | Expansion of a node changed (v-model). |
| `update:selectedKeys` | `[selectedKeys: NTree.TKey[]]` | Selection of a node changed (v-model). |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `any` | Tree nodes by default (when described declaratively in markup). |
| `icon` | `NTree.ITreeNodeAttribute` | Custom icon of the tree node. |
| `switcherIcon` | `any` | Custom icon of the expand/collapse switcher. |
| `title` | `NTree.IEventDataNode` | Custom title of the tree node. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `halfCheckedKeys` | `any` | Keys of the nodes with partially checked children — the “half checked” state. |
| `loadingKeys` | `any` | Keys of the nodes whose children are being lazily loaded right now. |
| `scrollTo` | `ScrollTo` | Scrolls the tree to a node by its key or to a given position. |
| `treeRef` | `any` | Reference to the internal tree instance. |

### CdsTreeDirectory

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `allowDrop` | `NTree.TAllowDrop<NTree.IDataNode> \| undefined` | `true` | no | Decides whether a node accepts a drop |
| `autoExpandParent` | `boolean \| undefined` | `false` | no | Expands the parent node automatically |
| `blockNode` | `boolean \| undefined` | `false` | no | The tree node fills all the remaining horizontal space |
| `checkable` | `boolean \| undefined` | `false` | no | Adds a checkbox before the tree nodes |
| `checkedKeys` | `NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; } \| undefined` | — | no | (v-model) Keys of the checked tree nodes. When the key of a parent node is given, all its child nodes become checked; and the other way around, when the key of a child node is given, its parent node becomes checked too. When `checkable` and `checkStrictly` are both true, the object has the `checked` and `halfChecked` fields, and checking a child or a parent node no longer affects the other. |
| `checkStrictly` | `boolean \| undefined` | `false` | no | Checks only the node itself, without its parents and children. |
| `defaultExpandAll` | `boolean \| undefined` | `false` | no | Expands all the nodes by default |
| `defaultExpandedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Expands all the nodes by default |
| `defaultExpandParent` | `boolean \| undefined` | `true` | no | Expands the parent nodes by default |
| `defaultSelectedKeys` | `NTree.TKey[] \| undefined` | — | no | Tree nodes selected by default |
| `draggable` | `boolean \| NTree.TDraggableConfig \| undefined` | `false` | no | Allows dragging the tree nodes |
| `expandAction` | `string \| false \| undefined` | — | no | Action that expands or collapses the tree nodes |
| `expandedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the expanded tree nodes. |
| `fieldNames` | `NTree.IFieldNames \| undefined` | — | no | Maps the title, key and children fields of a tree node to the matching fields of treeData |
| `filterTreeNode` | `((treeNode: NTree.IEventDataNode) => boolean) \| undefined` | — | no | Function that filters (highlights) the tree nodes. When it returns true, the node is highlighted. |
| `height` | `number \| undefined` | — | no | Height of the virtual scrolling list |
| `icon` | `((nodeProps: NTree.ITreeNodeAttribute) => any) \| undefined` | — | no | Icon of the tree node (also available through slot#icon) |
| `loadData` | `((treeNode: NTree.IEventDataNode) => Promise<any>) \| undefined` | — | no | Loads the data of a tree node asynchronously |
| `loadedKeys` | `NTree.TKey[] \| undefined` | `[]` | no | Keys of the already loaded tree nodes. Required to work with loadData |
| `multiple` | `boolean \| undefined` | `false` | no | Allows selecting several tree nodes |
| `openAnimation` | `Function \| undefined` | — | no | Animation function for expanding and collapsing a tree node |
| `selectable` | `boolean \| undefined` | `false` | no | Makes the tree nodes selectable |
| `selectedKeys` | `NTree.TKey[] \| undefined` | — | no | (v-model) Keys of the selected tree nodes. |
| `showIcon` | `boolean \| undefined` | `false` | no | Shows the icon of the tree node |
| `showLine` | `boolean \| { showLeafIcon: string \| boolean; } \| undefined` | — | no | Shows the lines between the tree nodes |
| `switcherIcon` | `((nodeProps: SwitcherIconProps) => any) \| undefined` | — | no | Icon of the expand/collapse switcher (also available through slot#switcherIcon) |
| `treeData` | `NTree.IDataNode[] \| undefined` | — | no | Data of the tree |
| `virtual` | `boolean \| undefined` | `true` | no | Enables virtual scrolling of the list inside the tree; enabled by default |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `check` | `[checked: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }, info: NTree.ICheckInfo]` | A node was checked with its checkbox. |
| `click` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Click on a node. |
| `dblclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node. |
| `doubleclick` | `[event: MouseEvent, node: NTree.IEventDataNode]` | Double click on a node (alias). |
| `dragend` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node finished. |
| `dragenter` | `[info: NTree.TNodeDragEventParams & { expandedKeys: NTree.TKey[]; }]` | A dragged node entered the drop area. |
| `dragleave` | `[info: NTree.TNodeDragEventParams]` | A dragged node left the drop area. |
| `dragover` | `[info: NTree.TNodeDragEventParams]` | A dragged node moves inside the drop area. |
| `dragstart` | `[info: NTree.TNodeDragEventParams]` | Dragging of a node started. |
| `drop` | `[info: NTree.TNodeDragEventParams & { dragNode: NTree.IEventDataNode; dragNodesKeys: NTree.TKey[]; dragPosition: number; dropToGap: boolean; }]` | A node was dropped. |
| `expand` | `[expandedKeys: NTree.TKey[], info: { node: NTree.IEventDataNode; expanded: boolean; nativeEvent: MouseEvent; }]` | A node was expanded or collapsed. |
| `load` | `[treeNode: NTree.IEventDataNode]` | Children of a node were loaded (async loadData). |
| `rightClick` | `[info: { event: MouseEvent; node: NTree.IEventDataNode; }]` | Right click on a node. |
| `select` | `[selectedKeys: NTree.TKey[], info: { event: "select"; selected: boolean; node: NTree.IEventDataNode; selectedNodes: NTree.IDataNode[]; nativeEvent: MouseEvent; }]` | A node was selected. |
| `update:checkedKeys` | `[checkedKeys: NTree.TKey[] \| { checked: NTree.TKey[]; halfChecked: NTree.TKey[]; }]` | Checking of a node changed (v-model). |
| `update:expandedKeys` | `[expandedKeys: NTree.TKey[]]` | Expansion of a node changed (v-model). |
| `update:selectedKeys` | `[selectedKeys: NTree.TKey[]]` | Selection of a node changed (v-model). |

### CdsTreeNode

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | — | no | Highlights the node as active |
| `checkable` | `boolean \| undefined` | — | no | Shows a checkbox next to the node |
| `data` | `NTree.IDataNode \| undefined` | `undefined as unknown as NTree.IDataNode` | no | Data of the node — the original list item the node is built from |
| `disableCheckbox` | `boolean \| undefined` | — | no | Disables only the checkbox of the node, leaving the node itself available |
| `disabled` | `boolean \| undefined` | — | no | Disables the node: it cannot be selected, checked or expanded |
| `domRef` | `((arg: any) => void) \| undefined` | — | no | Callback that receives the DOM element of the node after mounting |
| `eventKey` | `NTree.TKey \| undefined` | `''` | no | Unique key of the node — the tree uses it to track selection, expansion and checking |
| `icon` | `Function \| undefined` | — | no | Function that returns the icon of the node |
| `isEnd` | `boolean[] \| undefined` | — | no | “Last on its level” flags for every nesting level — the connecting lines are drawn from them |
| `isLeaf` | `boolean \| undefined` | — | no | The node is a leaf: it has no children and shows no expand switcher |
| `isStart` | `boolean[] \| undefined` | — | no | “First on its level” flags for every nesting level — the connecting lines are drawn from them |
| `parent` | `NTree.IDataNode \| undefined` | `undefined as unknown as NTree.IDataNode` | no | Data of the parent node. Not set for the top-level nodes |
| `prefixCls` | `string \| undefined` | — | no | Prefix of the CSS classes of the node |
| `selectable` | `boolean \| undefined` | — | no | Allows selecting the node |
| `switcherIcon` | `Function \| undefined` | — | no | Function that returns the icon of the expand switcher |
| `title` | `string \| (Function & string) \| undefined` | — | no | Tree node title: a string or a render function |

---

# CdsUploader

_Category: Controls · since 4.0.0_

_Tests: API 77/77 · 102 unit · 3 e2e · 18 known bugs · lines 96.8% (v4.0.0-alpha.13) · a11y: 27 axe recommendations (v4.0.0-alpha.11)_

The uploader sends files to the server right from the interface: the user picks them in the system dialog or drags them onto the button, and the component shows the list of what was uploaded — with a status, progress, downloading and removal. Every step of the file lifecycle comes with an event.

**See also:** The uploader sends the files over HTTP itself. If the files only have to be picked and sent together with the form, take the CdsFileInput field, and for a drop zone with image previews — CdsFileUpload.

## Anatomy

The first diagram is the frame: the label, the description, the upload button and
the messages. The second one is an item of the file list during the upload: the
status, the name as a link, the actions and the progress bar.

## Variations

### The upload button

By default the upload is started by the primary "Загрузить файл" button with the
`upload-icon` icon. The `button-props` prop passes any
CdsButton props to the button, and the `default` slot
replaces it entirely — the ready props of the button arrive in the `props` slot
argument.

**Example — `TriggerButton.vue`:**

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

const documents = ref<NUploader.IUploadFile[]>([]);
const photos = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader
      v-model="documents"
      label="Свойства кнопки"
      action="https://user1694090019726.requestly.dev/upload"
      :button-props="{ variant: 'soft', text: 'Прикрепить файлы' }"
    />

    <CdsUploader
      v-model="photos"
      label="Своя кнопка через слот"
      action="https://user1694090019726.requestly.dev/upload"
    >
      <template #default="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral" prepend-icon="add" text="Добавить фото" />
      </template>
    </CdsUploader>
  </div>
</template>
```

### Allowed file types

The `accept` prop limits the choice in the system dialog and filters out the
unsuitable files on a drop — the rejected ones arrive in the `reject` event.

**Example — `Default.vue`:**

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

const files = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка файла"
      description="Подойдут только изображения jpeg, jpg или png"
      action="https://user1694090019726.requestly.dev/upload"
      accept="image/png, image/jpeg"
    />
  </div>
</template>
```

### The file list

The list of the uploaded files lives in `v-model` — put the files received from
the server into it and they will be shown right away. The `show-upload-list` prop
controls the list: `false` hides it entirely, an object turns on the download and
removal icons.

**Example — `FileList.vue`:**

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

const files = ref<NUploader.IUploadFile[]>([
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  },
  {
    uid: '2',
    name: 'B2b-elbcp-180x130.png',
    status: 'done',
    url: 'https://upload.wikimedia.org/wikipedia/commons/a/ae/B2b-elbcp-180x130.png'
  }
]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Документы"
      description="Уже загруженные файлы приходят через v-model"
      action="https://user1694090019726.requestly.dev/upload"
      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
    />
  </div>
</template>
```

### Number of files

The `max-count` prop limits the length of the list: with `max-count="1"` a new
file replaces the previous one, with a larger limit the extra files are dropped.

**Example — `MaxCount.vue`:**

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

const avatar = ref<NUploader.IUploadFile[]>([]);
const documents = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader
      v-model="avatar"
      label="Фото профиля"
      description="Новый файл заменяет предыдущий"
      action="https://user1694090019726.requestly.dev/upload"
      accept="image/png, image/jpeg"
      :max-count="1"
    />

    <CdsUploader
      v-model="documents"
      label="Документы"
      description="Не больше трёх файлов — лишние отбрасываются"
      action="https://user1694090019726.requestly.dev/upload"
      :max-count="3"
    />
  </div>
</template>
```

### Uploading directories

The `directory` prop turns on picking a whole folder — the files are collected
from it recursively, on a drop as well.

**Example — `Directories.vue`:**

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

const files = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка директории"
      description="Выберите папку — файлы соберутся из неё рекурсивно"
      action="https://user1694090019726.requestly.dev/upload"
      directory
    >
      <template #default="{ props }">
        <CdsButton v-bind="props" text="Загрузить директорию" />
      </template>
    </CdsUploader>
  </div>
</template>
```

### States

`disabled` blocks the button and removes the removal icons from the list,
`readonly` forbids changing the list but keeps the downloading.

**Example — `States.vue`:**

```vue
<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';

const files: NUploader.IUploadFile[] = [
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
];
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader label="Disabled" description="Загрузка недоступна" disabled />

    <CdsUploader
      label="Readonly"
      description="Список нельзя изменить, скачивание работает"
      :model-value="files"
      :show-upload-list="{ showDownloadIcon: true }"
      readonly
    />
  </div>
</template>
```

### Slots

When props are not enough, the content of any block is replaced by a slot.

| Slot name     | Description                                                                  |
| :------------ | :--------------------------------------------------------------------------- |
| `label`       | Label content (replaces `label`)                                             |
| `description` | Description content (replaces `description`)                                 |
| `prepend`     | Element before the upload button                                             |
| `default`     | Your own upload button; receives the ready `props` for CdsButton             |
| `append`      | Element after the upload button                                              |
| `messages`    | Content of the messages block                                                |
| `itemRender`  | Your own rendering of a list item; receives `file`, `fileList` and `actions` |

**Example — `Slots.vue`:**

```vue
<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import {
  CdsButton,
  CdsFunctionalButton,
  CdsIcon,
  CdsListItem,
  CdsTooltip,
  CdsUploader
} from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
]);

const clearAll = () => {
  files.value = [];
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader v-model="files" action="https://user1694090019726.requestly.dev/upload">
      <template #label>
        <span class="flex items-center gap-0.5">
          Загрузка файла
          <CdsTooltip text="Дополнительная информация">
            <template #activator="{ props }">
              <CdsIcon name="info" v-bind="props" />
            </template>
          </CdsTooltip>
        </span>
      </template>

      <template #description> Подойдёт любой формат — <strong>jpg, png, doc, zip</strong> — до 10 МБ. </template>

      <template #default="{ props }">
        <CdsButton v-bind="props" text="Выбрать файл" />
      </template>

      <template #append>
        <CdsFunctionalButton icon="delete" aria-label="Удалить все файлы" @click="clearAll">
          <CdsTooltip activator="parent">Удалить все файлы</CdsTooltip>
        </CdsFunctionalButton>
      </template>

      <template #messages>Файлы проверяются после загрузки</template>

      <template #itemRender="{ file, actions }">
        <CdsListItem :title="file?.name">
          <template #append>
            <CdsFunctionalButton icon="download" aria-label="Скачать файл" @click="actions.download" />
            <CdsFunctionalButton icon="delete" aria-label="Удалить файл" @click="actions.remove" />
          </template>
        </CdsListItem>
      </template>
    </CdsUploader>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| The description names the allowed formats and size upfront — the user does not waste an attempt. | Without a description the restrictions are learned only from an error after the upload. |
| The text of the button names exactly what to upload. | “Click here” says nothing about the action nor about the content. |
| The list shows what has already been uploaded and lets the extra files be removed. | With the list hidden the user does not see the result and uploads the files again. |

## Scenarios

### Deferred sending

The `before-upload` hook returning `false` turns the automatic sending off: the
files pile up in the list, and the upload is started by a separate button in the
`append` slot — together with the submission of the whole form, for example.

**Example — `UploadManual.vue`:**

```vue
<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsButton, CdsToast, CdsUploader } from '@central-design-system/components';
import { ref, unref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);
const loading = ref(false);
const uploaded = ref(false);

const beforeUpload = (file: NUploader.IUploadFile): boolean => {
  files.value = [...(unref(files) || []), file];
  return false;
};

const handleUpload = async () => {
  loading.value = true;
  await new Promise((resolve) => setTimeout(resolve, 3000));
  files.value = [];
  loading.value = false;
  uploaded.value = true;
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Выберите файлы"
      description="Файлы копятся в списке, загрузку запускает кнопка"
      :before-upload="beforeUpload"
      :show-upload-list="{ showRemoveIcon: true }"
    >
      <template #default="{ props }">
        <CdsButton
          variant="soft"
          color="brand"
          text="Выбрать файлы"
          :disabled="props.disabled"
          :readonly="props.readonly"
        />
      </template>
      <template #append>
        <CdsButton prepend-icon="upload" :loading="loading" :disabled="!files.length" @click="handleUpload">
          Загрузить файлы
        </CdsButton>
      </template>
    </CdsUploader>
    <CdsToast v-model="uploaded" title="Файлы успешно загружены" status="success" />
  </div>
</template>
```

### A check before the upload

The same `before-upload` is the place for validation: return `false` and the file
will not go to the server. A rejected file still gets into the list — remove it
in the `change` handler and show the reason through `error-messages`.

**Example — `BeforeUpload.vue`:**

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

const MAX_SIZE_MB = 5;

const files = ref<NUploader.IUploadFile[]>([]);
const errors = ref<string[]>([]);

const beforeUpload = (file: NUploader.IUploadFile): boolean => {
  const valid = (file.size ?? 0) <= MAX_SIZE_MB * 1024 * 1024;

  if (!valid) {
    errors.value = [`«${file.name}» больше ${MAX_SIZE_MB} МБ`];
  }

  return valid;
};

const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
  if (info instanceof Event) return;

  files.value = info.fileList.filter((file) => file.status);
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Вложения"
      :description="`Любые файлы до ${MAX_SIZE_MB} МБ`"
      action="https://user1694090019726.requestly.dev/upload"
      :error-messages="errors"
      :before-upload="beforeUpload"
      @change="handleChange"
    />
  </div>
</template>
```

### Upload errors

A file rejected by the server stays in the list with the error status. The
`show-tooltip-with-error` prop shows the server response in a tooltip next to the
status, and the `error` event lets you collect the messages under the field —
here they pile up in `error-messages` and are reset when the file is removed.

**Example — `UploadErrors.vue`:**

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

const files = ref<NUploader.IUploadFile[]>([]);
const errors = ref<string[]>([]);

const handleError = (
  _error: NUploader.IUploadRequestError | ProgressEvent,
  response: { message?: string } | null,
  file: NUploader.IUploadFile
) => {
  errors.value = [...errors.value, `${response?.message ?? 'Ошибка сервера'}: ${file.name}`];
};

const handleRemove = () => {
  errors.value = [];
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка с ошибкой"
      description="Тестовый сервер отклоняет любой файл"
      action="https://user1694090019726.requestly.dev/upload-error"
      :error-messages="errors"
      show-tooltip-with-error
      @error="handleError"
      @remove="handleRemove"
    />
  </div>
</template>
```

### Uploading without a server

The `custom-request` prop replaces the built-in XHR transport with your own
function: it receives the file and the `onProgress`, `onSuccess`, `onError`
callbacks and returns an object with an `abort` method. Here the upload is
simulated with a timer — files can be sent through an SDK or a WebSocket in the
same way.

**Example — `CustomRequest.vue`:**

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

const files = ref<NUploader.IUploadFile[]>([]);

// Имитация загрузки: прогресс по таймеру вместо XHR-запроса
const customRequest = ({ onProgress, onSuccess }: NUploader.IUploadRequestOption) => {
  let percent = 0;

  const timer = setInterval(() => {
    percent += 20;
    onProgress?.({ percent });

    if (percent >= 100) {
      clearInterval(timer);
      onSuccess?.({});
    }
  }, 400);

  return { abort: () => clearInterval(timer) };
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка без сервера"
      description="Файл никуда не отправляется — прогресс имитируется"
      :custom-request="customRequest"
      :show-upload-list="{ showRemoveIcon: true }"
    />
  </div>
</template>
```

### Events

The component reports every step: `change` — any change of the list, `progress`,
`success` and `error` — the course of the upload, `remove`, `drop`, `reject`,
`download`, `preview` — the actions of the user. Open the console to see them.

**Example — `Events.vue`:**

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

const files = ref<NUploader.IUploadFile[]>([]);

const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
  console.log('onChange', info);
};
const handleProgress = (event: NUploader.IUploadChangeParam['event'], file: NUploader.IUploadFile) => {
  console.log('onProgress', event, file);
};
const handleSuccess = (response: Record<string, any>, file: NUploader.IUploadFile) => {
  console.log('onSuccess', response, file);
};
const handleError = (
  event: NUploader.IUploadRequestError | ProgressEvent,
  response: any,
  file: NUploader.IUploadFile
) => {
  console.log('onError', event, response, file);
};
const handleRemove = (file: NUploader.IUploadFile) => {
  console.log('onRemove', file);
};
const handleDrop = (event: DragEvent) => {
  console.log('onDrop', event);
};
const handleReject = (rejected: NUploader.IUploadFile[]) => {
  console.log('onReject', rejected);
};
const handleDownload = (file: NUploader.IUploadFile) => {
  console.log('onDownload', file);
};
const handlePreview = (file: NUploader.IUploadFile) => {
  console.log('onPreview', file);
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка файлов"
      description="Откройте консоль, чтобы увидеть все циклы событий"
      action="https://user1694090019726.requestly.dev/upload"
      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
      @change="handleChange"
      @progress="handleProgress"
      @success="handleSuccess"
      @error="handleError"
      @remove="handleRemove"
      @drop="handleDrop"
      @reject="handleReject"
      @download="handleDownload"
      @preview="handlePreview"
    />
  </div>
</template>
```

## API

### CdsUploader

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `accept` | `string \| string[] \| undefined` | `''` | no | Allowed file types |
| `action` | `NUploader.TAction \| undefined` | `''` | no | URL the files are uploaded to |
| `activeColor` | `string \| undefined` | — | no | Color of the component in its active state |
| `appendIcon` | `IconValue \| undefined` | — | no | Icon in the append slot, after the content |
| `baseColor` | `string \| undefined` | — | no | Color of the component in its inactive state |
| `beforeUpload` | `((file: NUploader.IUploadFile<any>, fileList: NUploader.IUploadFile<any>[]) => NUploader.TBeforeUploadFileType \| Promise<void \| NUploader.TBeforeUploadFileType>) \| undefined` | — | no | Lifecycle hook called before a file is uploaded |
| `bgColor` | `string \| undefined` | — | no | Background color of the component |
| `buttonProps` | `Partial<CdsButtonProps> \| undefined` | `null` | no | Props for the CdsButton component |
| `capture` | `boolean \| "user" \| "environment" \| undefined` | — | no | Type of the media the file is captured from on mobile devices |
| `centerAffix` | `boolean \| undefined` | `true` | no | Vertically center the appendInner, prependInner, clearIcon and label elements. |
| `color` | `string \| undefined` | — | no | Component color |
| `customRequest` | `((options: NUploader.IUploadRequestOption<any>) => void) \| undefined` | — | no | Your own file upload request. Overrides the default xhr |
| `data` | `Record<string, unknown> \| ((file: string \| Blob \| NUploader.IRcFile) => Record<string, unknown>) \| {} \| undefined` | `{}` | no | Parameters of the file upload or a function returning them |
| `defaultFileList` | `NUploader.IUploadFile<any>[] \| undefined` | — | no | Default list of files |
| `description` | `string \| undefined` | — | no | Description of the component, shown under the label |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `'horizontal'` | no | Switches the component between horizontal and vertical layout. |
| `directory` | `boolean \| undefined` | — | no | Upload directories |
| `disabled` | `boolean \| null \| undefined` | `null` | no | Disabled state |
| `downloadIcon` | `IconValue \| undefined` | `'download'` | no | File download icon |
| `error` | `boolean \| undefined` | — | no | Puts the component into the error state |
| `errorMessages` | `string \| readonly string[] \| null \| undefined` | `[]` | no | 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. |
| `focused` | `boolean \| undefined` | — | no | Controls the focus state of the component. When `true`, the component is considered focused and may apply the corresponding styles or behavior. |
| `headers` | `NUploader.TUploadRequestHeaders \| undefined` | — | no | Request headers |
| `hideDetails` | `boolean \| "auto" \| undefined` | — | no | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
| `hideMessages` | `boolean \| undefined` | — | no | Hide the messages under the input |
| `hint` | `string \| undefined` | — | no | Hint text shown under the input |
| `iconColor` | `string \| boolean \| undefined` | — | no | Icon color. Accepts a boolean or a color string |
| `id` | `string \| undefined` | — | no | Unique identifier of the component |
| `isImageUrl` | `((file: NUploader.IUploadFile<any>) => boolean) \| undefined` | — | no | Configuration of the thumbnails of the uploaded files (not supported yet) |
| `itemRender` | `NUploader.TItemRender<any> \| undefined` | — | no | Render function for an item of the uploaded file list |
| `label` | `string \| undefined` | — | no | Label text of the component |
| `listType` | `NUploader.TUploadListType \| undefined` | `'text'` | no | Type of the uploaded file list ('text' only is supported) |
| `maxCount` | `number \| undefined` | — | no | Maximum number of uploaded files |
| `maxErrors` | `string \| number \| undefined` | `1` | no | Maximum number of validation errors shown |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `messages` | `string \| readonly string[] \| undefined` | `[]` | no | Messages shown under the input |
| `method` | `NUploader.TUploadRequestMethod \| undefined` | — | no | HTTP method of the upload request |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `modelValue` | `any` | — | no | Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default. |
| `multiple` | `boolean \| undefined` | `true` | no | Uploading several files at once |
| `name` | `string \| undefined` | — | no | Name of the input |
| `openFileDialogOnClick` | `boolean \| undefined` | — | no | Whether to open the system dialog on a click on the uploader |
| `persistentHint` | `boolean \| undefined` | — | no | Always show the hint, not only on focus |
| `prependIcon` | `IconValue \| undefined` | — | no | Icon in the prepend slot, before the content |
| `readonly` | `boolean \| null \| undefined` | `null` | no | Read-only state |
| `removeIcon` | `IconValue \| undefined` | `'delete'` | no | File removal icon |
| `rules` | `readonly ValidationRule[] \| undefined` | `[]` | no | 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. |
| `showTooltipWithError` | `boolean \| undefined` | `false` | no | Whether to show a tooltip with the error next to every file |
| `showUploadList` | `boolean \| NUploader.TShowUploadList \| undefined` | `true` | no | Show the list of the uploaded files |
| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Size of the component |
| `tag` | `string \| JSXComponent<any> \| undefined` | `'span'` | no | Custom HTML tag or component to render |
| `textColor` | `string \| undefined` | — | no | Text color of the component |
| `theme` | `string \| undefined` | — | no | Component theme |
| `uploadIcon` | `IconValue \| undefined` | `'upload'` | no | File upload icon |
| `validateOn` | `ValidateOn \| undefined` | — | no | Changes the type of the event that triggers validation |
| `validationValue` | `any` | — | no | Value used when applying the validation rules |
| `width` | `string \| number \| undefined` | — | no | Component width |
| `withCredentials` | `boolean \| undefined` | — | no | Send the request with cookies |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `change` | `[info: NUploader.IUploadChangeParam<NUploader.IUploadFile<any>>]` | Fires when the field changes |
| `download` | `[file: NUploader.IUploadFile<any>]` | Fires when a file is downloaded |
| `drop` | `[event: DragEvent]` | Fires when a file is dropped |
| `error` | `[error: ProgressEvent<EventTarget> \| NUploader.IUploadRequestError, response: any, file: NUploader.IUploadFile<any>]` | Fires when a file upload fails |
| `preview` | `[file: NUploader.IUploadFile<any>]` | Fires when a file preview is opened |
| `progress` | `[event: { percent: number; } \| undefined, file: NUploader.IUploadFile<any>]` | Fires while a file is being uploaded |
| `reject` | `[fileList: NUploader.IUploadFile<any>[]]` | Fires when a file upload is rejected |
| `remove` | `[file: NUploader.IUploadFile<any>]` | Fires when a file is removed |
| `success` | `[response: Record<string, unknown>, file: NUploader.IUploadFile<any>]` | Fires when a file has been uploaded successfully |
| `update:modelValue` | `[fileList: NUploader.IUploadFile<any>[]]` | Fires when the value changes (v-model) |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `append` | `any` | Content of the append slot after the upload button. |
| `default` | `{ props: Partial<CdsButtonProps>; }` | The upload button or activator. Receives the props for CdsButton. |
| `description` | `any` | Description under the label. |
| `itemRender` | `{ originNode: VNode<RendererNode, RendererElement, { [key: string]: any; }>; file?: NUploader.IUploadFile<any> \| undefined; fileList?: NUploader.IUploadFile<any>[] \| undefined; actions: { download?: (() => void) \| undefined; preview?: (() => void) \| undefined; remove?: (() => void) \| undefined; }; }` | Custom rendering of an item of the uploaded file list. |
| `label` | `any` | Label of the upload field. |
| `messages` | `any` | Hint and error messages. |
| `prepend` | `any` | Content of the prepend slot before the upload button. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `fileList` | `NUploader.IUploadFile<any>[]` | Current list of files together with their upload statuses. |
| `uploadRef` | `NUploader.IUploaderRef \| undefined` | Ref to the inner upload element — gives access to choosing files programmatically and to aborting. |

---

# CdsVirtualScroll

_Category: Content · since 4.0.0 · status: new_

_Tests: API 16/16 · 23 unit · 3 e2e · 1 known bug · lines 93.5% (v4.0.0-alpha.13) · a11y: 6 axe recommendations (v4.0.0-alpha.11)_

Virtual scrolling keeps long lists fast: only the visible rows get into the DOM, not the whole array. Pass the records to `items`, the markup of a row to the slot, and a list of tens of thousands of positions scrolls as smoothly as a list of ten.

**See also:** The dropdowns of CdsSelect and CdsAutocomplete, as well as the CdsTree tree, already virtualize their items — there is no need to wrap them. Render a short list — up to a couple of hundred rows — with the regular CdsList: virtualization will not pay off there.

## Variations

### Fixed height

The `height` prop sets the height of the viewport — the scrolling happens inside
it. If all the rows have the same height, set `item-height`: the component will
not measure every row, and the positions and the scrollbar will be exact from
the very first render.

**Example — `FixedHeight.vue`:**

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

const items = Array.from({ length: 10000 }, (_, index) => ({
  title: `Позиция каталога №${index + 1}`
}));
</script>

<template>
  <CdsCard class="m-auto w-[320px]">
    <CdsList>
      <CdsVirtualScroll height="300" item-height="36" :items="items">
        <template #default="{ item, index }">
          <CdsListItem
            :base-color="index % 2 ? 'surface-primary' : 'surface-secondary'"
            :height="36"
            :title="item.title"
          />
        </template>
      </CdsVirtualScroll>
    </CdsList>
  </CdsCard>
</template>
```

### Dynamic height

Without `item-height` the component measures the rows automatically — this fits
content of variable length: comments, messages, descriptions. The heights get
refined as you scroll, so the scrollbar may shift slightly.

**Example — `DynamicHeight.vue`:**

```vue
<script setup lang="ts">
import { CdsCard, CdsVirtualScroll } from '@central-design-system/components';

const texts = [
  'Согласовано.',
  'Уточните, пожалуйста, сроки поставки: в прошлой заявке отгрузка задержалась на неделю.',
  'Прошу приложить спецификацию к позиции.',
  'Цена выше средней по рынку — запросите у поставщика пересчёт и добавьте обоснование к заявке, иначе финансовый отдел вернёт её на доработку.'
];

const items = Array.from({ length: 5000 }, (_, index) => ({
  id: index + 1,
  author: `Участник ${(index % 27) + 1}`,
  text: texts[index % texts.length]
}));
</script>

<template>
  <CdsCard class="m-auto w-[360px]">
    <CdsVirtualScroll height="300" item-key="id" :items="items">
      <template #default="{ item }">
        <div class="border-b border-line-primary p-2">
          <div class="text-100 text-content-secondary">{{ item.author }}</div>
          <div class="text-200">{{ item.text }}</div>
        </div>
      </template>
    </CdsVirtualScroll>
  </CdsCard>
</template>
```

### Renderless mode

The `renderless` prop removes the own scroll container: the component listens to
the scrolling of the nearest scrollable parent and renders the rows without
wrappers. The slot additionally receives `itemRef` — bind it to the root node of
the row so that the component knows its height. This is how the list fits into
an existing scroll — of a panel or of the whole page. Give the scrollable parent
`position: relative` — the component counts the row positions from it.

**Example — `Renderless.vue`:**

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

const items = Array.from({ length: 3000 }, (_, index) => `Строка отчёта №${index + 1}`);
</script>

<template>
  <div class="relative m-auto h-[300px] w-[360px] overflow-y-auto rounded-200 border border-line-primary p-2">
    <div class="text-300">Отчёт за квартал</div>
    <p class="text-100 text-content-secondary">
      Шапка — часть общего потока: скролл-контейнер здесь один, родительский, и заголовок прокручивается вместе со
      строками списка.
    </p>

    <CdsVirtualScroll renderless :items="items">
      <template #default="{ item, itemRef }">
        <div :ref="itemRef" class="py-1">{{ item }}</div>
      </template>
    </CdsVirtualScroll>
  </div>
</template>
```

## Guidelines

| ✅ Do | ❌ Don't |
| --- | --- |
| A short list renders in full — with the regular CdsList, without a nested scroll. | Virtualizing a few rows speeds up nothing, while an extra scroll container hides part of the list. |
| A search next to a long list leads to the right row in seconds. | Scrolling by hand is the only way to find a record among thousands of rows. |

## Scenarios

### Catalog search

Pass an already filtered array to `items`: a `computed` recalculates the records
on input, and the component picks the new list up on its own. `item-key="id"`
binds the rows to the records rather than to the positions in the array — so the
rows do not get mixed up while filtering.

**Example — `CatalogSearch.vue`:**

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

const query = ref('');

const categories = ['Крепёж', 'Инструмент', 'Электрика', 'Сантехника', 'Спецодежда'];

const items = Array.from({ length: 10000 }, (_, index) => ({
  id: index + 1,
  title: `${categories[index % categories.length]}, артикул ${10000 + index}`
}));

const filtered = computed(() => {
  const search = query.value.trim().toLowerCase();

  return search ? items.filter((item) => item.title.toLowerCase().includes(search)) : items;
});
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsTextInput v-model="query" clearable hide-details placeholder="Поиск по каталогу" prepend-inner-icon="search" />

    <CdsCard>
      <CdsList v-if="filtered.length">
        <CdsVirtualScroll height="260" item-height="36" item-key="id" :items="filtered">
          <template #default="{ item }">
            <CdsListItem :height="36" :title="item.title" />
          </template>
        </CdsVirtualScroll>
      </CdsList>
      <div v-else class="p-2 text-content-secondary">Ничего не найдено</div>
    </CdsCard>

    <div class="text-100 text-content-secondary">Найдено: {{ filtered.length.toLocaleString('ru-RU') }}</div>
  </div>
</template>
```

### Jumping through a journal

The component exposes the `scrollToIndex` method — get it through a ref and
scroll the list programmatically. The month buttons calculate the index of the
first operation of the month; with a fixed `item-height` the jump lands exactly
on the right row.

**Example — `MonthNavigation.vue`:**

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

const MONTHS = [
  'Январь',
  'Февраль',
  'Март',
  'Апрель',
  'Май',
  'Июнь',
  'Июль',
  'Август',
  'Сентябрь',
  'Октябрь',
  'Ноябрь',
  'Декабрь'
];
const PER_MONTH = 400;

const items = Array.from({ length: MONTHS.length * PER_MONTH }, (_, index) => ({
  id: index + 1,
  title: `${MONTHS[Math.floor(index / PER_MONTH)]} — операция №${index + 1}`
}));

const virtualScroll = ref<InstanceType<typeof CdsVirtualScroll>>();

function scrollToMonth(month: number) {
  virtualScroll.value?.scrollToIndex(month * PER_MONTH);
}
</script>

<template>
  <div class="m-auto flex w-[400px] flex-col gap-2">
    <div class="flex flex-wrap justify-center gap-1">
      <CdsButton
        v-for="(month, index) in MONTHS"
        :key="month"
        variant="soft"
        color="neutral"
        size="xs"
        @click="scrollToMonth(index)"
      >
        {{ month.slice(0, 3) }}
      </CdsButton>
    </div>

    <CdsCard>
      <CdsList>
        <CdsVirtualScroll ref="virtualScroll" height="260" item-height="36" item-key="id" :items="items">
          <template #default="{ item }">
            <CdsListItem :height="36" :title="item.title" />
          </template>
        </CdsVirtualScroll>
      </CdsList>
    </CdsCard>
  </div>
</template>
```

### Selection in a long list

The rows outside the screen do not exist in the DOM, so keep the selection state
in the data, not in the rows themselves. In the demo the checked `id`s live in a
`Set`: the checkbox of a row reads it and changes it on click — the selection
survives any scrolling.

**Example — `RecipientsPicker.vue`:**

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

const departments = ['Закупки', 'Продажи', 'Логистика', 'Финансы'];

const employees = Array.from({ length: 8000 }, (_, index) => ({
  id: index + 1,
  name: `Сотрудник ${index + 1}`,
  department: departments[index % departments.length]
}));

const selected = ref(new Set<number>());

function toggle(id: number) {
  if (selected.value.has(id)) {
    selected.value.delete(id);
  } else {
    selected.value.add(id);
  }
}
</script>

<template>
  <div class="m-auto flex w-[360px] flex-col gap-2">
    <CdsCard>
      <CdsVirtualScroll height="260" item-height="40" item-key="id" :items="employees">
        <template #default="{ item }">
          <div class="flex h-[40px] items-center justify-between px-2">
            <CdsCheckbox
              hide-details
              :label="item.name"
              :model-value="selected.has(item.id)"
              @update:model-value="toggle(item.id)"
            />
            <span class="text-100 text-content-secondary">{{ item.department }}</span>
          </div>
        </template>
      </CdsVirtualScroll>
    </CdsCard>

    <div class="text-100 text-content-secondary">Выбрано получателей: {{ selected.size }}</div>
  </div>
</template>
```

## API

### CdsVirtualScroll

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `height` | `string \| number \| undefined` | — | no | Component height |
| `itemHeight` | `string \| number \| undefined` | `null` | no | Height of a single item in pixels. When omitted, the height is measured automatically. |
| `itemKey` | `SelectItemKey` | `null` | no | Key that identifies an item (a field name, a path or a function). The index is used by default. |
| `items` | `readonly unknown[] \| undefined` | `[]` | no | Array of the items rendered by the virtual scroll. |
| `maxHeight` | `string \| number \| undefined` | — | no | Maximum component height |
| `maxWidth` | `string \| number \| undefined` | — | no | Maximum component width |
| `minHeight` | `string \| number \| undefined` | — | no | Minimum component height |
| `minWidth` | `string \| number \| undefined` | — | no | Minimum component width |
| `renderless` | `boolean \| undefined` | — | no | Renderless mode: the component does not create its own scroll container and uses the nearest scrollable parent instead. |
| `width` | `string \| number \| undefined` | — | no | Component width |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `CdsVirtualScrollSlot<any> & { itemRef?: TemplateRef \| undefined; }` | Content of a single list item. In `renderless` mode it additionally receives `itemRef`. |

**Exposed**

| Name | Type | Description |
| --- | --- | --- |
| `calculateVisibleItems` | `() => void` | Recalculates the window of visible items — needed after their height changes outside the update cycle. |
| `scrollToIndex` | `(index: number) => void` | Scrolls the list to the item with the given index. |

### CdsVirtualScrollItem

**Props**

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `renderless` | `boolean \| undefined` | — | no | Renderless mode: the item renders only the slot content, without a wrapper. |

**Events**

| Name | Type | Description |
| --- | --- | --- |
| `update:height` | `[height: number]` | Tells the virtual list that the height of the item has changed. |

**Slots**

| Name | Type | Description |
| --- | --- | --- |
| `default` | `{ itemRef: TemplateRef; }` | Content of the item. In `renderless` mode it receives `itemRef` to measure the height. |