0
# Iconify for React
1

2
Iconify for React is a React icon component library that provides access to over 200,000 icons from 150+ icon sets through the Iconify ecosystem. Unlike traditional icon libraries that bundle all icons, this component loads icon data on demand from the Iconify API, resulting in smaller bundle sizes and better performance. The component supports extensive customization options and renders pixel-perfect SVG icons.
3

4
## Package Information
5

6
- **Package Name**: @iconify/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @iconify/react`
10

11
## Core Imports
12

13
ESM (default):
14

15
```typescript
16
import { Icon, InlineIcon, loadIcons, addIcon } from "@iconify/react";
17
```
18

19
For offline usage:
20

21
```typescript
22
import { Icon, InlineIcon, addIcon, addCollection } from "@iconify/react/offline";
23
```
24

25
CommonJS:
26

27
```javascript
28
const { Icon, InlineIcon, loadIcons, addIcon } = require("@iconify/react");
29
```
30

31
## Basic Usage
32

33
### Online Mode (API-based)
34

35
```typescript
36
import { Icon, InlineIcon } from "@iconify/react";
37

38
function App() {
39
  return (
40
    <div>
41
      {/* Block icon - centers vertically */}
42
      <Icon icon="mdi:home" />
43
      
44
      {/* Inline icon - aligns with text baseline */}
45
      <InlineIcon icon="mdi:account" />
46
      
47
      {/* With customizations */}
48
      <Icon 
49
        icon="mdi:heart" 
50
        color="red" 
51
        width="32" 
52
        height="32" 
53
        rotate={1} 
54
      />
55
      
56
      {/* With fallback content */}
57
      <Icon 
58
        icon="missing:icon" 
59
        fallback={<span>Loading...</span>}
60
      />
61
    </div>
62
  );
63
}
64
```
65

66
### Offline Mode
67

68
```typescript
69
import { Icon, addIcon, addCollection } from "@iconify/react/offline";
70

71
// Add individual icon
72
addIcon("custom-icon", {
73
  body: '<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>',
74
  width: 24,
75
  height: 24
76
});
77

78
// Add icon collection
79
addCollection({
80
  prefix: "custom",
81
  icons: {
82
    star: {
83
      body: '<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>',
84
    }
85
  },
86
  width: 24,
87
  height: 24
88
});
89

90
function OfflineApp() {
91
  return (
92
    <div>
93
      <Icon icon="custom-icon" />
94
      <Icon icon="custom:star" />
95
    </div>
96
  );
97
}
98
```
99

100
## Architecture
101

102
Iconify for React is built around several key components:
103

104
- **React Components**: `Icon` and `InlineIcon` components for different display modes
105
- **Storage System**: Icon data storage and retrieval with automatic loading from API
106
- **API Integration**: Automatic loading of icon data from Iconify API on demand
107
- **Offline Support**: Pre-loaded icon usage without API calls via `/offline` sub-package
108
- **Customization Engine**: Extensive icon transformation and styling options
109
- **Type Safety**: Full TypeScript support with comprehensive type definitions
110

111
## Capabilities
112

113
### React Components
114

115
Core React components for rendering icons with different display behaviors and extensive customization options.
116

117
```typescript { .api }
118
const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
119
const InlineIcon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
120

121
interface IconProps extends React.SVGProps<SVGSVGElement>, IconifyIconProps {}
122

123
interface IconifyIconProps extends IconifyIconCustomisations {
124
  icon: IconifyIcon | string;
125
  mode?: IconifyRenderMode;
126
  color?: string;
127
  flip?: string;
128
  id?: string;
129
  ssr?: boolean;
130
  fallback?: React.ReactNode;
131
  onLoad?: IconifyIconOnLoad;
132
}
133
```
134

135
[React Components](./components.md)
136

137
### Icon Storage Management
138

139
Functions for managing icon data in local storage, including loading, checking, and adding icons.
140

141
```typescript { .api }
142
function iconLoaded(name: string): boolean;
143
function getIcon(name: string): IconifyIcon | null;
144
function listIcons(provider?: string, prefix?: string): string[];
145
function addIcon(name: string, data: IconifyIcon): boolean;
146
function addCollection(data: IconifyJSON, provider?: string): boolean;
147
```
148

149
[Storage Management](./storage.md)
150

151
### API Loading
152

153
Functions for loading icon data from the Iconify API, including batch loading and custom providers.
154

155
```typescript { .api }
156
function loadIcons(
157
  icons: string[], 
158
  callback?: IconifyIconLoaderCallback
159
): IconifyIconLoaderAbort;
160

161
function loadIcon(icon: string): Promise<IconifyIcon>;
162

163
function addAPIProvider(
164
  provider: string, 
165
  config: PartialIconifyAPIConfig
166
): boolean;
167

168
function setCustomIconLoader(loader: IconifyCustomIconLoader): void;
169

170
function setCustomIconsLoader(loader: IconifyCustomIconsLoader): void;
171
```
172

173
[API Loading](./api-loading.md)
174

175
### Icon Transformation & Building
176

177
Utility functions for building and transforming SVG content from icon data.
178

179
```typescript { .api }
180
function buildIcon(
181
  icon: IconifyIcon, 
182
  customisations?: IconifyIconCustomisations
183
): IconifyIconBuildResult;
184

185
function replaceIDs(
186
  body: string, 
187
  prefix?: string | (() => string)
188
): string;
189

190
function calculateSize(
191
  size: IconifyIconSize, 
192
  ratio: number, 
193
  precision?: number
194
): IconifyIconSize;
195
```
196

197
[Transformation & Building](./building.md)
198

199
### Offline Usage
200

201
Specialized components and functions for offline icon usage without API dependencies.
202

203
```typescript { .api }
204
// Offline versions (from @iconify/react/offline)
205
const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
206
const InlineIcon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
207

208
function addIcon(name: string, data: IconifyIcon): void;
209
function addCollection(data: IconifyJSON, prefix?: string | boolean): void;
210
```
211

212
[Offline Usage](./offline.md)
213

214
### Internal API
215

216
Low-level API functions for advanced use cases and custom integrations.
217

218
```typescript { .api }
219
interface IconifyAPIInternalFunctions {
220
  getAPIConfig(provider: string): IconifyAPIConfig | undefined;
221
  setAPIModule(provider: string, module: IconifyAPIModule): void;
222
  sendAPIQuery(provider: string, data: IconifyAPIQueryParams, callback: Function): void;
223
  setFetch(fetch: Function): void;
224
  getFetch(): Function;
225
  listAPIProviders(): string[];
226
}
227

228
// Internal API access
229
const _api: IconifyAPIInternalFunctions;
230
```
231

232
## Types
233

234
```typescript { .api }
235
// Core Types
236
type IconifyRenderMode = 'style' | 'bg' | 'mask' | 'svg';
237
type IconElement = SVGSVGElement | HTMLSpanElement;
238
type IconifyIconOnLoad = (name: string) => void;
239

240
// Icon Data Types
241
interface IconifyIcon {
242
  body: string;
243
  width?: number;
244
  height?: number;
245
  left?: number;
246
  top?: number;
247
  hFlip?: boolean;
248
  vFlip?: boolean;
249
  rotate?: number;
250
}
251

252
interface IconifyJSON {
253
  prefix: string;
254
  icons: Record<string, IconifyIcon>;
255
  aliases?: Record<string, Partial<IconifyIcon> & { parent: string }>;
256
  width?: number;
257
  height?: number;
258
  left?: number;
259
  top?: number;
260
  hFlip?: boolean;
261
  vFlip?: boolean;
262
  rotate?: number;
263
}
264

265
// Customization Types
266
interface IconifyIconCustomisations {
267
  width?: IconifyIconSize;
268
  height?: IconifyIconSize;
269
  hFlip?: boolean;
270
  vFlip?: boolean;
271
  rotate?: string | number;
272
  inline?: boolean;
273
}
274

275
type IconifyIconSize = number | string;
276

277
// API Types
278
interface PartialIconifyAPIConfig {
279
  resources: string[];
280
  index?: number;
281
  timeout?: number;
282
  rotate?: number;
283
  random?: boolean;
284
  dataAfterTimeout?: boolean;
285
}
286

287
interface IconifyIconBuildResult {
288
  attributes: Record<string, string>;
289
  body: string;
290
}
291

292
type IconifyIconLoaderCallback = (
293
  loaded: IconifyIconName[],
294
  missing: IconifyIconName[],
295
  pending: IconifyIconName[]
296
) => void;
297

298
type IconifyIconLoaderAbort = () => void;
299

300
interface IconifyIconName {
301
  provider: string;
302
  prefix: string;
303
  name: string;
304
}
305

306
// API Module Types
307
interface IconifyAPIModule {
308
  prepare: IconifyAPIPrepareIconsQuery;
309
  send: IconifyAPISendQuery;
310
}
311

312
type IconifyAPIPrepareIconsQuery = (
313
  provider: string,
314
  prefix: string,
315
  icons: string[]
316
) => IconifyAPIQueryParams[];
317

318
type IconifyAPISendQuery = (
319
  host: string,
320
  params: IconifyAPIQueryParams,
321
  callback: Function
322
) => void;
323

324
interface IconifyAPIQueryParams {
325
  type: string;
326
  provider: string;
327
  prefix: string;
328
  icons: string[];
329
  [key: string]: any;
330
}
331

332
interface IconifyAPIConfig {
333
  resources: string[];
334
  index: number;
335
  timeout: number;
336
  rotate: number;
337
  random: boolean;
338
  dataAfterTimeout: boolean;
339
}
340

341
// Custom Loader Types
342
type IconifyCustomIconLoader = (
343
  name: string,
344
  prefix: string,
345
  provider: string
346
) => Promise<IconifyIcon | null>;
347

348
type IconifyCustomIconsLoader = (
349
  names: string[],
350
  prefix: string,
351
  provider: string
352
) => Promise<(IconifyIcon | null)[]>;
353
```