0
# React Components
1

2
Core React components for rendering icons with different display behaviors and extensive customization options.
3

4
## Capabilities
5

6
### Icon Component
7

8
Block-level icon component that renders icons as SVG elements with middle vertical alignment. This is the default component for most use cases.
9

10
```typescript { .api }
11
/**
12
 * Block icon component with middle vertical alignment
13
 * @param props - Icon properties including icon data/name and customizations
14
 * @param ref - Forward ref to the rendered SVG or span element
15
 */
16
const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { Icon } from "@iconify/react";
23

24
// Basic usage with icon name
25
<Icon icon="mdi:home" />
26

27
// With custom dimensions
28
<Icon icon="mdi:home" width="32" height="32" />
29

30
// With color (monotone icons only)
31
<Icon icon="mdi:home" color="blue" />
32

33
// With rotation (quarter-turns)
34
<Icon icon="mdi:home" rotate={1} />
35

36
// With rotation (degrees)
37
<Icon icon="mdi:home" rotate="45deg" />
38

39
// With flip transformations
40
<Icon icon="mdi:home" hFlip={true} />
41
<Icon icon="mdi:home" flip="horizontal,vertical" />
42

43
// With CSS properties
44
<Icon 
45
  icon="mdi:home" 
46
  style={{ margin: '10px' }}
47
  className="my-icon"
48
/>
49

50
// With fallback content
51
<Icon 
52
  icon="might-not-exist:icon" 
53
  fallback={<span>Loading...</span>}
54
/>
55

56
// With load callback (API mode only)
57
<Icon 
58
  icon="mdi:home" 
59
  onLoad={(name) => console.log(`Icon ${name} loaded`)}
60
/>
61
```
62

63
### InlineIcon Component
64

65
Inline icon component that renders icons with baseline vertical alignment, making it suitable for use within text content.
66

67
```typescript { .api }
68
/**
69
 * Inline icon component with baseline vertical alignment
70
 * Adds verticalAlign: -0.125em style for proper text alignment
71
 * @param props - Icon properties including icon data/name and customizations
72
 * @param ref - Forward ref to the rendered SVG or span element
73
 */
74
const InlineIcon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import { InlineIcon } from "@iconify/react";
81

82
// Inline with text
83
<p>
84
  Welcome to your <InlineIcon icon="mdi:home" /> home page
85
</p>
86

87
// In buttons
88
<button>
89
  <InlineIcon icon="mdi:plus" /> Add Item
90
</button>
91

92
// All Icon props work with InlineIcon
93
<InlineIcon 
94
  icon="mdi:heart" 
95
  color="red" 
96
  width="16" 
97
  height="16" 
98
/>
99
```
100

101
### Icon Properties
102

103
Complete interface for icon component properties, combining React SVG props with Iconify-specific options.
104

105
```typescript { .api }
106
interface IconProps extends React.SVGProps<SVGSVGElement>, IconifyIconProps {}
107

108
interface IconifyIconProps extends IconifyIconCustomisations {
109
  /** The icon to render - either icon data object or icon name string */
110
  icon: IconifyIcon | string;
111
  
112
  /** Rendering mode for the icon */
113
  mode?: IconifyRenderMode;
114
  
115
  /** Icon color (for monotone icons only) */
116
  color?: string;
117
  
118
  /** Flip transformation shorthand */
119
  flip?: string;
120
  
121
  /** Unique identifier for the icon */
122
  id?: string;
123
  
124
  /** Server-side rendering mode */
125
  ssr?: boolean;
126
  
127
  /** Fallback content while icon is loading or failed to load */
128
  fallback?: React.ReactNode;
129
  
130
  /** Callback fired when icon data is loaded from API */
131
  onLoad?: IconifyIconOnLoad;
132
}
133

134
interface IconifyIconCustomisations {
135
  /** Icon width */
136
  width?: IconifyIconSize;
137
  
138
  /** Icon height */
139
  height?: IconifyIconSize;
140
  
141
  /** Horizontal flip */
142
  hFlip?: boolean;
143
  
144
  /** Vertical flip */
145
  vFlip?: boolean;
146
  
147
  /** Rotation - number for quarter-turns or string with units */
148
  rotate?: string | number;
149
  
150
  /** Display mode - true for inline, false for block */
151
  inline?: boolean;
152
}
153

154
type IconifyIconSize = number | string;
155
type IconifyRenderMode = 'style' | 'bg' | 'mask' | 'svg';
156
type IconElement = SVGSVGElement | HTMLSpanElement;
157
type IconifyIconOnLoad = (name: string) => void;
158
```
159

160
### Icon Data Format
161

162
Format for providing icon data directly to components instead of using icon names.
163

164
```typescript { .api }
165
interface IconifyIcon {
166
  /** SVG content inside <svg> element */
167
  body: string;
168
  
169
  /** Icon width (default: 16) */
170
  width?: number;
171
  
172
  /** Icon height (default: 16) */
173
  height?: number;
174
  
175
  /** Left offset */
176
  left?: number;
177
  
178
  /** Top offset */
179
  top?: number;
180
  
181
  /** Horizontal flip */
182
  hFlip?: boolean;
183
  
184
  /** Vertical flip */
185
  vFlip?: boolean;
186
  
187
  /** Rotation in quarter-turns */
188
  rotate?: number;
189
}
190
```
191

192
**Usage with Icon Data:**
193

194
```typescript
195
import { Icon } from "@iconify/react";
196

197
const customIcon: IconifyIcon = {
198
  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"/>',
199
  width: 24,
200
  height: 24
201
};
202

203
<Icon icon={customIcon} />
204
```
205

206
### Server-Side Rendering
207

208
Special considerations for server-side rendering to prevent hydration issues.
209

210
```typescript
211
// Enable SSR mode to render immediately without waiting for mount
212
<Icon icon="mdi:home" ssr={true} />
213

214
// Provide fallback for icons that might not load on server
215
<Icon 
216
  icon="mdi:home" 
217
  ssr={true}
218
  fallback={<span className="icon-placeholder" />}
219
/>
220
```
221

222
### Render Modes
223

224
Different rendering modes for various use cases and performance optimizations.
225

226
```typescript
227
// Default SVG rendering (recommended)
228
<Icon icon="mdi:home" mode="svg" />
229

230
// CSS background-image rendering
231
<Icon icon="mdi:home" mode="bg" />
232

233
// CSS mask-image rendering (for monotone icons)
234
<Icon icon="mdi:home" mode="mask" />
235

236
// Auto-detect between bg/mask based on icon content
237
<Icon icon="mdi:home" mode="style" />
238
```
239

240
### Forward Refs
241

242
Both Icon and InlineIcon components support React forward refs for direct DOM element access.
243

244
```typescript
245
import { useRef } from 'react';
246
import { Icon } from "@iconify/react";
247

248
function MyComponent() {
249
  const iconRef = useRef<SVGSVGElement>(null);
250
  
251
  const handleClick = () => {
252
    if (iconRef.current) {
253
      iconRef.current.style.transform = 'scale(1.2)';
254
    }
255
  };
256
  
257
  return (
258
    <Icon 
259
      ref={iconRef}
260
      icon="mdi:home" 
261
      onClick={handleClick}
262
    />
263
  );
264
}
265
```