0
# Dynamic Font Loading
1

2
Runtime font loading capabilities for Expo environments with automatic fallback handling. This feature allows fonts to be loaded on-demand without requiring them to be bundled into the app.
3

4
## Capabilities
5

6
### Loading State Management
7

8
Control and monitor dynamic font loading behavior.
9

10
```typescript { .api }
11
/**
12
 * Check if dynamic font loading is currently enabled
13
 * @returns true if dynamic loading is active
14
 */
15
function isDynamicLoadingEnabled(): boolean;
16

17
/**
18
 * Check if the current environment supports dynamic font loading
19
 * @returns true if Expo modules are available and compatible
20
 */
21
function isDynamicLoadingSupported(): boolean;
22

23
/**
24
 * Enable or disable dynamic font loading
25
 * @param value - true to enable, false to disable
26
 * @returns true if setting was successful, false if not supported
27
 */
28
function setDynamicLoadingEnabled(value: boolean): boolean;
29

30
/**
31
 * Set a callback function to handle dynamic loading errors
32
 * @param callback - Function called when font loading fails
33
 */
34
function setDynamicLoadingErrorCallback(callback: ErrorCallback): void;
35

36
type ErrorCallback = (args: {
37
  error: Error;
38
  fontFamily: string;
39
  fontSource: FontSource;
40
}) => void;
41
```
42

43
### Internal Loading Interface
44

45
These functions are used internally by icon components but are not typically called directly.
46

47
```typescript { .api }
48
interface DynamicLoader {
49
  /** Check if a font family is already loaded */
50
  isLoaded(fontFamily: string): boolean;
51
  /** Load a font asynchronously from a source */
52
  loadFontAsync(fontFamily: string, fontSource: FontSource): Promise<void>;
53
}
54

55
interface ExpoAssetModule {
56
  downloadAsync(uri: string, hash: string | undefined, type: string): Promise<string>;
57
}
58

59
interface ExpoFontLoaderModule {
60
  getLoadedFonts(): string[];
61
  loadAsync(fontFamilyAlias: string, asset: LoadAsyncAsset): Promise<void>;
62
}
63

64
type LoadAsyncAsset = string | { uri: string; display: string };
65
type FontSource = any; // Platform-specific asset source
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import { 
72
  isDynamicLoadingSupported, 
73
  isDynamicLoadingEnabled,
74
  setDynamicLoadingEnabled,
75
  setDynamicLoadingErrorCallback
76
} from '@react-native-vector-icons/common';
77

78
// Check if dynamic loading is available
79
if (isDynamicLoadingSupported()) {
80
  console.log('Dynamic loading is supported');
81
  
82
  // Enable dynamic loading
83
  const success = setDynamicLoadingEnabled(true);
84
  console.log('Dynamic loading enabled:', success);
85
} else {
86
  console.log('Dynamic loading not supported - using static fonts');
87
}
88

89
// Set up error handling
90
setDynamicLoadingErrorCallback(({ error, fontFamily, fontSource }) => {
91
  console.error(`Failed to load font ${fontFamily}:`, error);
92
  // Could trigger fallback UI or retry logic
93
});
94

95
// Check current state
96
const isEnabled = isDynamicLoadingEnabled();
97
console.log('Dynamic loading is currently:', isEnabled ? 'enabled' : 'disabled');
98
```
99

100
### Integration with Icon Components
101

102
Dynamic loading works automatically with icon components created using `createIconSet` when `fontSource` is provided:
103

104
```typescript
105
import { createIconSet } from '@react-native-vector-icons/common';
106

107
// This icon component will use dynamic loading if enabled
108
const DynamicIcon = createIconSet(glyphMap, {
109
  postScriptName: 'CustomFont',
110
  fontFileName: 'CustomFont.ttf',
111
  fontSource: require('./assets/CustomFont.ttf') // Enables dynamic loading
112
});
113

114
// Component behavior:
115
// 1. Initially renders empty while font loads
116
// 2. Re-renders with icon once font is available
117
// 3. Falls back to error callback if loading fails
118
```
119

120
### Environment Requirements
121

122
Dynamic loading requires specific Expo modules to be available:
123

124
- **ExpoAsset**: For downloading font files (native platforms)
125
- **ExpoFontLoader**: For registering fonts with the system
126
- **Expo SDK**: Version 54 or newer for full compatibility
127

128
### Platform Support
129

130
- **Expo Go**: Not supported (fonts must be pre-bundled)
131
- **Expo Development Build**: Fully supported
132
- **Bare React Native**: Not supported without Expo modules
133
- **Web**: Supported through different loading mechanism
134

135
### Performance Considerations
136

137
```typescript
138
// Dynamic loading adds initial delay for first render
139
// Consider pre-loading critical fonts:
140

141
import { setDynamicLoadingEnabled } from '@react-native-vector-icons/common';
142

143
// Enable early in app lifecycle
144
setDynamicLoadingEnabled(true);
145

146
// Icons will show loading state until fonts are ready
147
// Subsequent renders are instant once fonts are cached
148
```
149

150
### Error Scenarios
151

152
Common failure cases and their handling:
153

154
```typescript
155
setDynamicLoadingErrorCallback(({ error, fontFamily }) => {
156
  if (error.message.includes('Network')) {
157
    // Handle network failures
158
    console.log('Font download failed - using fallback');
159
  } else if (error.message.includes('Expo')) {
160
    // Handle Expo module issues
161
    console.log('Expo modules not properly configured');
162
  }
163
});
164

165
// Automatic fallbacks:
166
// 1. Missing Expo modules -> static loading
167
// 2. Network failures -> error callback + empty icon
168
// 3. Invalid fonts -> error callback + '?' character
169
```