0
# Transformation & Building
1

2
Utility functions for building and transforming SVG content from icon data. These functions provide low-level access to the icon rendering pipeline for advanced use cases.
3

4
## Capabilities
5

6
### Build Icon SVG
7

8
Convert icon data and customizations into renderable SVG content with attributes.
9

10
```typescript { .api }
11
/**
12
 * Build SVG content from icon data and customizations
13
 * @param icon - Icon data containing SVG body and metadata
14
 * @param customisations - Optional customizations (size, rotation, flip, etc.)
15
 * @returns Object containing SVG attributes and body content
16
 */
17
function buildIcon(
18
  icon: IconifyIcon, 
19
  customisations?: IconifyIconCustomisations
20
): IconifyIconBuildResult;
21

22
interface IconifyIconBuildResult {
23
  /** SVG element attributes (width, height, viewBox, etc.) */
24
  attributes: Record<string, string>;
25
  
26
  /** SVG body content (inner HTML) */
27
  body: string;
28
}
29

30
interface IconifyIconCustomisations {
31
  width?: IconifyIconSize;
32
  height?: IconifyIconSize;
33
  hFlip?: boolean;
34
  vFlip?: boolean;
35
  rotate?: string | number;
36
  inline?: boolean;
37
}
38

39
type IconifyIconSize = number | string;
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { buildIcon } from "@iconify/react";
46

47
const iconData = {
48
  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"/>',
49
  width: 24,
50
  height: 24
51
};
52

53
// Build basic icon
54
const result = buildIcon(iconData);
55
console.log("Attributes:", result.attributes);
56
console.log("Body:", result.body);
57

58
// Build with customizations
59
const customResult = buildIcon(iconData, {
60
  width: 32,
61
  height: 32,
62
  rotate: 1, // 90 degrees
63
  hFlip: true,
64
  color: "red"
65
});
66

67
// Use result to create SVG element
68
const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
69
Object.entries(customResult.attributes).forEach(([key, value]) => {
70
  svg.setAttribute(key, value);
71
});
72
svg.innerHTML = customResult.body;
73

74
// Build for different sizes
75
const sizes = [16, 24, 32, 48];
76
const builtIcons = sizes.map(size => buildIcon(iconData, { 
77
  width: size, 
78
  height: size 
79
}));
80
```
81

82
### Replace SVG IDs
83

84
Replace ID attributes in SVG content to ensure uniqueness when multiple icons are used.
85

86
```typescript { .api }
87
/**
88
 * Replace IDs in SVG content to ensure uniqueness
89
 * @param body - SVG body content containing potential ID attributes
90
 * @param prefix - Prefix for new IDs, or function that returns unique ID
91
 * @returns SVG content with replaced IDs
92
 */
93
function replaceIDs(
94
  body: string, 
95
  prefix?: string | (() => string)
96
): string;
97
```
98

99
**Usage Examples:**
100

101
```typescript
102
import { replaceIDs } from "@iconify/react";
103

104
const svgBody = `
105
  <defs>
106
    <linearGradient id="grad1">
107
      <stop offset="0%" stop-color="red"/>
108
      <stop offset="100%" stop-color="blue"/>
109
    </linearGradient>
110
  </defs>
111
  <rect width="100" height="100" fill="url(#grad1)"/>
112
`;
113

114
// Replace with string prefix
115
const uniqueBody1 = replaceIDs(svgBody, "icon1-");
116
console.log(uniqueBody1);
117
// Result: IDs become "icon1-grad1", etc.
118

119
// Replace with function for dynamic IDs
120
let counter = 0;
121
const uniqueBody2 = replaceIDs(svgBody, () => `dynamic-${++counter}-`);
122
console.log(uniqueBody2);
123

124
// Use in component creation
125
function createUniqueIcon(iconData: IconifyIcon, id: string) {
126
  const built = buildIcon(iconData);
127
  const uniqueBody = replaceIDs(built.body, `${id}-`);
128
  
129
  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
130
  Object.entries(built.attributes).forEach(([key, value]) => {
131
    svg.setAttribute(key, value);
132
  });
133
  svg.innerHTML = uniqueBody;
134
  
135
  return svg;
136
}
137

138
// Ensure uniqueness in React component
139
function CustomIconComponent({ iconData, componentId }) {
140
  const built = buildIcon(iconData);
141
  const safeBody = replaceIDs(built.body, `${componentId}-`);
142
  
143
  return React.createElement("svg", {
144
    ...built.attributes,
145
    dangerouslySetInnerHTML: { __html: safeBody }
146
  });
147
}
148
```
149

150
### Calculate Icon Size
151

152
Calculate icon dimensions with proper aspect ratio handling and precision control.
153

154
```typescript { .api }
155
/**
156
 * Calculate icon dimensions with aspect ratio handling
157
 * @param size - Input size (number, string, or 'auto')
158
 * @param ratio - Aspect ratio (width/height)
159
 * @param precision - Decimal precision for calculations (default: 2)
160
 * @returns Calculated size value
161
 */
162
function calculateSize(
163
  size: IconifyIconSize, 
164
  ratio: number, 
165
  precision?: number
166
): IconifyIconSize;
167

168
type IconifyIconSize = number | string;
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
import { calculateSize } from "@iconify/react";
175

176
// Calculate height from width maintaining aspect ratio
177
const iconRatio = 24 / 16; // width/height = 1.5
178
const calculatedHeight = calculateSize(32, 1/iconRatio); // Calculate height from width
179
console.log("Height for width 32:", calculatedHeight); // Result: 21.33
180

181
// Calculate width from height
182
const calculatedWidth = calculateSize(20, iconRatio); // Calculate width from height  
183
console.log("Width for height 20:", calculatedWidth); // Result: 30
184

185
// With custom precision
186
const preciseSize = calculateSize(32, 1/iconRatio, 4);
187
console.log("Precise calculation:", preciseSize); // More decimal places
188

189
// Handle string sizes
190
const stringSize = calculateSize("2em", iconRatio);
191
console.log("String size result:", stringSize); // Passes through string values
192

193
// Use in icon sizing logic
194
function getIconDimensions(originalIcon: IconifyIcon, targetWidth?: number, targetHeight?: number) {
195
  const ratio = (originalIcon.width || 16) / (originalIcon.height || 16);
196
  
197
  if (targetWidth && !targetHeight) {
198
    return {
199
      width: targetWidth,
200
      height: calculateSize(targetWidth, 1/ratio)
201
    };
202
  } else if (targetHeight && !targetWidth) {
203
    return {
204
      width: calculateSize(targetHeight, ratio),
205
      height: targetHeight
206
    };
207
  } else if (targetWidth && targetHeight) {
208
    return { width: targetWidth, height: targetHeight };
209
  } else {
210
    return { width: originalIcon.width || 16, height: originalIcon.height || 16 };
211
  }
212
}
213

214
// Example usage
215
const icon = { body: "...", width: 24, height: 16 };
216
const dimensions = getIconDimensions(icon, 48); // Width=48, Height=32 (maintains ratio)
217
```
218

219
### Advanced Building Scenarios
220

221
Combine building functions for complex icon manipulation.
222

223
```typescript
224
import { buildIcon, replaceIDs, calculateSize } from "@iconify/react";
225

226
// Create responsive icon with multiple sizes
227
function createResponsiveIcon(iconData: IconifyIcon, sizes: number[]) {
228
  const ratio = (iconData.width || 16) / (iconData.height || 16);
229
  
230
  return sizes.map((size, index) => {
231
    const height = calculateSize(size, 1/ratio);
232
    const built = buildIcon(iconData, { width: size, height });
233
    const uniqueBody = replaceIDs(built.body, `responsive-${index}-`);
234
    
235
    return {
236
      size,
237
      attributes: built.attributes,
238
      body: uniqueBody
239
    };
240
  });
241
}
242

243
// Create themed icon variants
244
function createThemedIcons(iconData: IconifyIcon, themes: Record<string, any>) {
245
  return Object.entries(themes).map(([themeName, customizations]) => {
246
    const built = buildIcon(iconData, customizations);
247
    const themedBody = replaceIDs(built.body, `${themeName}-`);
248
    
249
    return {
250
      theme: themeName,
251
      attributes: built.attributes,
252
      body: themedBody
253
    };
254
  });
255
}
256

257
// Usage
258
const iconData = {
259
  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"/>',
260
  width: 24,
261
  height: 24
262
};
263

264
const responsiveVersions = createResponsiveIcon(iconData, [16, 24, 32, 48]);
265
console.log("Responsive icons:", responsiveVersions);
266

267
const themedVersions = createThemedIcons(iconData, {
268
  small: { width: 16, height: 16 },
269
  medium: { width: 24, height: 24 },
270
  large: { width: 32, height: 32, rotate: 1 },
271
  flipped: { width: 24, height: 24, hFlip: true }
272
});
273
console.log("Themed icons:", themedVersions);
274
```
275

276
### Manual SVG Creation
277

278
Use building functions to create SVG elements programmatically.
279

280
```typescript
281
import { buildIcon, replaceIDs } from "@iconify/react";
282

283
function createSVGElement(iconData: IconifyIcon, customizations?: any, idPrefix?: string): SVGSVGElement {
284
  // Build the icon with customizations
285
  const built = buildIcon(iconData, customizations);
286
  
287
  // Ensure unique IDs if prefix provided
288
  const body = idPrefix ? replaceIDs(built.body, idPrefix) : built.body;
289
  
290
  // Create SVG element
291
  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
292
  
293
  // Set attributes
294
  Object.entries(built.attributes).forEach(([key, value]) => {
295
    svg.setAttribute(key, value);
296
  });
297
  
298
  // Set content
299
  svg.innerHTML = body;
300
  
301
  return svg;
302
}
303

304
// Create multiple unique SVG elements
305
const icons = [
306
  { name: "star", data: starIconData },
307
  { name: "heart", data: heartIconData },
308
  { name: "home", data: homeIconData }
309
];
310

311
const svgElements = icons.map((icon, index) => 
312
  createSVGElement(icon.data, { width: 32, height: 32 }, `${icon.name}-${index}-`)
313
);
314

315
// Append to DOM
316
svgElements.forEach(svg => {
317
  document.body.appendChild(svg);
318
});
319
```