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.

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Sandbox Storybook

<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

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

<template>
  <CdsEmptyState
    headline="404"
    title="Страница не найдена"
    text="Возможно, страница переехала или в адресе опечатка. Начните с главной страницы"
    action-text="На главную"
    href="/"
  />
</template>

API

Props

Name	Type	Default	Description
actionText	string | undefined	—	Text of the action button. When set, a button is rendered below the content.
bgColor	string | undefined	—	Background color of the component
color	string | undefined	—	Component color
content	string | number | undefined	—	Content displayed in the component.
description	string | undefined	—	Description
headline	string | undefined	—	Large accent heading above the main heading.
height	string | number | undefined	—	Component height
href	string | undefined	—	The href attribute of the link. When set, the component behaves as a regular link
icon	IconValue | undefined	—	Icon in the media area.
illustration	string | undefined	—	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	—	Source of the image in the media area (takes priority over icon).
justify	"start" | "end" | "center" | undefined	'center'	Horizontal alignment of the content: start, center, end.
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
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
text	string | number | undefined	—	Text displayed in the component.
textWidth	string | number | undefined	500	Maximum width of the description block.
theme	string | undefined	—	Component theme
title	string | undefined	—	Heading.
to	LinkTo | undefined	—	Target route or route location object for RouterLink. When set, the component behaves as a RouterLink
width	string | number | undefined	—	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).