0
# Plugin Configuration
1

2
Core plugin setup and configuration options for unplugin-icons across different build tools and frameworks.
3

4
## Capabilities
5

6
### Main Configuration Interface
7

8
The primary options interface for configuring unplugin-icons behavior.
9

10
```typescript { .api }
11
/**
12
 * Main configuration options for unplugin-icons
13
 */
14
interface Options {
15
  /** Scale of icons against 1em (default: 1.2) */
16
  scale?: number;
17
  
18
  /** Style apply to icons by default (default: '') */
19
  defaultStyle?: string;
20
  
21
  /** Class names apply to icons by default (default: '') */
22
  defaultClass?: string;
23
  
24
  /** Loader for custom loaders */
25
  customCollections?: Record<string, CustomIconLoader | InlineCollection>;
26
  
27
  /** Icon customizer */
28
  iconCustomizer?: IconCustomizer;
29
  
30
  /** Current working directory for resolving collections from node_modules */
31
  collectionsNodeResolvePath?: string | string[];
32
  
33
  /** 
34
   * Transform raw SVG.
35
   * WARNING: transform will only be applied when using custom icon collection.
36
   */
37
  transform?: (svg: string, collection: string, icon: string) => Awaitable<string>;
38
  
39
  /** Auto install icon sources package when the usages is detected (default: false) */
40
  autoInstall?: boolean;
41
  
42
  /** Compiler (default: detect automatically, fallback to 'vue3') */
43
  compiler?: 'astro' | 'jsx' | 'marko' | 'none' | 'solid' | 'svelte' | 'raw' | 'vue2' | 'vue3' | 'web-components' | 'qwik' | CustomCompiler;
44
  
45
  /** JSX style, works only when compiler set to jsx (default: detect automatically, fallback to 'react') */
46
  jsx?: 'react' | 'preact' | 'qwik';
47
  
48
  /** Config for Web Components compiler */
49
  webComponents?: WebComponentsConfig;
50
}
51
```
52

53
### Web Components Configuration
54

55
Configuration options specific to the web-components compiler.
56

57
```typescript { .api }
58
/**
59
 * Configuration for Web Components compiler
60
 */
61
interface WebComponentsConfig {
62
  /** Call customElements.define automatically on module importing */
63
  autoDefine?: boolean;
64
  
65
  /** Prefix for auto defining (default: 'icon') */
66
  iconPrefix?: string;
67
  
68
  /** Use shadow DOM (default: false) */
69
  shadow?: boolean;
70
}
71
```
72

73
### Configuration Type Definitions
74

75
Type definitions for configuration functions and custom implementations.
76

77
```typescript { .api }
78
/**
79
 * Icon customizer function
80
 */
81
type IconCustomizer = (
82
  collection: string, 
83
  icon: string, 
84
  props: Record<string, string>
85
) => Awaitable<void>;
86

87
/**
88
 * Custom icon loader function
89
 */
90
type CustomIconLoader = (name: string) => Awaitable<string | undefined>;
91

92
/**
93
 * Inline collection definition
94
 */
95
type InlineCollection = Record<string, string | (() => Awaitable<string | undefined>)>;
96

97
/**
98
 * Custom compiler definition
99
 */
100
interface CustomCompiler {
101
  compiler: Awaitable<Compiler>;
102
  extension?: string;
103
}
104

105
/**
106
 * Compiler function signature
107
 */
108
type Compiler = (
109
  svg: string,
110
  collection: string,
111
  icon: string,
112
  options: ResolvedOptions
113
) => string | Promise<string>;
114

115
/**
116
 * Resolved configuration options
117
 */
118
type ResolvedOptions = Omit<Required<Options>, 'iconSource' | 'transform'> & Pick<Options, 'transform'>;
119
```
120

121
## Usage Examples
122

123
### Basic Configuration
124

125
```typescript
126
import Icons from "unplugin-icons/vite";
127

128
export default {
129
  plugins: [
130
    Icons({
131
      scale: 1.5,
132
      defaultClass: "icon",
133
      compiler: "vue3",
134
      autoInstall: true,
135
    }),
136
  ],
137
};
138
```
139

140
### Custom Collections
141

142
```typescript
143
import Icons from "unplugin-icons/vite";
144
import { FileSystemIconLoader } from "unplugin-icons/loaders";
145

146
export default {
147
  plugins: [
148
    Icons({
149
      customCollections: {
150
        // Load from filesystem
151
        'my-icons': FileSystemIconLoader('./src/assets/icons', svg => 
152
          svg.replace(/^<svg /, '<svg fill="currentColor" ')
153
        ),
154
        
155
        // Inline collection
156
        'custom': {
157
          'star': '<svg>...</svg>',
158
          'heart': () => Promise.resolve('<svg>...</svg>'),
159
        }
160
      },
161
      iconCustomizer: (collection, icon, props) => {
162
        if (collection === 'my-icons') {
163
          props.class = `custom-icon ${props.class || ''}`.trim();
164
        }
165
      },
166
    }),
167
  ],
168
};
169
```
170

171
### Framework-Specific Configuration
172

173
```typescript
174
// React/JSX setup
175
Icons({
176
  compiler: "jsx",
177
  jsx: "react",
178
  defaultStyle: "display: inline-block;",
179
})
180

181
// Vue 3 setup
182
Icons({
183
  compiler: "vue3",
184
  defaultClass: "vue-icon",
185
})
186

187
// Svelte setup
188
Icons({
189
  compiler: "svelte",
190
  scale: 1.1,
191
})
192

193
// Web Components setup
194
Icons({
195
  compiler: "web-components",
196
  webComponents: {
197
    autoDefine: true,
198
    iconPrefix: "my-icon",
199
    shadow: true,
200
  },
201
})
202
```
203

204
### Custom Compiler
205

206
```typescript
207
import Icons from "unplugin-icons/vite";
208

209
export default {
210
  plugins: [
211
    Icons({
212
      compiler: {
213
        compiler: async (svg, collection, icon, options) => {
214
          // Custom compilation logic
215
          return `export default "${svg.replace(/"/g, '\\"')}"`;
216
        },
217
        extension: "js",
218
      },
219
    }),
220
  ],
221
};
222
```