1---
2name: preset-icons
3description: Pure CSS icons using Iconify with any icon set
4---
5 
6# Preset Icons
7 
8Use any icon as a pure CSS class, powered by Iconify.
9 
10## Installation
11 
12```bash
13pnpm add -D @unocss/preset-icons @iconify-json/[collection-name]
14```
15 
16Example: `@iconify-json/mdi` for Material Design Icons, `@iconify-json/carbon` for Carbon icons.
17 
18```ts
19import { defineConfig, presetIcons } from 'unocss'
20 
21export default defineConfig({
22  presets: [
23    presetIcons(),
24  ],
25})
26```
27 
28## Usage
29 
30Two naming conventions:
31- `<prefix><collection>-<icon>` → `i-ph-anchor-simple-thin`
32- `<prefix><collection>:<icon>` → `i-ph:anchor-simple-thin`
33 
34```html
35<!-- Phosphor anchor icon -->
36<div class="i-ph-anchor-simple-thin" />
37 
38<!-- Material Design alarm with color -->
39<div class="i-mdi-alarm text-orange-400" />
40 
41<!-- Large Vue logo -->
42<div class="i-logos-vue text-3xl" />
43 
44<!-- Dynamic: Sun in light mode, Moon in dark -->
45<button class="i-carbon-sun dark:i-carbon-moon" />
46 
47<!-- Hover effect -->
48<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />
49```
50 
51Browse icons at [icones.js.org](https://icones.js.org/) or [Iconify](https://icon-sets.iconify.design/).
52 
53## Icon Modes
54 
55Icons automatically choose between `mask` (monochrome) and `background-img` (colorful).
56 
57### Force Specific Mode
58 
59- `?mask` - Render as mask (colorable with `currentColor`)
60- `?bg` - Render as background image (preserves original colors)
61 
62```html
63<!-- Original with colors -->
64<div class="i-vscode-icons:file-type-light-pnpm" />
65 
66<!-- Force mask mode, apply custom color -->
67<div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
68```
69 
70## Options
71 
72```ts
73presetIcons({
74  scale: 1.2,              // Scale relative to font size
75  prefix: 'i-',            // Class prefix (default)
76  mode: 'auto',            // 'auto' | 'mask' | 'bg'
77  extraProperties: {
78    'display': 'inline-block',
79    'vertical-align': 'middle',
80  },
81  warn: true,              // Warn on missing icons
82  autoInstall: true,       // Auto-install missing icon sets
83  cdn: 'https://esm.sh/',  // CDN for browser usage
84})
85```
86 
87## Custom Icon Collections
88 
89### Inline SVGs
90 
91```ts
92presetIcons({
93  collections: {
94    custom: {
95      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
96    },
97  }
98})
99```
100 
101Usage: `<span class="i-custom:circle"></span>`
102 
103### File System Loader
104 
105```ts
106import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
107 
108presetIcons({
109  collections: {
110    'my-icons': FileSystemIconLoader(
111      './assets/icons',
112      svg => svg.replace(/#fff/, 'currentColor')
113    ),
114  }
115})
116```
117 
118### Dynamic Import (Browser)
119 
120```ts
121import presetIcons from '@unocss/preset-icons/browser'
122 
123presetIcons({
124  collections: {
125    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
126  }
127})
128```
129 
130## Icon Customization
131 
132```ts
133presetIcons({
134  customizations: {
135    // Transform SVG
136    transform(svg, collection, icon) {
137      return svg.replace(/#fff/, 'currentColor')
138    },
139    // Global sizing
140    customize(props) {
141      props.width = '2em'
142      props.height = '2em'
143      return props
144    },
145    // Per-collection
146    iconCustomizer(collection, icon, props) {
147      if (collection === 'mdi') {
148        props.width = '2em'
149      }
150    }
151  }
152})
153```
154 
155## CSS Directive
156 
157Use `icon()` in CSS (requires transformer-directives):
158 
159```css
160.icon {
161  background-image: icon('i-carbon-sun');
162}
163.icon-colored {
164  background-image: icon('i-carbon-moon', '#fff');
165}
166```
167 
168## Accessibility
169 
170```html
171<!-- With label -->
172<a href="/profile" aria-label="Profile" class="i-ph:user-duotone"></a>
173 
174<!-- Decorative -->
175<a href="/profile">
176  <span aria-hidden="true" class="i-ph:user-duotone"></span>
177  My Profile
178</a>
179```
180 
181<!-- 
182Source references:
183- https://unocss.dev/presets/icons
184-->
185