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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Storybook

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.

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

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

Sandbox Storybook

<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

Props

Name	Type	Default	Description
activeColor	string | undefined	—	Color of the component in its active state
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
color	string | undefined	—	Component color
disabled	boolean | null | undefined	null	Disabled state
end	boolean | undefined	—	Adds spacing to the left of the icon — for an icon after the text
icon	IconValue | undefined	—	Name of the icon or the icon component to render
name	string | undefined	—	String name of an icon from a registered pack (an alias for icon)
opacity	string | number | undefined	—	Opacity of the icon — a number between 0 and 1
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
start	boolean | undefined	—	Adds spacing to the right of the icon — for an icon before the text
tag	string | JSXComponent<any> | undefined	'i'	Custom HTML tag or component to render
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme

Slots

Name	Type	Description
default	any	Name of the icon as text — an alternative to the icon prop