Icons

CDS v4 supports many popular icon packs out of the box.

Usage

By default CDS draws icons with the Phosphor pack. There is nothing to set up: the CSS for every icon the components use ships with the package. You do not need UnoCSS or @iconify-json/ph for it.

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

const cds = createCds();

app.use(cds);

After that, use icons in your templates:

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

An icon name describes its purpose: close closes a container, remove removes an item or a value, warning and error are different statuses. See the full list in the icon gallery.

Icons are stored in CSS as data: URIs. If your project sets a Content Security Policy, its img-src directive must allow data:. Printed icons are always black: the color comes from a mask, which does not print correctly.

CDS 3 names keep working throughout 4.x: the icon resolves to its new name and a [CDS UPGRADE] warning appears in the dev console. Old names are removed in 5.0. The replacement table is in the migration guide.

Replacing a single icon

To replace specific icons, pass only those. The other names stay drawn by the selected pack:

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

Installing icon packs through UnoCSS

CDS integrates with UnoCSS Preset Icons, which supports every icon pack available on Iconify.

Icons are tree-shaken, so only the icons you actually use end up in the final CSS bundle. You can register several packs at once and freely mix icons from any of them in your components.

Icon packs

For the packs listed below, CDS ships iconsets with alias mappings — aliases for the icons CDS components use (checkboxes, dropdowns, radio buttons and so on). Pick one of them as the default pack (defaultSet); the alias mappings can be overridden if needed. Additional packs — without aliases — can be plugged in alongside and used freely in your own templates.

Icon library	Iconify package	Iconset import	Set name
Phosphor Icons	not needed for aliases	@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

Each module exports an object named after the pack: icons (the pack itself, for sets) and aliases (the aliases, for aliases).

Install the pack you need from the table above:

npm

npm install @iconify-json/ri

pnpm

pnpm add @iconify-json/ri

yarn

yarn add @iconify-json/ri

bun

bun add @iconify-json/ri

Icons from the table run through UnoCSS, so you have to install and configure UnoCSS first. See the official documentation for details.

Here is an example integration in a Vite project.

1. Install UnoCSS as a dev dependency (see the Vite integration):

npm

npm install -D unocss

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

bun

bun add -d unocss

2. Add the UnoCSS plugin to your Vite config:

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

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

3. Create an unocss.config.ts file in the project root:

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

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

Nothing else needs to go into unocss.config.ts: CDS iconsets carry the @unocss-include marker, so UnoCSS scans them on its own — even though they live in node_modules as .js files, which are not part of content.pipeline.include by default.

4. Pass the icon pack to createCds(). The example uses the Remix pack, but you can swap it for any other pack from the table above:

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);

Import the pack through the @central-design-system/components/iconsets/<pack> subpath, not from the shared iconsets object. The shared object references all packs at once and is not tree-shaken — you would ship the extra JS and CSS of all packs.

After that, pick any icon from the pack — for example ri:settings-3-line — and use it in templates:

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

UnoCSS uses the i- prefix for icons. CDS uses the same prefix and already configures its aliases with it — don't change it, or the CDS aliases will stop working.

Your own pack in components

Any Iconify pack works without a CDS map: install @iconify-json/<pack> and write the class in your template, for example icon="i-mdi:home".

To make components draw with your pack too, pass your own aliases map to createCds. Names missing from it are drawn by the default pack. UnoCSS will not find the classes from this map by itself: CDS packs carry @unocss-include, your project file does not. Add the map file to content.pipeline.include or list the classes in safelist, otherwise the icons silently do not render.

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

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

Pack credits

Pack	Author	License
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

If you add a pack under a CC-BY license (Solar, for example), your project must credit its author.

The cds pack

The CDS 3 pack of inline SVGs is deprecated and keeps working throughout 4.x. Use it to keep the familiar look while moving from CDS 3:

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

New names the pack has no drawing for use a Phosphor glyph.

Legacy icons package from CDS v3

The @central-design-system/icons package is deprecated and is removed in 5.0. When it is connected, the cds pack draws component icons, and the Icon* components from the package stay registered globally:

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);