0
# Icon Loaders
1

2
Custom icon loading functionality for filesystem icons, external packages, and custom icon sources.
3

4
## Capabilities
5

6
### FileSystemIconLoader
7

8
Load icons from a filesystem directory with optional SVG transformation.
9

10
```typescript { .api }
11
/**
12
 * Creates a custom icon loader for filesystem icons
13
 * @param dir - Directory path containing SVG files
14
 * @param transform - Optional SVG transformation function
15
 * @returns CustomIconLoader function
16
 */
17
function FileSystemIconLoader(
18
  dir: string, 
19
  transform?: (svg: string) => Awaitable<string>
20
): CustomIconLoader;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { FileSystemIconLoader } from "unplugin-icons/loaders";
27
import Icons from "unplugin-icons/vite";
28

29
export default {
30
  plugins: [
31
    Icons({
32
      customCollections: {
33
        // Basic filesystem loader
34
        'local': FileSystemIconLoader('./src/assets/icons'),
35
        
36
        // With SVG transformation
37
        'branded': FileSystemIconLoader(
38
          './src/assets/brand-icons',
39
          (svg) => svg.replace(/^<svg /, '<svg fill="currentColor" ')
40
        ),
41
        
42
        // With async transformation
43
        'processed': FileSystemIconLoader(
44
          './src/assets/raw-icons',
45
          async (svg) => {
46
            // Custom processing logic
47
            return svg
48
              .replace(/fill="[^"]*"/g, '')  // Remove existing fills
49
              .replace(/^<svg/, '<svg fill="currentColor"');  // Add currentColor
50
          }
51
        ),
52
      },
53
    }),
54
  ],
55
};
56
```
57

58
### ExternalPackageIconLoader
59

60
Load icons from external npm packages with optional auto-installation.
61

62
```typescript { .api }
63
/**
64
 * Creates custom icon loaders for external packages
65
 * @param packageName - Name of the external package containing icons
66
 * @param autoInstall - Auto-installation configuration
67
 * @returns Record of collection names to CustomIconLoader functions
68
 */
69
function ExternalPackageIconLoader(
70
  packageName: ExternalPkgName, 
71
  autoInstall?: AutoInstall
72
): Record<string, CustomIconLoader>;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
import { ExternalPackageIconLoader } from "unplugin-icons/loaders";
79
import Icons from "unplugin-icons/vite";
80

81
export default {
82
  plugins: [
83
    Icons({
84
      customCollections: {
85
        // Load from external package
86
        ...ExternalPackageIconLoader("@my-company/icon-package"),
87
        
88
        // With auto-install
89
        ...ExternalPackageIconLoader(
90
          "@iconscout/unicons", 
91
          { autoInstall: true }
92
        ),
93
      },
94
    }),
95
  ],
96
};
97
```
98

99
### CustomIconLoader Type
100

101
The function signature for custom icon loaders.
102

103
```typescript { .api }
104
/**
105
 * Custom icon loader function signature
106
 * @param name - Icon name to load
107
 * @returns Promise resolving to SVG string or undefined if not found
108
 */
109
type CustomIconLoader = (name: string) => Awaitable<string | undefined>;
110
```
111

112
### InlineCollection Type
113

114
Define icons directly in configuration using inline collections.
115

116
```typescript { .api }
117
/**
118
 * Inline collection of icons defined as strings or functions
119
 */
120
type InlineCollection = Record<string, string | (() => Awaitable<string | undefined>)>;
121
```
122

123
**Usage Examples:**
124

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

128
export default {
129
  plugins: [
130
    Icons({
131
      customCollections: {
132
        // Static inline icons
133
        'ui': {
134
          'check': '<svg viewBox="0 0 24 24"><path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/></svg>',
135
          'close': '<svg viewBox="0 0 24 24"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>',
136
        },
137
        
138
        // Dynamic inline icons
139
        'dynamic': {
140
          'star': () => fetch('/api/icon/star').then(r => r.text()),
141
          'heart': async () => {
142
            const response = await fetch('/api/icon/heart');
143
            return response.text();
144
          },
145
        },
146
      },
147
    }),
148
  ],
149
};
150
```
151

152
## Advanced Usage Patterns
153

154
### Combined Loader Strategy
155

156
```typescript
157
import { FileSystemIconLoader, ExternalPackageIconLoader } from "unplugin-icons/loaders";
158
import Icons from "unplugin-icons/vite";
159

160
export default {
161
  plugins: [
162
    Icons({
163
      customCollections: {
164
        // Combine different loading strategies
165
        'brand': FileSystemIconLoader('./assets/brand'),
166
        'ui': FileSystemIconLoader('./assets/ui', svg => 
167
          svg.replace(/stroke="[^"]*"/g, 'stroke="currentColor"')
168
        ),
169
        ...ExternalPackageIconLoader("@company/icons"),
170
        
171
        // Fallback/override system
172
        'icons': {
173
          // High priority inline icons
174
          'logo': '<svg>...</svg>',
175
          'special': async () => {
176
            try {
177
              return await fetch('/api/special-icon').then(r => r.text());
178
            } catch {
179
              // Fallback to filesystem
180
              return FileSystemIconLoader('./fallbacks')('special');
181
            }
182
          },
183
        },
184
      },
185
    }),
186
  ],
187
};
188
```
189

190
### Custom Transformation Pipeline
191

192
```typescript
193
import { FileSystemIconLoader } from "unplugin-icons/loaders";
194

195
// Create reusable transformation functions
196
const addCurrentColor = (svg: string) => 
197
  svg.replace(/fill="(?!none)[^"]*"/g, 'fill="currentColor"');
198

199
const addViewBox = (svg: string) => 
200
  svg.includes('viewBox') ? svg : svg.replace('<svg', '<svg viewBox="0 0 24 24"');
201

202
const transformPipeline = (svg: string) => addViewBox(addCurrentColor(svg));
203

204
export default {
205
  plugins: [
206
    Icons({
207
      customCollections: {
208
        'icons': FileSystemIconLoader('./src/icons', transformPipeline),
209
      },
210
    }),
211
  ],
212
};
213
```
214

215
### Dynamic Collection Loading
216

217
```typescript
218
import Icons from "unplugin-icons/vite";
219

220
// Function to create dynamic collections
221
const createDynamicCollection = (apiEndpoint: string): InlineCollection => ({
222
  async load(name: string) {
223
    try {
224
      const response = await fetch(`${apiEndpoint}/${name}.svg`);
225
      return response.ok ? response.text() : undefined;
226
    } catch {
227
      return undefined;
228
    }
229
  },
230
});
231

232
export default {
233
  plugins: [
234
    Icons({
235
      customCollections: {
236
        'remote': createDynamicCollection('https://api.example.com/icons'),
237
      },
238
    }),
239
  ],
240
};
241
```