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.

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Props

Name	Type	Default	Description
boilerplate	boolean | undefined	false	Boilerplate mode: turns the shimmer animation off (for prototyping).
height	string | number | undefined	—	Component height
loading	boolean | undefined	false	Shows the skeleton instead of the slot content while loading.
loadingText	string | undefined	—	Text for the aria-label while loading.
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
theme	string | undefined	—	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'	Skeleton type: a predefined preset or an arbitrary structure string (or an array of strings).
width	string | number | undefined	—	Component width

Slots

Name	Type	Description
default	any	Content rendered instead of the skeleton once the loading is done.