Иконки

Дизайн-система CDS v4 «из коробки» поддерживает множество популярных наборов иконок (iconpack).

Использование

По умолчанию CDS рисует иконки набором Phosphor. Настраивать ничего не нужно: CSS всех иконок, которые используют компоненты, уже входит в пакет. UnoCSS и @iconify-json/ph для этого не требуются.

import { createCds } from '@central-design-system/components';

const cds = createCds();

app.use(cds);

После этого иконку можно использовать в шаблонах:

<template>
  <CdsIcon icon="add" />
</template>

Имя иконки описывает её назначение: close закрывает контейнер, remove убирает элемент или значение, warning и error — разные статусы. Полный список — в галерее иконок.

Иконки в CSS хранятся как data: URI. Если у проекта настроен Content Security Policy, директива img-src должна разрешать data:. При печати иконки всегда чёрные: цвет задаётся маской, а она печатается неверно.

Имена CDS 3 продолжают работать весь 4.x: иконка подставляется по новому имени, а в dev-консоли появляется предупреждение [CDS UPGRADE]. В 5.0 старые имена будут удалены. Таблица замен — в гайде по миграции.

Своя иконка вместо алиаса

Чтобы заменить отдельные иконки, передайте только их. Остальные имена продолжат рисоваться выбранным набором:

const cds = createCds({
  icons: {
    aliases: {
      remove: 'class:my-remove-icon',
    }
  },
});

Установка наборов иконок через UnoCSS

Дизайн-система CDS интегрируется с UnoCSS Preset Icons, который поддерживает все наборы иконок, доступные на Iconify.

Иконки подключаются с tree-shaking, поэтому в итоговый CSS-бандл попадают только те иконки, которые вы действительно используете. Вы можете зарегистрировать сразу несколько наборов и свободно комбинировать иконки из любого из них в своих компонентах.

Наборы иконок

Для перечисленных ниже наборов в CDS подготовлены iconset'ы с alias mappings — псевдонимами для иконок, которые используют компоненты CDS (например, чекбоксы, выпадающие списки, радио-кнопки и т. д.). В качестве набора по умолчанию (defaultSet) нужно выбрать один из них; при необходимости alias mappings можно переопределить. Дополнительные наборы — уже без алиасов — можно подключить параллельно и свободно использовать в своих шаблонах.

Библиотека иконок	Iconify package	Импорт iconset'а	Set name
Phosphor Icons	не нужен для алиасов	@central-design-system/components/iconsets/phosphor	phosphor
Remix Icon	@iconify-json/ri	@central-design-system/components/iconsets/remix	remix
Lucide	@iconify-json/lucide	@central-design-system/components/iconsets/lucide	lucide
Tabler Icons	@iconify-json/tabler	@central-design-system/components/iconsets/tabler	tabler
Material Symbols	@iconify-json/material-symbols	@central-design-system/components/iconsets/materialSymbols	materialSymbols

Каждый модуль экспортирует объект с именем набора: icons (сам набор для sets) и aliases (псевдонимы для aliases).

Установите нужный набор из таблицы выше:

npm

npm install @iconify-json/ri

pnpm

pnpm add @iconify-json/ri

yarn

yarn add @iconify-json/ri

bun

bun add @iconify-json/ri

Иконки из таблицы работают через UnoCSS, поэтому сначала нужно установить и настроить сам UnoCSS. Подробнее об этом — в официальной документации.

Ниже — пример интеграции в проект на Vite.

1. Установите UnoCSS в dev-зависимости (см. интеграцию с Vite):

npm

npm install -D unocss

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

bun

bun add -d unocss

2. Подключите плагин UnoCSS в конфигурации Vite:

// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})

3. Создайте в корне проекта файл unocss.config.ts:

// unocss.config.ts
import { presetIcons, defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      processor(props) {
        delete props.color
      },
    }),
  ],
})

Больше ничего в unocss.config.ts дописывать не нужно: iconset'ы CDS помечены маркером @unocss-include, поэтому UnoCSS сканирует их сам — несмотря на то, что они лежат в node_modules и это .js-файлы, которые по умолчанию не попадают в content.pipeline.include.

4. Передайте набор иконок в функцию createCds(). В примере используется набор Remix, но его можно заменить любым другим из таблицы выше:

import { createCds } from '@central-design-system/components';
import { remix } from '@central-design-system/components/iconsets/remix';

const cds = createCds({
  icons: {
    defaultSet: 'remix',
    aliases: remix.aliases,
    sets: {
      remix: remix.icons,
    }
  },
});

app.use(cds);

Импортируйте набор подпутём @central-design-system/components/iconsets/<набор>, а не из общего объекта iconsets. Общий объект ссылается сразу на все наборы и не тришейкается — в бандл попадут лишний JS и CSS всех наборов.

После этого можно выбрать любую иконку из набора — например, ri:settings-3-line — и использовать её в шаблонах:

<CdsButton icon="i-ri:settings-3-line" />

UnoCSS использует для иконок префикс i-. CDS использует тот же префикс и уже настраивает с ним свои алиасы — не меняйте его, иначе алиасы из CDS перестанут работать.

Свой пак в компонентах

Любой пак Iconify можно подключить без карты CDS: установите @iconify-json/<пак> и пишите класс в шаблоне, например icon="i-mdi:home".

Чтобы своим паком рисовали и компоненты, передайте в createCds свою карту aliases. Имена, которых в ней нет, нарисует пак по умолчанию. UnoCSS сам не найдёт классы из этой карты: паки CDS помечены @unocss-include, а файл проекта нет. Добавьте файл карты в content.pipeline.include или перечислите классы в safelist, иначе иконки молча не нарисуются.

// unocss.config.ts
import { presetIcons, defineConfig } from 'unocss'

export default defineConfig({
  content: {
    pipeline: {
      include: [/\.vue$/, 'src/icons/aliases.ts'],
    },
  },
  presets: [presetIcons()],
})

Авторство паков

Пак	Автор	Лицензия
Phosphor	Phosphor Icons	MIT
Remix Icon	Remix Design	Apache-2.0
Lucide	Lucide Contributors	ISC
Tabler Icons	Paweł Kuna	MIT
Material Symbols	Google	Apache-2.0

Если вы подключаете пак под лицензией CC-BY (например, Solar), автора обязан указать ваш проект.

Набор cds

Набор CDS 3 на инлайновых SVG помечен как устаревший и работает весь 4.x. Он нужен, чтобы сохранить привычный вид при переходе с CDS 3:

const cds = createCds({
  icons: {
    defaultSet: 'cds'
  },
});

Новые имена, для которых в наборе нет рисунка, рисуются глифом Phosphor.

Legacy-пакет иконок из CDS v3

Пакет @central-design-system/icons устарел и будет удалён в 5.0. Если он подключён, иконки компонентов рисует набор cds, а компоненты Icon* из пакета остаются зарегистрированными глобально:

npm

npm install @central-design-system/icons

pnpm

pnpm add @central-design-system/icons

yarn

yarn add @central-design-system/icons

bun

bun add @central-design-system/icons

import * as icons from '@central-design-system/icons';

const cds = createCds({
  icons
});

app.use(cds);