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.

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Sandbox Storybook

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

Sandbox Storybook

<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

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Name	Type	Default	Description
activatable	boolean | undefined	—	Allows items to be activated (highlighting the current item without selection mode)
activated	any	—	Identifiers of the active items (supports v-model through update:activated)
activeClass	string | undefined	—	Class applied to list items when they are in the active state
activeColor	string | undefined	—	Color of the component in its active state
activeStrategy	ActiveStrategyProp | undefined	—	Activation strategy for items (single, multiple, and so on)
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
collapseIcon	IconValue | undefined	—	Icon shown on a collapsed group
color	string | undefined	—	Component color
disabled	boolean | null | undefined	null	Disabled state
expandIcon	IconValue | undefined	—	Icon shown on an expanded group
filterable	boolean | undefined	—	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	—	Component height
indent	string | number | undefined	—	Indent size for nested item groups
itemChildren	SelectItemKey	'children'	Object field that holds the child items, or a function that returns them
itemProps	SelectItemKey	'props'	Object field that holds the props of the item, or a function that returns them
items	any[] | undefined	[]	Array of items to display
itemsRegistration	ItemsRegistrationType | undefined	'render'	Item registration strategy: render — as they are rendered, otherwise all at once
itemTitle	SelectItemKey	'title'	Object field used as the item title, or a function that returns it
itemType	SelectItemKey	'type'	Object field that defines the item type (item, divider, subheader), or a function that returns it
itemValue	SelectItemKey	'value'	Object field used as the item value, or a function that returns it
lines	false | "one" | "two" | "three" | undefined	'one'	Number of lines in the list items; affects their height. false turns off the fixed height
mandatory	boolean | undefined	—	Makes the selection mandatory: forbids clearing the selection of the last item
maxHeight	string | number | undefined	—	Maximum component height
maxWidth	string | number | undefined	—	Maximum component width
minHeight	string | number | undefined	—	Minimum component height
minWidth	string | number | undefined	—	Minimum component width
nav	boolean | undefined	—	Applies navigation list styles (rounded active items)
navigationIndex	number | undefined	—	Index of the current item during keyboard navigation (supports v-model)
navigationStrategy	"focus" | "track" | undefined	'focus'	Keyboard navigation strategy: focus — moves the focus, track — a virtual cursor
opened	any	—	Identifiers of the expanded groups (supports v-model through update:opened)
openStrategy	OpenStrategyProp | undefined	'list'	Expansion strategy for groups (list, single, multiple)
prependGap	string | number | undefined	—	Indent before the item content (reserves space for the prepend icon or avatar)
required	boolean | undefined	—	Makes the selection mandatory: forbids clearing the selection of the last item
returnObject	boolean | undefined	—	Return an object in the model value instead of an array
selectable	boolean | undefined	—	Allows items to be selected
selected	any	—	Identifiers of the selected items (supports v-model through update:selected)
selectStrategy	SelectStrategyProp | undefined	'single-leaf'	Selection strategy for items (single-leaf, leaf, independent, classic, and so on)
slim	boolean | undefined	—	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'	Custom HTML tag or component to render
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
valueComparator	ValueComparator | undefined	—	Function that compares item values to determine the selected state
width	string | number | undefined	—	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

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon shown after the group title
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
collapseIcon	IconValue | undefined	'chevron-up'	Icon shown when the group is collapsed
color	string | undefined	—	Component color
disabled	boolean | null | undefined	null	Disabled state
expandIcon	IconValue | undefined	'chevron-down'	Icon shown when the group is expanded
fluid	boolean | undefined	—	Removes the indent of the group activator, aligning it to the edge of the list
prependIcon	IconValue | undefined	—	Icon shown before the group title
rawId	string | number | undefined	—	Original identifier of the group; used to build the id of the DOM element
subgroup	boolean | undefined	—	Marks the component as a group of nested lists (a subgroup)
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
textColor	string | undefined	—	Text color of the component
title	string | undefined	—	Title of the group shown in the default activator
value	any	—	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

Name	Type	Default	Description
active	boolean | undefined	—	Forces the active state of the item
activeClass	string | undefined	—	Class applied to list items when they are in the active state
activeColor	string | undefined	—	Color of the component in its active state
appendAvatar	string | undefined	—	Avatar (image URL) shown after the item content
appendIcon	IconValue | undefined	—	Icon shown after the item content
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
color	string | undefined	—	Component color
description	string | number | boolean | undefined	—	Description of the list item shown below the title and the subtitle
disabled	boolean | null | undefined	null	Disabled state
exact	boolean | undefined	—	If true, the active state applies only on an exact route match
height	string | number | undefined	—	Component height
href	string | undefined	—	The href attribute of the link. When set, the component behaves as a regular link
index	number | undefined	—	Index of the item; used for keyboard navigation
lines	false | "one" | "two" | "three" | undefined	'one'	Number of lines in the list items; affects their height. false turns off the fixed height
link	boolean | undefined	—	Turns the item into a clickable link. Detected automatically when href or to is set
maxHeight	string | number | undefined	—	Maximum component height
maxWidth	string | number | undefined	—	Maximum component width
minHeight	string | number | undefined	—	Minimum component height
minWidth	string | number | undefined	—	Minimum component width
nav	boolean | undefined	—	Applies navigation list styles (rounded active items)
prependAvatar	string | undefined	—	Avatar (image URL) shown before the item content
prependGap	string | number | undefined	—	Indent before the item content (reserves space for the prepend icon or avatar)
prependIcon	IconValue | undefined	—	Icon shown before the item content
replace	boolean | undefined	—	If true, navigation replaces the current history entry instead of pushing a new one
slim	boolean | undefined	—	Removes the inner paddings of the list and of the menu container: the list fills the available area completely
subtitle	string | number | boolean | undefined	—	Subtitle of the item shown below the title
tabindex	string | number | undefined	—	Value of the element tabindex attribute
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
title	string | number | boolean | undefined	—	Title of the item shown in the component
to	LinkTo | undefined	—	Target route or route location object for RouterLink. When set, the component behaves as a RouterLink
value	any	—	Value of the item used for selection and activation in the list
width	string | number | undefined	—	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

Name	Type	Default	Description
end	boolean | undefined	—	Places the action at the end of the list item (after the content)
start	boolean | undefined	—	Places the action at the start of the list item (before the content)
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render

Slots

Name	Type	Description
default	any	Default content of the action

CdsListItemDescription

Props

Name	Type	Default	Description
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render

CdsListItemDivider

Props

Name	Type	Default	Description
color	string | undefined	—	Color of the divider.
contentOffset	string | number | (string | number)[] | undefined	—	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	—	Adds a fade-out effect on both ends.
inset	boolean | undefined	—	Adds an indent to horizontal dividers and reduces the maximum height of vertical ones.
length	string | number | undefined	—	Length of the divider. Defaults to pixels.
opacity	string | number | undefined	—	Opacity of the divider.
theme	string | undefined	—	Component theme
thickness	string | number | undefined	—	Thickness of the divider. Defaults to pixels.
variant	"solid" | "dotted" | "dashed" | "double" | undefined	'solid'	Visual variant of the divider
vertical	boolean | undefined	—	Renders the divider vertically

Slots

Name	Type	Description
default	any	Text or content placed in the gap of the divider

CdsListItemImage

Props

Name	Type	Default	Description
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render

CdsListItemMedia

Props

Name	Type	Default	Description
end	boolean | undefined	—	Places the media at the end of the list item (after the content)
start	boolean | undefined	—	Places the media at the start of the list item (before the content)
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render

Slots

Name	Type	Description
default	any	Default content of the media

CdsListItemSubtitle

Props

Name	Type	Default	Description
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render

CdsListItemTitle

Props

Name	Type	Default	Description
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render

CdsListSubheader

Props

Name	Type	Default	Description
color	string | undefined	—	Color of the subheader text
inset	boolean | undefined	—	Adds a left indent, aligning the text with the content of the list items
sticky	boolean | undefined	—	Pins the subheader to the top while the list scrolls
tag	string | JSXComponent<any> | undefined	'div'	Custom HTML tag or component to render
title	string | undefined	—	Text of the subheader

Slots

Name	Type	Description
default	any	Default content of the subheader (overrides the title prop)