0
# Screen Components
1
2
Core components for creating and managing native screen hierarchies. These components provide the foundation for native screen management, transitions, and lifecycle handling.
3
4
## Core Imports
5
6
```typescript
7
import {
8
Screen,
9
ScreenContainer,
10
ScreenStack,
11
ScreenStackItem,
12
FullWindowOverlay,
13
ScreenFooter,
14
ScreenContentWrapper
15
} from "react-native-screens";
16
```
17
18
## Capabilities
19
20
### Screen
21
22
The main screen component that wraps screen content and provides native screen functionality. Each Screen represents a single native screen with its own lifecycle and navigation properties.
23
24
```typescript { .api }
25
/**
26
* Main screen component providing native screen functionality
27
*/
28
function Screen(props: ScreenProps): JSX.Element;
29
30
interface ScreenProps {
31
/** Screen active state (0 = inactive, 1 = active, or animated value) */
32
active?: 0 | 1 | Animated.AnimatedInterpolation<number>;
33
34
/** How the screen should be presented in the stack */
35
stackPresentation?: StackPresentationTypes;
36
37
/** Transition animation type */
38
stackAnimation?: StackAnimationTypes;
39
40
/** Whether dismiss gestures are enabled */
41
gestureEnabled?: boolean;
42
43
/** Status bar style for this screen */
44
statusBarStyle?: 'inverted' | 'auto' | 'light' | 'dark';
45
46
/** Whether the status bar is hidden */
47
statusBarHidden?: boolean;
48
49
/** Status bar animation when hidden/shown */
50
statusBarAnimation?: 'none' | 'fade' | 'slide';
51
52
/** Screen orientation preferences */
53
screenOrientation?: ScreenOrientationTypes;
54
55
/** Navigation bar color (Android) */
56
navigationBarColor?: ColorValue;
57
58
/** Whether navigation bar is hidden (Android) */
59
navigationBarHidden?: boolean;
60
61
/** Navigation bar style (Android) */
62
navigationBarStyle?: 'light' | 'dark';
63
64
/** Native stack presentation style */
65
nativeBackButtonDismissalEnabled?: boolean;
66
67
/** Whether swipe-to-dismiss is enabled */
68
swipeDirection?: 'horizontal' | 'vertical';
69
70
/** Full screen swipe area */
71
fullScreenSwipeEnabled?: boolean;
72
73
/** Custom gesture response distances */
74
gestureResponseDistance?: GestureResponseDistanceType;
75
76
/** Whether screen prevents auto-dismiss */
77
preventNativeDismiss?: boolean;
78
79
/** Callback when screen appears */
80
onAppear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
81
82
/** Callback when screen disappears */
83
onDisappear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
84
85
/** Callback when screen will appear */
86
onWillAppear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
87
88
/** Callback when screen will disappear */
89
onWillDisappear?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
90
91
/** Callback when dismiss gesture starts */
92
onDismissed?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
93
94
/** Callback for header height changes */
95
onHeaderHeightChange?: (event: NativeSyntheticEvent<HeaderHeightChangeEventType>) => void;
96
97
/** Callback for transition progress updates */
98
onTransitionProgress?: (event: NativeSyntheticEvent<TransitionProgressEventType>) => void;
99
100
/** Sheet presentation detents (iOS) */
101
sheetAllowedDetents?: (number | 'medium' | 'large' | 'all')[] | number[];
102
103
/** Sheet corner radius (iOS) */
104
sheetCornerRadius?: number;
105
106
/** Whether sheet grabs are visible (iOS) */
107
sheetGrabberVisible?: boolean;
108
109
/** Sheet largest undimmed detent identifier (iOS) */
110
sheetLargestUndimmedDetentIdentifier?: number | 'medium' | 'large';
111
112
/** Whether sheet expands on scroll (iOS) */
113
sheetExpandsWhenScrolledToEdge?: boolean;
114
115
/** Auto keyboard dismiss mode */
116
autoKeyboardInsets?: boolean;
117
118
/** Keyboard handling mode */
119
keyboardHandlingEnabled?: boolean;
120
121
/** Home indicator auto-hidden */
122
homeIndicatorHidden?: boolean;
123
}
124
```
125
126
**Usage Example:**
127
128
```typescript
129
import React from 'react';
130
import { Screen } from 'react-native-screens';
131
import { View, Text } from 'react-native';
132
133
function MyScreen() {
134
return (
135
<Screen
136
active={1}
137
stackPresentation="push"
138
stackAnimation="slide_from_right"
139
gestureEnabled={true}
140
statusBarStyle="dark"
141
onAppear={() => console.log('Screen appeared')}
142
onWillDisappear={() => console.log('Screen will disappear')}
143
>
144
<View>
145
<Text>Screen Content</Text>
146
</View>
147
</Screen>
148
);
149
}
150
```
151
152
### InnerScreen
153
154
Internal screen component that provides the core native screen functionality. This is primarily used by other screen components and navigation libraries internally, but can be accessed directly for advanced use cases.
155
156
```typescript { .api }
157
/**
158
* Internal screen component providing core native screen functionality
159
*/
160
const InnerScreen: React.ForwardRefExoticComponent<ScreenProps & React.RefAttributes<View>>;
161
```
162
163
**Usage Example:**
164
165
```typescript
166
import React from 'react';
167
import { InnerScreen } from 'react-native-screens';
168
import { View, Text } from 'react-native';
169
170
function CustomScreenWrapper({ children, ...screenProps }) {
171
return (
172
<InnerScreen {...screenProps}>
173
<View style={{ flex: 1 }}>
174
{children}
175
</View>
176
</InnerScreen>
177
);
178
}
179
```
180
181
**Note:** `InnerScreen` is typically used internally by other components and navigation libraries. For most use cases, use the `Screen` component instead.
182
183
### ScreenContainer
184
185
Container component that manages multiple screen instances. Provides optimization for single-screen navigators and controls the overall screen management behavior.
186
187
```typescript { .api }
188
/**
189
* Container component for managing multiple screen instances
190
*/
191
function ScreenContainer(props: ScreenContainerProps): JSX.Element;
192
193
interface ScreenContainerProps extends ViewProps {
194
/** Whether to use screens functionality */
195
enabled?: boolean;
196
197
/** Optimization for single-screen navigators */
198
hasTwoStates?: boolean;
199
}
200
```
201
202
**Usage Example:**
203
204
```typescript
205
import React from 'react';
206
import { ScreenContainer, Screen } from 'react-native-screens';
207
208
function NavigationContainer({ children }) {
209
return (
210
<ScreenContainer enabled={true} hasTwoStates={false}>
211
{children}
212
</ScreenContainer>
213
);
214
}
215
```
216
217
### ScreenStack
218
219
Stack container for managing screen transitions with native stack behavior. Provides platform-appropriate navigation stack functionality.
220
221
```typescript { .api }
222
/**
223
* Stack container for managing screen transitions
224
*/
225
function ScreenStack(props: ScreenStackProps): JSX.Element;
226
227
interface ScreenStackProps extends ViewProps, GestureProps {
228
/** Custom gesture handling */
229
children?: React.ReactNode;
230
}
231
232
interface GestureProps {
233
/** Go back gesture types */
234
goBackGesture?: GoBackGesture;
235
236
/** Custom animated screen transitions */
237
customAnimationOnSwipe?: boolean;
238
239
/** Full screen swipe enabled */
240
fullScreenSwipeEnabled?: boolean;
241
242
/** Animated screen transition configuration */
243
screenTransition?: AnimatedScreenTransition;
244
}
245
```
246
247
**Usage Example:**
248
249
```typescript
250
import React from 'react';
251
import { ScreenStack, Screen } from 'react-native-screens';
252
253
function NavigationStack({ routes, activeRoute }) {
254
return (
255
<ScreenStack>
256
{routes.map((route, index) => (
257
<Screen
258
key={route.key}
259
active={index === activeRoute ? 1 : 0}
260
stackPresentation="push"
261
>
262
{route.component}
263
</Screen>
264
))}
265
</ScreenStack>
266
);
267
}
268
```
269
270
### ScreenStackItem
271
272
Individual item within a screen stack that wraps screen content with stack-specific behavior and header configuration.
273
274
```typescript { .api }
275
/**
276
* Individual item within a screen stack with header configuration
277
*/
278
function ScreenStackItem(props: ScreenStackItemProps): JSX.Element;
279
280
interface ScreenStackItemProps extends Omit<ScreenProps, 'enabled' | 'isNativeStack' | 'hasLargeHeader'> {
281
/** Unique identifier for the screen */
282
screenId: string;
283
284
/** Header configuration for this screen */
285
headerConfig?: ScreenStackHeaderConfigProps;
286
287
/** Custom content styling */
288
contentStyle?: StyleProp<ViewStyle>;
289
290
/** Footer component for form sheet presentations */
291
unstable_sheetFooter?: () => React.ReactNode;
292
}
293
```
294
295
**Usage Example:**
296
297
```typescript
298
import React from 'react';
299
import { ScreenStack, ScreenStackItem } from 'react-native-screens';
300
301
function StackNavigator() {
302
return (
303
<ScreenStack>
304
<ScreenStackItem
305
screenId="home"
306
headerConfig={{
307
title: "Home Screen",
308
backgroundColor: "#007AFF",
309
color: "white"
310
}}
311
contentStyle={{ backgroundColor: "#f5f5f5" }}
312
stackPresentation="push"
313
activityState={1}
314
>
315
{/* Screen content */}
316
</ScreenStackItem>
317
</ScreenStack>
318
);
319
}
320
```
321
322
### FullWindowOverlay
323
324
Component for creating full-window overlay screens that render above all other content, including system UI elements.
325
326
```typescript { .api }
327
/**
328
* Component for creating full-window overlay screens
329
*/
330
function FullWindowOverlay(props: ViewProps): JSX.Element;
331
```
332
333
**Usage Example:**
334
335
```typescript
336
import React from 'react';
337
import { FullWindowOverlay } from 'react-native-screens';
338
import { View, Text } from 'react-native';
339
340
function OverlayScreen({ visible, children }) {
341
if (!visible) return null;
342
343
return (
344
<FullWindowOverlay>
345
<View style={{ flex: 1, backgroundColor: 'rgba(0,0,0,0.5)' }}>
346
{children}
347
</View>
348
</FullWindowOverlay>
349
);
350
}
351
```
352
353
### ScreenFooter
354
355
Footer component specifically designed for use with formSheet presentation style on iOS.
356
357
```typescript { .api }
358
/**
359
* Footer component for use with formSheet presentation style
360
*/
361
function ScreenFooter(props: ViewProps): JSX.Element;
362
```
363
364
**Usage Example:**
365
366
```typescript
367
import React from 'react';
368
import { Screen, ScreenFooter } from 'react-native-screens';
369
import { View, Text, Button } from 'react-native';
370
371
function FormSheetScreen() {
372
return (
373
<Screen stackPresentation="formSheet">
374
<View style={{ flex: 1 }}>
375
<Text>Form content</Text>
376
</View>
377
<ScreenFooter>
378
<Button title="Save" onPress={() => {}} />
379
</ScreenFooter>
380
</Screen>
381
);
382
}
383
```
384
385
### ScreenContentWrapper
386
387
Wrapper component for screen content that provides additional layout and behavior management.
388
389
```typescript { .api }
390
/**
391
* Wrapper component for screen content
392
*/
393
function ScreenContentWrapper(props: ViewProps): JSX.Element;
394
```
395
396
**Usage Example:**
397
398
```typescript
399
import React from 'react';
400
import { Screen, ScreenContentWrapper } from 'react-native-screens';
401
import { ScrollView } from 'react-native';
402
403
function ScrollableScreen({ children }) {
404
return (
405
<Screen>
406
<ScreenContentWrapper>
407
<ScrollView>
408
{children}
409
</ScrollView>
410
</ScreenContentWrapper>
411
</Screen>
412
);
413
}
414
```
415
416
### SearchBar
417
418
Native search bar component for iOS and Android that integrates with the navigation header or can be used standalone.
419
420
```typescript { .api }
421
/**
422
* Native search bar component with platform-specific styling
423
*/
424
function SearchBar(props: SearchBarProps): JSX.Element;
425
426
interface SearchBarProps {
427
/** Reference for imperative control */
428
ref?: React.RefObject<SearchBarCommands>;
429
430
/** Auto-capitalization behavior */
431
autoCapitalize?: 'none' | 'words' | 'sentences' | 'characters';
432
433
/** Automatically focus on mount (Android) */
434
autoFocus?: boolean;
435
436
/** Search field background color */
437
barTintColor?: ColorValue;
438
439
/** Cursor and cancel button color (iOS) */
440
tintColor?: ColorValue;
441
442
/** Custom cancel button text (iOS, deprecated) */
443
cancelButtonText?: string;
444
445
/** Whether back button closes search (Android) */
446
disableBackButtonOverride?: boolean;
447
448
/** Hide navigation bar during search (iOS) */
449
hideNavigationBar?: boolean;
450
451
/** Hide search bar when scrolling (iOS) */
452
hideWhenScrolling?: boolean;
453
454
/** Input type for keyboard (Android) */
455
inputType?: 'text' | 'phone' | 'number' | 'email';
456
457
/** Whether to obscure background content */
458
obscureBackground?: boolean;
459
460
/** Search bar placement position (iOS) */
461
placement?: SearchBarPlacement;
462
463
/** Allow toolbar integration (iOS) */
464
allowToolbarIntegration?: boolean;
465
466
/** Placeholder text */
467
placeholder?: string;
468
469
/** Search field text color */
470
textColor?: ColorValue;
471
472
/** Search hint text color (Android) */
473
hintTextColor?: ColorValue;
474
475
/** Header icon color (Android) */
476
headerIconColor?: ColorValue;
477
478
/** Show search hint icon when focused (Android) */
479
shouldShowHintSearchIcon?: boolean;
480
481
/** Callback when search loses focus */
482
onBlur?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
483
484
/** Callback when cancel button pressed (iOS) */
485
onCancelButtonPress?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
486
487
/** Callback when text changes */
488
onChangeText?: (event: NativeSyntheticEvent<TextInputFocusEventData>) => void;
489
490
/** Callback when search closes (Android) */
491
onClose?: () => void;
492
493
/** Callback when search gains focus */
494
onFocus?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
495
496
/** Callback when search opens (Android) */
497
onOpen?: () => void;
498
499
/** Callback when search button pressed */
500
onSearchButtonPress?: (event: NativeSyntheticEvent<TextInputFocusEventData>) => void;
501
}
502
503
interface SearchBarCommands {
504
/** Focus the search bar */
505
focus(): void;
506
507
/** Remove focus from search bar */
508
blur(): void;
509
510
/** Clear search text */
511
clearText(): void;
512
513
/** Toggle cancel button visibility (iOS) */
514
toggleCancelButton(show: boolean): void;
515
516
/** Set search text programmatically */
517
setText(text: string): void;
518
519
/** Cancel search operation */
520
cancelSearch(): void;
521
}
522
523
type SearchBarPlacement =
524
| 'automatic' // Automatic placement
525
| 'inline' // Inline (deprecated, use integrated)
526
| 'stacked' // Below other content
527
| 'integrated' // Trailing edge (iOS 16+)
528
| 'integratedButton' // Always button form (iOS 16+)
529
| 'integratedCentered'; // Centered on iPad (iOS 16+)
530
```
531
532
**Usage Example:**
533
534
```typescript
535
import React, { useRef } from 'react';
536
import { SearchBar, SearchBarCommands } from 'react-native-screens';
537
538
function SearchScreen() {
539
const searchRef = useRef<SearchBarCommands>(null);
540
541
const handleSearchPress = () => {
542
searchRef.current?.focus();
543
};
544
545
const handleClearPress = () => {
546
searchRef.current?.clearText();
547
};
548
549
return (
550
<SearchBar
551
ref={searchRef}
552
placeholder="Search items..."
553
placement="stacked"
554
hideWhenScrolling={false}
555
autoCapitalize="none"
556
onChangeText={(event) => {
557
console.log('Search text:', event.nativeEvent.text);
558
}}
559
onSearchButtonPress={(event) => {
560
console.log('Search submitted:', event.nativeEvent.text);
561
}}
562
onFocus={() => console.log('Search focused')}
563
onBlur={() => console.log('Search blurred')}
564
/>
565
);
566
}
567
```
568
569
**Platform-Specific Usage:**
570
571
```typescript
572
import { Platform } from 'react-native';
573
import { SearchBar, isSearchBarAvailableForCurrentPlatform } from 'react-native-screens';
574
575
function ConditionalSearchBar() {
576
if (!isSearchBarAvailableForCurrentPlatform) {
577
return <TextInput placeholder="Search..." />; // Fallback
578
}
579
580
return (
581
<SearchBar
582
placeholder="Search..."
583
// iOS-specific props
584
placement={Platform.OS === 'ios' ? 'integrated' : undefined}
585
hideNavigationBar={Platform.OS === 'ios'}
586
tintColor={Platform.OS === 'ios' ? '#007AFF' : undefined}
587
588
// Android-specific props
589
inputType={Platform.OS === 'android' ? 'text' : undefined}
590
disableBackButtonOverride={Platform.OS === 'android' ? false : undefined}
591
headerIconColor={Platform.OS === 'android' ? '#666' : undefined}
592
/>
593
);
594
}
595
```
596
597
## Types
598
599
### Stack Presentation Types
600
601
```typescript { .api }
602
type StackPresentationTypes =
603
| 'push' // Standard push navigation
604
| 'modal' // Modal presentation
605
| 'transparentModal' // Transparent modal
606
| 'containedModal' // Contained modal (iOS)
607
| 'containedTransparentModal' // Contained transparent modal (iOS)
608
| 'fullScreenModal' // Full screen modal
609
| 'formSheet' // Form sheet (iOS)
610
| 'pageSheet'; // Page sheet (iOS)
611
```
612
613
### Stack Animation Types
614
615
```typescript { .api }
616
type StackAnimationTypes =
617
| 'default' // Platform default animation
618
| 'fade' // Fade in/out
619
| 'fade_from_bottom' // Fade from bottom
620
| 'flip' // Flip animation
621
| 'none' // No animation
622
| 'simple_push' // Simple push
623
| 'slide_from_bottom' // Slide from bottom
624
| 'slide_from_right' // Slide from right
625
| 'slide_from_left' // Slide from left
626
| 'ios_from_right' // iOS-style from right
627
| 'ios_from_left'; // iOS-style from left
628
```
629
630
### Screen Orientation Types
631
632
```typescript { .api }
633
type ScreenOrientationTypes =
634
| 'default' // Use app default
635
| 'all' // All orientations
636
| 'portrait' // Portrait orientations
637
| 'portrait_up' // Portrait up only
638
| 'portrait_down' // Portrait down only
639
| 'landscape' // Landscape orientations
640
| 'landscape_left' // Landscape left
641
| 'landscape_right'; // Landscape right
642
```
643
644
### Event Types
645
646
```typescript { .api }
647
interface HeaderHeightChangeEventType {
648
headerHeight: number;
649
}
650
651
interface TransitionProgressEventType {
652
progress: number;
653
closing: number;
654
goingForward: number;
655
}
656
657
interface GestureResponseDistanceType {
658
start?: number;
659
end?: number;
660
top?: number;
661
bottom?: number;
662
}
663
```
664
665
### Gesture Types
666
667
```typescript { .api }
668
type GoBackGesture =
669
| 'swipeRight'
670
| 'swipeLeft'
671
| 'swipeUp'
672
| 'swipeDown'
673
| 'verticalSwipe'
674
| 'horizontalSwipe'
675
| 'twoDimensionalSwipe';
676
677
interface AnimatedScreenTransition {
678
topScreenFrame?: {
679
x: number;
680
y: number;
681
width: number;
682
height: number;
683
};
684
belowTopScreenFrame?: {
685
x: number;
686
y: number;
687
width: number;
688
height: number;
689
};
690
}
691
```
692
693
## Platform Considerations
694
695
### iOS Specific Features
696
- Form sheet and page sheet presentations
697
- Large title support
698
- Sheet detents and corner radius
699
- Home indicator control
700
- Visual effect backgrounds
701
702
### Android Specific Features
703
- Navigation bar styling
704
- Edge-to-edge support
705
- Hardware back button integration
706
- Fragment lifecycle management
707
- Material design transitions
708
709
### Performance Optimization
710
- Use `hasTwoStates={true}` for simple navigators
711
- Enable `gestureEnabled={false}` for non-dismissible screens
712
- Implement `onTransitionProgress` for custom animations
713
- Use appropriate `stackAnimation` for smooth transitions