0
# Image Generation
1

2
Convert font glyphs to PNG images for use in non-React Native contexts or when vector icons need to be rendered as static images. This functionality requires the optional native module package.
3

4
## Capabilities
5

6
### Native Image Generation
7

8
Generate PNG images from font glyphs using native platform capabilities.
9

10
```typescript { .api }
11
/**
12
 * Generate a PNG image from a font glyph asynchronously
13
 * @param fontFamilyName - Platform-specific font family name
14
 * @param glyph - Unicode character or string representation of the glyph
15
 * @param fontSize - Size of the rendered icon in points
16
 * @param color - Color as a numeric value (e.g., 0xFF0000 for red)
17
 * @returns Promise resolving to base64 data URI of the PNG image
18
 */
19
function getImageForFont(
20
  fontFamilyName: string,
21
  glyph: string,
22
  fontSize: number,
23
  color: number
24
): Promise<string>;
25

26
/**
27
 * Generate a PNG image from a font glyph synchronously
28
 * @param fontFamilyName - Platform-specific font family name
29
 * @param glyph - Unicode character or string representation of the glyph
30
 * @param fontSize - Size of the rendered icon in points
31
 * @param color - Color as a numeric value (e.g., 0xFF0000 for red)
32
 * @returns Base64 data URI of the PNG image
33
 */
34
function getImageForFontSync(
35
  fontFamilyName: string,
36
  glyph: string,
37
  fontSize: number,
38
  color: number
39
): string;
40

41
/**
42
 * Ensures the native module is properly linked and available
43
 * @throws Error if native module is not properly configured
44
 */
45
function ensureNativeModuleAvailable(): void;
46
```
47

48
### Icon Component Image Methods
49

50
All icon components created with `createIconSet` include built-in image generation methods.
51

52
```typescript { .api }
53
interface IconComponent<T> {
54
  /**
55
   * Generate image source asynchronously for the given icon
56
   * @param name - Icon name from the component's glyph map
57
   * @param size - Icon size in points (default: DEFAULT_ICON_SIZE)
58
   * @param color - Icon color as string (default: DEFAULT_ICON_COLOR)
59
   * @returns Promise resolving to image source object
60
   */
61
  getImageSource(name: T, size?: number, color?: string): Promise<ImageSource | undefined>;
62
  
63
  /**
64
   * Generate image source synchronously for the given icon
65
   * @param name - Icon name from the component's glyph map
66
   * @param size - Icon size in points (default: DEFAULT_ICON_SIZE)
67
   * @param color - Icon color as string (default: DEFAULT_ICON_COLOR)
68
   * @returns Image source object or undefined if generation fails
69
   */
70
  getImageSourceSync(name: T, size?: number, color?: string): ImageSource | undefined;
71
}
72

73
interface ImageSource {
74
  /** Data URI of the generated PNG image */
75
  uri: string;
76
  /** Scale factor for the image (typically 1) */
77
  scale: number;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { getImageForFont, getImageForFontSync } from '@react-native-vector-icons/get-image';
85
import FontAwesome6 from '@react-native-vector-icons/fontawesome6';
86

87
// Direct native module usage
88
const asyncImage = await getImageForFont(
89
  'FontAwesome6Free-Solid',
90
  '\uf015', // Unicode for 'home' icon
91
  24,
92
  0x4A90E2 // Blue color
93
);
94
// asyncImage = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
95

96
const syncImage = getImageForFontSync(
97
  'FontAwesome6Free-Regular',
98
  '\uf005', // Unicode for 'star' icon
99
  20,
100
  0xFFD700 // Gold color
101
);
102

103
// Using icon component methods (recommended)
104
const homeImage = await FontAwesome6.getImageSource('home', 24, '#4A90E2');
105
// homeImage = { uri: 'data:image/png;base64,...', scale: 1 }
106

107
const starImage = FontAwesome6.getImageSourceSync('star', 20, 'gold');
108
// starImage = { uri: 'data:image/png;base64,...', scale: 1 } or undefined
109
```
110

111
### Multi-Style Components
112

113
For components that support multiple styles (like FontAwesome 6), image generation methods accept an additional style parameter.
114

115
```typescript { .api }
116
interface MultiStyleImageMethods {
117
  getImageSource(
118
    iconStyle: 'regular' | 'solid' | 'brand',
119
    name: string,
120
    size?: number,
121
    color?: string
122
  ): Promise<ImageSource | undefined>;
123
  
124
  getImageSourceSync(
125
    iconStyle: 'regular' | 'solid' | 'brand',
126
    name: string,
127
    size?: number,
128
    color?: string
129
  ): ImageSource | undefined;
130
}
131
```
132

133
```typescript
134
import FontAwesome6 from '@react-native-vector-icons/fontawesome6';
135

136
// Generate different styles of the same icon
137
const regularStar = await FontAwesome6.getImageSource('regular', 'star', 24, '#FFD700');
138
const solidStar = await FontAwesome6.getImageSource('solid', 'star', 24, '#FFD700');
139
const brandGithub = await FontAwesome6.getImageSource('brand', 'github', 20, '#333');
140
```
141

142
## Setup Requirements
143

144
### Native Module Installation
145

146
The image generation functionality requires the native module package:
147

148
```bash
149
npm install @react-native-vector-icons/get-image
150
```
151

152
### Platform Setup
153

154
- **iOS**: Run `pod install` after installation
155
- **Android**: Rebuild the app after installation
156
- **Expo Go**: Not supported (requires custom development build)
157
- **Web**: Not available (use SVG alternatives)
158

159
### Linking Verification
160

161
```typescript
162
import { ensureNativeModuleAvailable } from '@react-native-vector-icons/get-image';
163

164
try {
165
  ensureNativeModuleAvailable();
166
  console.log('Native module is properly linked');
167
} catch (error) {
168
  console.error('Native module setup issue:', error.message);
169
  // Handle graceful fallback
170
}
171
```
172

173
## Color Format Handling
174

175
The native module expects colors as numeric values, but icon component methods accept string colors.
176

177
```typescript
178
// String colors (icon component methods)
179
const image1 = await FontAwesome6.getImageSource('home', 24, '#4A90E2');
180
const image2 = await FontAwesome6.getImageSource('star', 20, 'red');
181
const image3 = await FontAwesome6.getImageSource('heart', 18, 'rgba(255, 0, 0, 0.8)');
182

183
// Numeric colors (native module direct usage)
184
const directImage = await getImageForFont(
185
  'FontAwesome6Free-Solid',
186
  '\uf015',
187
  24,
188
  0x4A90E2 // Hexadecimal color value
189
);
190

191
// Color conversion utility (internal)
192
const colorToNumber = (color: string): number => {
193
  // Converts CSS color strings to numeric values
194
  // Handles: hex (#RGB, #RRGGBB), named colors, rgba(), etc.
195
};
196
```
197

198
## Performance Considerations
199

200
### Caching
201

202
Image generation results are automatically cached to avoid regenerating the same images:
203

204
```typescript
205
// First call generates the image
206
const image1 = await FontAwesome6.getImageSource('home', 24, '#4A90E2');
207

208
// Subsequent calls return cached result
209
const image2 = await FontAwesome6.getImageSource('home', 24, '#4A90E2');
210
// Returned immediately from cache
211
```
212

213
### Synchronous vs Asynchronous
214

215
```typescript
216
// Synchronous: Fast but may block UI thread
217
const syncImage = FontAwesome6.getImageSourceSync('star', 20, 'gold');
218

219
// Asynchronous: Recommended for UI responsiveness
220
const asyncImage = await FontAwesome6.getImageSource('star', 20, 'gold');
221

222
// Use sync only when:
223
// - Image is likely cached
224
// - Called outside render cycle
225
// - Performance testing confirms no blocking
226
```
227

228
## Error Handling
229

230
### Common Failure Scenarios
231

232
```typescript
233
// Native module not linked
234
try {
235
  const image = await getImageForFont('FontName', '\uf000', 24, 0x000000);
236
} catch (error) {
237
  if (error.message.includes("doesn't seem to be linked")) {
238
    console.log('Run pod install and rebuild the app');
239
  }
240
}
241

242
// Font not found
243
const image = await FontAwesome6.getImageSource('nonexistent-icon', 24, '#000');
244
// Returns undefined for invalid icon names
245

246
// Invalid color format (direct native usage)
247
try {
248
  const image = await getImageForFont('FontName', '\uf000', 24, 'invalid-color');
249
} catch (error) {
250
  console.error('Color must be numeric for direct native calls');
251
}
252
```
253

254
### Graceful Fallbacks
255

256
```typescript
257
const getIconImage = async (name: string, size: number, color: string) => {
258
  try {
259
    // Try to generate image
260
    const image = await FontAwesome6.getImageSource(name, size, color);
261
    return image || getDefaultImage(); // Fallback for invalid icons
262
  } catch (error) {
263
    console.warn('Image generation failed:', error);
264
    return getDefaultImage(); // Fallback for native module issues
265
  }
266
};
267

268
const getDefaultImage = () => ({
269
  uri: 'data:image/png;base64,iVBORw0...', // Placeholder image
270
  scale: 1
271
});
272
```
273

274
## Integration Examples
275

276
### React Native Image Component
277

278
```typescript
279
import { Image } from 'react-native';
280
import FontAwesome6 from '@react-native-vector-icons/fontawesome6';
281

282
const IconImage = ({ name, size = 24, color = '#000' }) => {
283
  const [imageSource, setImageSource] = useState(null);
284
  
285
  useEffect(() => {
286
    FontAwesome6.getImageSource(name, size, color)
287
      .then(setImageSource)
288
      .catch(console.error);
289
  }, [name, size, color]);
290
  
291
  return imageSource ? (
292
    <Image source={imageSource} style={{ width: size, height: size }} />
293
  ) : null;
294
};
295
```
296

297
### Web/HTML Context
298

299
```typescript
300
// Generate image for use in web context
301
const exportIconAsImage = async (iconName: string) => {
302
  const image = await FontAwesome6.getImageSource(iconName, 48, '#333');
303
  
304
  if (image) {
305
    // Use in img tag, canvas, or download
306
    return image.uri; // data:image/png;base64,...
307
  }
308
  
309
  return null;
310
};
311
```