0
# React Native Screens
1

2
React Native Screens provides native navigation primitives for React Native applications, offering superior performance through native screen management. It enables true native screens instead of plain React Native Views, leading to better memory management, improved transition performance, and seamless integration with platform navigation patterns.
3

4
## Package Information
5

6
- **Package Name**: react-native-screens
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-screens`
10

11
## Core Imports
12

13
ESM:
14
```typescript
15
import {
16
  enableScreens,
17
  Screen,
18
  InnerScreen,
19
  ScreenStack,
20
  ScreenStackItem,
21
  ScreenContainer,
22
  SearchBar,
23
  ScreenStackHeaderConfig
24
} from "react-native-screens";
25
```
26

27
CommonJS:
28
```javascript
29
const {
30
  enableScreens,
31
  Screen,
32
  InnerScreen,
33
  ScreenStack,
34
  ScreenStackItem,
35
  ScreenContainer,
36
  SearchBar,
37
  ScreenStackHeaderConfig
38
} = require("react-native-screens");
39
```
40

41
## Basic Usage
42

43
```typescript
44
import React from 'react';
45
import { View, Text } from 'react-native';
46
import {
47
  enableScreens,
48
  Screen,
49
  ScreenStack,
50
  ScreenStackHeaderConfig
51
} from 'react-native-screens';
52

53
// Enable native screens (typically done in index.js)
54
enableScreens();
55

56
function App() {
57
  return (
58
    <ScreenStack>
59
      <Screen active={1}>
60
        <ScreenStackHeaderConfig title="Home" />
61
        <View>
62
          <Text>Home Screen Content</Text>
63
        </View>
64
      </Screen>
65
    </ScreenStack>
66
  );
67
}
68
```
69

70
## Architecture
71

72
React Native Screens is built around several key architectural concepts:
73

74
- **Native Screen Management**: Each `Screen` component represents a true native screen rather than a React Native View
75
- **Screen Stacks**: `ScreenStack` provides native navigation stack functionality with platform-appropriate transitions
76
- **Lifecycle Integration**: Automatic screen lifecycle management with React's component lifecycle and native navigation events  
77
- **Performance Optimization**: Built-in support for React Freeze to suspend inactive screens and reduce memory usage
78
- **Platform Integration**: Deep integration with iOS UINavigationController and Android Fragment management
79
- **Modular Design**: Core components, utilities, and experimental features are organized into logical capability areas
80

81
## Capabilities
82

83
### Core Functions
84

85
Essential functions for enabling and configuring the native screens functionality.
86

87
```typescript { .api }
88
function enableScreens(shouldEnableScreens?: boolean): void;
89
function enableFreeze(shouldEnableReactFreeze?: boolean): void;
90
function screensEnabled(): boolean;
91
function freezeEnabled(): boolean;
92
```
93

94
[Core Functions](./core-functions.md)
95

96
### Screen Components
97

98
Main components for creating and managing native screen hierarchies.
99

100
```typescript { .api }
101
function Screen(props: ScreenProps): JSX.Element;
102
function InnerScreen(props: ScreenProps): JSX.Element;
103
function ScreenContainer(props: ScreenContainerProps): JSX.Element;
104
function ScreenStack(props: ScreenStackProps): JSX.Element;
105
function ScreenStackItem(props: ScreenStackItemProps): JSX.Element;
106
function FullWindowOverlay(props: ViewProps): JSX.Element;
107
function ScreenFooter(props: ViewProps): JSX.Element;
108
function ScreenContentWrapper(props: ViewProps): JSX.Element;
109
function SearchBar(props: SearchBarProps): JSX.Element;
110
```
111

112
[Screen Components](./screen-components.md)
113

114
### Header Components
115

116
Components for configuring native navigation headers with platform-specific styling.
117

118
```typescript { .api }
119
function ScreenStackHeaderConfig(props: ScreenStackHeaderConfigProps): JSX.Element;
120
function ScreenStackHeaderLeftView(props: ViewProps): JSX.Element;
121
function ScreenStackHeaderCenterView(props: ViewProps): JSX.Element;
122
function ScreenStackHeaderRightView(props: ViewProps): JSX.Element;
123
function ScreenStackHeaderBackButtonImage(props: ViewProps): JSX.Element;
124
```
125

126
[Header Components](./header-components.md)
127

128
### Navigation Utilities
129

130
Utility functions, hooks, and configuration objects for navigation behavior.
131

132
```typescript { .api }
133
const isSearchBarAvailableForCurrentPlatform: boolean;
134
function executeNativeBackPress(): boolean;
135
function useTransitionProgress(): TransitionProgressContext;
136
```
137

138
[Navigation Utilities](./navigation-utilities.md)
139

140
### Experimental Features
141

142
Beta and experimental components including bottom tabs, split views, and advanced screen hosting.
143

144
```typescript { .api }
145
function BottomTabs(props: BottomTabsProps): JSX.Element;
146
function BottomTabsScreen(props: BottomTabsScreenProps): JSX.Element;
147
function SplitViewHost(props: SplitViewHostProps): JSX.Element;
148
function SplitViewScreen(props: SplitViewScreenProps): JSX.Element;
149
```
150

151
[Experimental Features](./experimental-features.md)
152

153
### Types and Interfaces
154

155
Comprehensive TypeScript definitions for all components, props, and configuration options.
156

157
```typescript { .api }
158
interface ScreenProps {
159
  active?: 0 | 1 | Animated.AnimatedInterpolation<number>;
160
  stackPresentation?: StackPresentationTypes;
161
  stackAnimation?: StackAnimationTypes;
162
  gestureEnabled?: boolean;
163
  statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
164
  // ... extensive additional properties
165
}
166

167
type StackPresentationTypes = 
168
  | 'push' 
169
  | 'modal' 
170
  | 'transparentModal' 
171
  | 'containedModal' 
172
  | 'containedTransparentModal' 
173
  | 'fullScreenModal' 
174
  | 'formSheet' 
175
  | 'pageSheet';
176

177
type StackAnimationTypes = 
178
  | 'default' 
179
  | 'fade' 
180
  | 'fade_from_bottom' 
181
  | 'flip' 
182
  | 'none' 
183
  | 'simple_push' 
184
  | 'slide_from_bottom' 
185
  | 'slide_from_right' 
186
  | 'slide_from_left'
187
  | 'ios_from_right' 
188
  | 'ios_from_left';
189
```
190

191
[Types and Interfaces](./types-interfaces.md)
192

193
## Platform Support
194

195
### iOS Features
196
- Large title navigation bars with iOS 11+ styling
197
- Native search bar integration with UISearchController
198
- Form sheet and page sheet presentation styles  
199
- Visual effect blur backgrounds
200
- SF Symbols icon support
201
- Split view layouts for iPad
202
- Native swipe gestures and interactive transitions
203

204
### Android Features
205
- Material Design navigation patterns
206
- Edge-to-edge display support
207
- Hardware back button integration
208
- Fragment-based screen management
209
- Navigation bar configuration
210
- Android-specific transition animations
211

212
### Cross-platform Features
213
- React component lifecycle integration
214
- Screen orientation control
215
- Status bar styling
216
- Modal presentations
217
- Stack navigation patterns
218
- React Freeze performance optimization
219

220
## Migration and Integration
221

222
React Native Screens is designed to work seamlessly with popular navigation libraries:
223

224
- **React Navigation**: Full integration as the native screen implementation
225
- **React Native Navigation**: Alternative native navigation solution
226
- **Custom Solutions**: Direct usage for building custom navigation systems
227

228
For applications upgrading from React Navigation v5 or earlier, enable native screens by calling `enableScreens()` early in your app initialization. For newer React Navigation versions, native screens are enabled by default when this package is installed.
229

230
## Performance Considerations
231

232
- **Memory Management**: Native screens automatically manage memory more efficiently than JavaScript-based screen implementations
233
- **React Freeze**: Inactive screens can be suspended to reduce CPU and memory usage
234
- **Native Transitions**: Hardware-accelerated transitions provide 60fps performance
235
- **Platform Optimization**: Each platform uses its native navigation primitives for optimal performance
236

237
## Configuration Flags
238

239
```typescript { .api }
240
interface CompatibilityFlags {
241
  isNewBackTitleImplementation: boolean;
242
  usesHeaderFlexboxImplementation: boolean;
243
}
244

245
interface FeatureFlags {
246
  experiment: {
247
    controlledBottomTabs: boolean;
248
  };
249
  stable: {};
250
}
251

252
const compatibilityFlags: CompatibilityFlags;
253
const featureFlags: FeatureFlags;
254
```
255

256
These flags enable downstream navigation libraries to detect feature availability and maintain backward compatibility across different versions of react-native-screens.