Внутри других компонентов иконку отдельно не собирают: у CdsButton, CdsTextInput, CdsList и других есть пропсы icon, prepend-icon и append-icon. Для самостоятельного действия возьмите CdsFunctionalButton — это кнопка-иконка с подписью и состояниями. Все доступные иконки — в галерее, подключение своего набора — в руководстве.

Вариации

Иконка

Свойство icon принимает имя иконки из набора по умолчанию — например add или search. Свойство name делает то же самое и читается естественнее, когда иконка задаётся строкой. Кроме имени icon принимает компонент иконки и массив SVG-путей, поэтому в него можно передать и собственную графику.

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>

Иконка из другого подключённого набора указывается с префиксом набора — i-ri:settings-3-line. Как подключить набор, описано в руководстве по иконкам.

Размеры

Свойство size принимает одно из значений шкалы — от xs до xl — или число в пикселях, когда иконка работает как иллюстрация. По умолчанию — md, вровень с основным текстом.

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 иконка наследует цвет текста родителя — это поведение по умолчанию и в большинстве случаев верное. Свойство color принимает токен палитры (content-secondary, brand-primary), цветовой алиас статуса (green, red, lemon) или hex/rgb. Свойство opacity приглушает иконку, не меняя её цвет.

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>

Отступ от текста

Свойства start и end добавляют отступ со стороны текста: start — для иконки перед подписью, end — после. Так не приходится подбирать margin руками.

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>

Реакция на клик

Если повесить на иконку обработчик @click, она получает role="button", попадает в обход по Tab и меняет курсор; disabled убирает её из обхода и перестаёт принимать клики. Это удобно для мелких переключателей внутри своих компонентов — для полноценного действия лучше подойдёт CdsFunctionalButton.

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>

Слот

Имя иконки можно передать текстом в слот по умолчанию — результат тот же, что и у icon. Пригодится, когда имя приходит из выражения в шаблоне.

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>

Рекомендации

Storybook

Сценарии использования

Статусы в списке

Иконка слева от подписи задаёт статус цветом и формой, а текст называет его словами. Цвета берутся из алиасов статусов, size="sm" подгоняет иконку под мелкий текст, start даёт отступ до подписи.

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>

Список вложений

Иконка показывает тип файла и держит взгляд на левом крае списка. Размер lg делает её заметнее подписи, а цвет content-secondary не даёт ей спорить с названием файла. Действие рядом — уже кнопка: CdsFunctionalButton с 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>

Ход операции

Иконка отражает состояние процесса: заявка готова, отправляется, отправлена. Меняются только icon и color — компонент перерисовывается на месте, и строка статуса не прыгает.

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>

Примечание в тексте

В абзаце иконка выравнивается по середине строки, поэтому её можно ставить прямо в текст. Размер sm и start не дают ей разрывать строку.

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

Пропсы

Имя	Тип	По умолчанию	Описание
activeColor	string | undefined	—	Цвет компонента, когда он находится в активном состоянии
baseColor	string | undefined	—	Цвет неактивного компонента
bgColor	string | undefined	—	Цвет фона компонента
color	string | undefined	—	Цвет компонента
disabled	boolean | null | undefined	null	Заблокированное состояние
end	boolean | undefined	—	Добавляет отступ слева от иконки — для иконки после текста
icon	IconValue | undefined	—	Название иконки или компонент иконки, который будет отображаться
name	string | undefined	—	Строковое имя иконки из зарегистрированного набора (алиас для icon)
opacity	string | number | undefined	—	Прозрачность иконки — число от 0 до 1
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Размер компонента
start	boolean | undefined	—	Добавляет отступ справа от иконки — для иконки перед текстом
tag	string | JSXComponent<any> | undefined	'i'	Пользовательский HTML-тег для отображения
textColor	string | undefined	—	Цвет текста компонента
theme	string | undefined	—	Тема компонента

Слоты

Имя	Тип	Описание
default	any	Имя иконки текстом — альтернатива пропу icon