0
# Core Icon Creation
1

2
The foundational API for creating icon components from font files and glyph mappings. This is the primary interface for building custom icons or integrating new font families.
3

4
## Capabilities
5

6
### CreateIconSet Function
7

8
Creates a React component for rendering vector icons from a font file.
9

10
```typescript { .api }
11
/**
12
 * Creates an icon component from a glyph mapping and font information
13
 * @param glyphMap - Object mapping icon names to Unicode code points
14
 * @param postScriptName - PostScript name of the font
15
 * @param fontFileName - Font file name (e.g., 'MyFont.ttf')
16
 * @param fontStyle - Optional React Native TextStyle overrides
17
 * @returns Icon component with getImageSource methods
18
 */
19
function createIconSet<GM extends Record<string, number>>(
20
  glyphMap: GM,
21
  postScriptName: string,
22
  fontFileName: string,
23
  fontStyle?: TextStyle
24
): IconComponent<GM>;
25

26
/**
27
 * Creates an icon component using options object (preferred for dynamic loading)
28
 * @param glyphMap - Object mapping icon names to Unicode code points
29
 * @param options - Configuration object for font and styling
30
 * @returns Icon component with getImageSource methods
31
 */
32
function createIconSet<GM extends Record<string, number>>(
33
  glyphMap: GM,
34
  options: CreateIconSetOptions
35
): IconComponent<GM>;
36

37
interface CreateIconSetOptions {
38
  /** PostScript name of the font family */
39
  postScriptName: string;
40
  /** Font file name including extension */
41
  fontFileName: string;
42
  /** Optional font source for dynamic loading (Expo environments) */
43
  fontSource?: FontSource;
44
  /** Optional React Native TextStyle overrides */
45
  fontStyle?: TextStyle;
46
}
47

48
interface IconComponent<GM extends Record<string, number>> {
49
  /** React component for rendering icons */
50
  (props: IconProps<keyof GM>): JSX.Element;
51
  /** Generate image source asynchronously */
52
  getImageSource(name: keyof GM, size?: number, color?: string): Promise<ImageSource>;
53
  /** Generate image source synchronously */
54
  getImageSourceSync(name: keyof GM, size?: number, color?: string): ImageSource | undefined;
55
}
56

57
interface IconProps<T> {
58
  /** Icon name from the glyph map */
59
  name: T;
60
  /** Icon size in points (default: 12) */
61
  size?: number;
62
  /** Icon color (default: 'black') */
63
  color?: string;
64
  /** Additional React Native Text styles */
65
  style?: TextStyle;
66
  /** Ref forwarding for the underlying Text component */
67
  innerRef?: React.Ref<Text>;
68
  /** Enable font scaling with device accessibility settings */
69
  allowFontScaling?: boolean;
70
}
71

72
type ImageSource = {
73
  /** Data URI or file path to the generated image */
74
  uri: string;
75
  /** Image scale factor for different screen densities */
76
  scale: number;
77
};
78

79
type FontSource = any; // Platform-specific asset source (require() result)
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { createIconSet } from '@react-native-vector-icons/common';
86

87
// Basic usage with separate parameters
88
const myGlyphMap = {
89
  'home': 0xE88A,
90
  'search': 0xE8B6,
91
  'star': 0xE838,
92
};
93

94
const MyIcon = createIconSet(
95
  myGlyphMap,
96
  'MaterialIcons-Regular',
97
  'MaterialIcons-Regular.otf'
98
);
99

100
// Usage in React Native
101
<MyIcon name="home" size={24} color="#4A90E2" />
102

103
// Advanced usage with options (for dynamic loading)
104
const DynamicIcon = createIconSet(myGlyphMap, {
105
  postScriptName: 'MaterialIcons-Regular',
106
  fontFileName: 'MaterialIcons-Regular.otf',
107
  fontSource: require('./fonts/MaterialIcons-Regular.otf'),
108
  fontStyle: { fontWeight: '400' }
109
});
110

111
// Generate image sources
112
const imageSource = await MyIcon.getImageSource('home', 24, '#4A90E2');
113
// imageSource = { uri: 'data:image/png;base64,...', scale: 1 }
114

115
const syncImageSource = MyIcon.getImageSourceSync('star', 20, 'gold');
116
// Works if font is already loaded, returns undefined otherwise
117
```
118

119
### Platform-Specific Font Handling
120

121
The createIconSet function automatically handles platform-specific font loading:
122

123
- **iOS**: Uses PostScript name directly
124
- **Android**: Uses font basename (filename without extension)  
125
- **Windows**: Uses format `/Assets/{fontFileName}#{postScriptName}`
126
- **Web**: Uses PostScript name with proper CSS font-face declarations
127

128
### Dynamic Loading Integration
129

130
When using the options-based signature with `fontSource`, the icon component automatically integrates with dynamic loading:
131

132
```typescript
133
// Dynamic loading will be used if:
134
// 1. fontSource is provided in options
135
// 2. Dynamic loading is enabled (setDynamicLoadingEnabled(true))
136
// 3. Expo modules are available
137

138
const DynamicIcon = createIconSet(glyphMap, {
139
  postScriptName: 'CustomFont',
140
  fontFileName: 'CustomFont.ttf',
141
  fontSource: require('./assets/CustomFont.ttf') // Enables dynamic loading
142
});
143
```
144

145
### Error Handling
146

147
The createIconSet function includes built-in error handling:
148

149
```typescript
150
// Invalid glyph names display as '?' character
151
<MyIcon name="nonexistent-icon" size={20} /> // Renders '?'
152

153
// Missing fonts on platforms show linking errors for native modules
154
// Dynamic loading failures trigger error callbacks if configured
155
```