0
# Core Functions
1

2
Core functionality for enabling and configuring react-native-screens. These functions control the fundamental behavior of native screen implementation and performance optimizations.
3

4
## Core Imports
5

6
```typescript
7
import {
8
  enableScreens,
9
  enableFreeze,
10
  screensEnabled,
11
  freezeEnabled
12
} from "react-native-screens";
13
```
14

15
## Capabilities
16

17
### Enable Screens
18

19
Enables or disables the native screen implementation globally. This function should be called early in the app lifecycle, typically in your main index file.
20

21
```typescript { .api }
22
/**
23
 * Enables or disables the native screen implementation
24
 * @param shouldEnableScreens - Whether to enable screens, defaults to true on supported platforms
25
 */
26
function enableScreens(shouldEnableScreens?: boolean): void;
27
```
28

29
**Usage Example:**
30

31
```typescript
32
import { enableScreens } from "react-native-screens";
33

34
// Enable native screens (recommended)
35
enableScreens(true);
36

37
// Disable native screens (fallback to React Native Views)
38
enableScreens(false);
39

40
// Use default behavior (enabled on iOS, Android, Windows)
41
enableScreens();
42
```
43

44
**Platform Support:**
45
- **iOS**: Uses native UIViewController and UINavigationController
46
- **Android**: Uses native Fragment management
47
- **Windows**: Native screen support available
48
- **Web**: Falls back to React Native View implementation
49

50
### Enable Freeze
51

52
Controls the React Freeze functionality for inactive screens. When enabled, inactive screens are suspended to improve performance and reduce memory usage.
53

54
```typescript { .api }
55
/**
56
 * Enables or disables React freeze functionality for inactive screens
57
 * @param shouldEnableReactFreeze - Whether to enable react-freeze, defaults to true
58
 */
59
function enableFreeze(shouldEnableReactFreeze?: boolean): void;
60
```
61

62
**Usage Example:**
63

64
```typescript
65
import { enableFreeze } from "react-native-screens";
66

67
// Enable React Freeze (recommended for performance)
68
enableFreeze(true);
69

70
// Disable React Freeze
71
enableFreeze(false);
72

73
// Use default behavior (enabled)
74
enableFreeze();
75
```
76

77
**Performance Impact:**
78
- **Memory**: Inactive screens use significantly less memory when frozen
79
- **CPU**: Suspended screens don't consume CPU cycles for re-renders
80
- **Battery**: Reduced background processing improves battery life
81
- **Compatibility**: Works with React 18+ concurrent features
82

83
### Check Screens Status
84

85
Returns whether native screens are currently enabled in the application.
86

87
```typescript { .api }
88
/**
89
 * Returns whether screens are currently enabled
90
 * @returns true if native screens are active, false if using fallback
91
 */
92
function screensEnabled(): boolean;
93
```
94

95
**Usage Example:**
96

97
```typescript
98
import { screensEnabled } from "react-native-screens";
99

100
if (screensEnabled()) {
101
  console.log("Using native screen implementation");
102
} else {
103
  console.log("Using React Native View fallback");
104
}
105

106
// Conditional logic based on screen implementation
107
const useNativeGestures = screensEnabled();
108
```
109

110
### Check Freeze Status
111

112
Returns whether React Freeze functionality is currently enabled.
113

114
```typescript { .api }
115
/**
116
 * Returns whether freeze functionality is currently enabled
117
 * @returns true if React Freeze is active for inactive screens
118
 */
119
function freezeEnabled(): boolean;
120
```
121

122
**Usage Example:**
123

124
```typescript
125
import { freezeEnabled } from "react-native-screens";
126

127
if (freezeEnabled()) {
128
  console.log("Inactive screens will be frozen for performance");
129
} else {
130
  console.log("All screens remain active");
131
}
132

133
// Adjust memory usage expectations
134
const expectedMemoryUsage = freezeEnabled() ? "low" : "high";
135
```
136

137
## Configuration Timing
138

139
### App Initialization
140

141
These functions should be called during app initialization, before any screen components are rendered:
142

143
```typescript
144
// index.js or App.tsx
145
import { enableScreens, enableFreeze } from "react-native-screens";
146
import { AppRegistry } from 'react-native';
147
import App from './App';
148

149
// Configure before app starts
150
enableScreens(true);
151
enableFreeze(true);
152

153
AppRegistry.registerComponent('MyApp', () => App);
154
```
155

156
### Conditional Enabling
157

158
Enable screens based on platform or feature detection:
159

160
```typescript
161
import { Platform } from 'react-native';
162
import { enableScreens } from "react-native-screens";
163

164
// Platform-specific enabling
165
if (Platform.OS === 'ios' || Platform.OS === 'android') {
166
  enableScreens(true);
167
} else {
168
  enableScreens(false);
169
}
170
```
171

172
### Development vs Production
173

174
Different configurations for development and production builds:
175

176
```typescript
177
import { enableScreens, enableFreeze } from "react-native-screens";
178

179
if (__DEV__) {
180
  // Development: Enable screens but disable freeze for debugging
181
  enableScreens(true);
182
  enableFreeze(false);
183
} else {
184
  // Production: Enable both for optimal performance
185
  enableScreens(true);
186
  enableFreeze(true);
187
}
188
```
189

190
## Compatibility
191

192
### React Navigation Integration
193

194
When using React Navigation, these functions integrate automatically:
195

196
```typescript
197
// React Navigation v6+ automatically enables screens when installed
198
// Manual enabling is optional but recommended for explicit control
199
import { enableScreens } from "react-native-screens";
200
enableScreens(true);
201
```
202

203
### Legacy Support
204

205
For apps upgrading from older navigation solutions:
206

207
```typescript
208
import { enableScreens, screensEnabled } from "react-native-screens";
209

210
// Gradual migration approach
211
enableScreens(true);
212

213
// Check if migration was successful
214
if (screensEnabled()) {
215
  console.log("Successfully migrated to native screens");
216
} else {
217
  console.log("Fallback to previous implementation");
218
}
219
```
220

221
## Troubleshooting
222

223
### Common Issues
224

225
1. **Screens not enabling**: Ensure the function is called before rendering any screen components
226
2. **Performance degradation**: Check if freeze is disabled when it should be enabled
227
3. **Platform compatibility**: Verify the target platform supports native screens
228

229
### Debugging
230

231
```typescript
232
import { screensEnabled, freezeEnabled } from "react-native-screens";
233

234
// Debug current configuration
235
console.log("Screens enabled:", screensEnabled());
236
console.log("Freeze enabled:", freezeEnabled());
237
```
238

239
### Metro Configuration
240

241
Ensure proper Metro resolver configuration for react-native-screens:
242

243
```javascript
244
// metro.config.js
245
module.exports = {
246
  resolver: {
247
    alias: {
248
      'react-native-screens': require.resolve('react-native-screens'),
249
    },
250
  },
251
};
252
```