0
# unplugin-icons
1

2
unplugin-icons is a universal icon solution that provides access to thousands of icons as components on-demand across multiple build tools and frameworks. It supports over 150 popular icon sets with more than 200,000 icons powered by Iconify, with on-demand bundling, SSR/SSG compatibility, and comprehensive TypeScript support.
3

4
## Package Information
5

6
- **Package Name**: unplugin-icons
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install unplugin-icons` or `pnpm add unplugin-icons`
10

11
## Core Imports
12

13
```typescript
14
import Icons from "unplugin-icons/vite";
15
import { Options, CustomIconLoader, IconCustomizer, InlineCollection } from "unplugin-icons";
16
```
17

18
For specific build tools:
19

20
```typescript
21
// Vite
22
import Icons from "unplugin-icons/vite";
23

24
// Webpack
25
import Icons from "unplugin-icons/webpack";
26

27
// Rollup
28
import Icons from "unplugin-icons/rollup";
29

30
// esbuild
31
import Icons from "unplugin-icons/esbuild";
32

33
// Rspack
34
import Icons from "unplugin-icons/rspack";
35

36
// Nuxt
37
import Icons from "unplugin-icons/nuxt";
38
```
39

40
For loaders, resolver, and utilities:
41

42
```typescript
43
import { FileSystemIconLoader, ExternalPackageIconLoader } from "unplugin-icons/loaders";
44
import ComponentsResolver from "unplugin-icons/resolver";
45
import { collections, hasCollection } from "unplugin-icons/types";
46
```
47

48
## Basic Usage
49

50
```typescript
51
// vite.config.ts
52
import { defineConfig } from "vite";
53
import Icons from "unplugin-icons/vite";
54

55
export default defineConfig({
56
  plugins: [
57
    Icons({
58
      compiler: "vue3", // or 'react', 'svelte', etc.
59
      autoInstall: true,
60
    }),
61
  ],
62
});
63
```
64

65
Icon usage in components:
66

67
```typescript
68
// React/JSX
69
import IconAccessibility from "~icons/carbon/accessibility";
70

71
function App() {
72
  return <IconAccessibility />;
73
}
74

75
// Vue 3
76
<template>
77
  <IconAccessibility />
78
</template>
79

80
<script setup>
81
import IconAccessibility from "~icons/carbon/accessibility";
82
</script>
83

84
// Svelte
85
<script>
86
import IconAccessibility from "~icons/carbon/accessibility";
87
</script>
88

89
<IconAccessibility />
90
```
91

92
## Architecture
93

94
unplugin-icons is built around several key components:
95

96
- **Universal Plugin Core**: Uses unplugin architecture to provide consistent API across all build tools
97
- **Icon Resolution System**: Resolves virtual icon imports (`~icons/collection/icon`) to actual SVG content
98
- **Multi-Framework Compilers**: Generates framework-specific components (React, Vue, Svelte, etc.) from SVG content  
99
- **Custom Loaders**: Supports loading icons from filesystem, external packages, or custom sources
100
- **Component Resolver**: Integrates with unplugin-vue-components for automatic component registration
101
- **TypeScript Integration**: Provides comprehensive type definitions for all supported frameworks
102

103
## Capabilities
104

105
### Plugin Configuration
106

107
Core plugin setup and configuration options for different build tools and frameworks.
108

109
```typescript { .api }
110
interface Options {
111
  scale?: number;
112
  defaultStyle?: string;  
113
  defaultClass?: string;
114
  customCollections?: Record<string, CustomIconLoader | InlineCollection>;
115
  iconCustomizer?: IconCustomizer;
116
  collectionsNodeResolvePath?: string | string[];
117
  transform?: (svg: string, collection: string, icon: string) => Awaitable<string>;
118
  autoInstall?: boolean;
119
  compiler?: 'astro' | 'jsx' | 'marko' | 'none' | 'solid' | 'svelte' | 'raw' | 'vue2' | 'vue3' | 'web-components' | 'qwik' | CustomCompiler;
120
  jsx?: 'react' | 'preact' | 'qwik';
121
  webComponents?: WebComponentsConfig;
122
}
123

124
interface WebComponentsConfig {
125
  autoDefine?: boolean;
126
  iconPrefix?: string;
127
  shadow?: boolean;
128
}
129
```
130

131
[Plugin Configuration](./plugin-configuration.md)
132

133
### Icon Loaders
134

135
Custom icon loading functionality for filesystem icons, external packages, and custom icon sources.
136

137
```typescript { .api }
138
function FileSystemIconLoader(
139
  dir: string, 
140
  transform?: (svg: string) => Awaitable<string>
141
): CustomIconLoader;
142

143
function ExternalPackageIconLoader(
144
  packageName: ExternalPkgName, 
145
  autoInstall?: AutoInstall
146
): Record<string, CustomIconLoader>;
147

148
type CustomIconLoader = (name: string) => Awaitable<string | undefined>;
149
```
150

151
[Icon Loaders](./icon-loaders.md)
152

153
### Component Resolver
154

155
Automatic component resolution for unplugin-vue-components and unplugin-auto-import integration.
156

157
```typescript { .api }
158
function ComponentsResolver(options?: ComponentResolverOption): (name: string) => string | undefined;
159

160
interface ComponentResolverOption {
161
  prefix?: string | false;
162
  enabledCollections?: string | string[];
163
  alias?: Record<string, string>;
164
  customCollections?: string | string[];
165
  extension?: string;
166
  strict?: boolean;
167
}
168
```
169

170
[Component Resolver](./component-resolver.md)
171

172
### Build Tool Integrations
173

174
Framework-specific plugin instances for different build tools and environments.
175

176
```typescript { .api }
177
declare const VitePlugin: (options?: Options) => any;
178
declare const WebpackPlugin: (options?: Options) => any;
179
declare const RollupPlugin: (options?: Options) => any;
180
declare const EsbuildPlugin: (options?: Options) => any;
181
declare const RspackPlugin: (options?: Options) => any;
182
declare const NuxtModule: (options?: Options, nuxt?: any) => void;
183
```
184

185
[Build Tool Integrations](./build-tools.md)
186

187
### Collections Utilities
188

189
Functions for working with available icon collections and validating collection names.
190

191
```typescript { .api }
192
declare const collections: string[];
193

194
function hasCollection(collection: string): boolean;
195
```
196

197
## Types
198

199
```typescript { .api }
200
type IconCustomizer = (
201
  collection: string, 
202
  icon: string, 
203
  props: Record<string, string>
204
) => Awaitable<void>;
205

206
type InlineCollection = Record<string, string | (() => Awaitable<string | undefined>)>;
207

208
interface CustomCompiler {
209
  compiler: Awaitable<Compiler>;
210
  extension?: string;
211
}
212

213
type Compiler = (
214
  svg: string,
215
  collection: string,
216
  icon: string,
217
  options: ResolvedOptions
218
) => string | Promise<string>;
219

220
type ResolvedOptions = Omit<Required<Options>, 'iconSource' | 'transform'> & Pick<Options, 'transform'>;
221

222
// Utility types
223
type Awaitable<T> = T | Promise<T>;
224

225
// External types from @iconify/utils for ExternalPackageIconLoader
226
type ExternalPkgName = string;
227
type AutoInstall = boolean | { install?: boolean };
228
```