0
# React Navigation Stack
1

2
React Navigation Stack is a powerful navigation component that provides stack-based navigation for React Native applications, supporting both iOS and Android platforms. It delivers native-feeling navigation experiences with smooth animated transitions, gesture handling, and extensive customization options including custom animations, header styling, and screen configurations.
3

4
## Package Information
5

6
- **Package Name**: @react-navigation/stack
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-navigation/stack`
10

11
## Core Imports
12

13
```typescript
14
import { createStackNavigator } from '@react-navigation/stack';
15
```
16

17
For complete transition control:
18

19
```typescript
20
import {
21
  createStackNavigator,
22
  StackNavigationProp,
23
  StackScreenProps,
24
  CardStyleInterpolators,
25
  HeaderStyleInterpolators,
26
  TransitionPresets,
27
  TransitionSpecs,
28
} from '@react-navigation/stack';
29
```
30

31
## Basic Usage
32

33
```typescript
34
import React from 'react';
35
import { createStackNavigator } from '@react-navigation/stack';
36
import { View, Text, Button } from 'react-native';
37

38
type RootStackParamList = {
39
  Home: undefined;
40
  Details: { itemId: number };
41
};
42

43
const Stack = createStackNavigator<RootStackParamList>();
44

45
function HomeScreen({ navigation }: StackScreenProps<RootStackParamList, 'Home'>) {
46
  return (
47
    <View>
48
      <Text>Home Screen</Text>
49
      <Button
50
        title="Go to Details"
51
        onPress={() => navigation.navigate('Details', { itemId: 42 })}
52
      />
53
    </View>
54
  );
55
}
56

57
function DetailsScreen({ route }: StackScreenProps<RootStackParamList, 'Details'>) {
58
  return (
59
    <View>
60
      <Text>Details Screen</Text>
61
      <Text>Item ID: {route.params.itemId}</Text>
62
    </View>
63
  );
64
}
65

66
export default function App() {
67
  return (
68
    <Stack.Navigator initialRouteName="Home">
69
      <Stack.Screen name="Home" component={HomeScreen} />
70
      <Stack.Screen name="Details" component={DetailsScreen} />
71
    </Stack.Navigator>
72
  );
73
}
74
```
75

76
## Architecture
77

78
React Navigation Stack is built around several key components:
79

80
- **Navigator Factory**: `createStackNavigator` creates stack navigation instances with type safety
81
- **View Components**: `StackView` and `Header` provide the core navigation UI
82
- **Animation System**: Modular interpolators and presets for customizing transitions
83
- **Gesture Handling**: Integration with react-native-gesture-handler for swipe navigation
84
- **Context System**: Provides animation and gesture data to child components
85
- **Type System**: Full TypeScript support with generic parameter lists
86

87
## Capabilities
88

89
### Stack Navigator Creation
90

91
Core navigator factory function for creating stack navigation instances with type-safe parameter lists and screen configuration.
92

93
```typescript { .api }
94
function createStackNavigator<ParamList extends ParamListBase = ParamListBase>(): {
95
  Navigator: React.ComponentType<StackNavigatorProps>;
96
  Screen: React.ComponentType<StackScreenConfig>;
97
  Group: React.ComponentType<StackGroupConfig>;
98
};
99
```
100

101
[Stack Navigation](./stack-navigation.md)
102

103
### Card Animation Styles
104

105
Comprehensive collection of card transition interpolators providing platform-specific animations for screen transitions.
106

107
```typescript { .api }
108
interface CardStyleInterpolators {
109
  forHorizontalIOS: StackCardStyleInterpolator;
110
  forVerticalIOS: StackCardStyleInterpolator;
111
  forModalPresentationIOS: StackCardStyleInterpolator;
112
  forFadeFromBottomAndroid: StackCardStyleInterpolator;
113
  forRevealFromBottomAndroid: StackCardStyleInterpolator;
114
  forScaleFromCenterAndroid: StackCardStyleInterpolator;
115
  forBottomSheetAndroid: StackCardStyleInterpolator;
116
  forFadeFromCenter: StackCardStyleInterpolator;
117
  forNoAnimation: StackCardStyleInterpolator;
118
}
119
```
120

121
[Card Animations](./card-animations.md)
122

123
### Header Animation Styles
124

125
Header transition interpolators for coordinating header animations with screen transitions, including cross-fade and slide effects.
126

127
```typescript { .api }
128
interface HeaderStyleInterpolators {
129
  forUIKit: StackHeaderStyleInterpolator;
130
  forFade: StackHeaderStyleInterpolator;
131
  forSlideLeft: StackHeaderStyleInterpolator;
132
  forSlideRight: StackHeaderStyleInterpolator;
133
  forSlideUp: StackHeaderStyleInterpolator;
134
  forNoAnimation: StackHeaderStyleInterpolator;
135
}
136
```
137

138
[Header Animations](./header-animations.md)
139

140
### Transition Presets
141

142
Complete transition configurations combining card, header, and timing specifications for common platform patterns.
143

144
```typescript { .api }
145
interface TransitionPresets {
146
  SlideFromRightIOS: TransitionPreset;
147
  ModalSlideFromBottomIOS: TransitionPreset;
148
  ModalPresentationIOS: TransitionPreset;
149
  FadeFromBottomAndroid: TransitionPreset;
150
  RevealFromBottomAndroid: TransitionPreset;
151
  ScaleFromCenterAndroid: TransitionPreset;
152
  BottomSheetAndroid: TransitionPreset;
153
  ModalFadeTransition: TransitionPreset;
154
  DefaultTransition: TransitionPreset;
155
  ModalTransition: TransitionPreset;
156
}
157
```
158

159
[Transition Presets](./transition-presets.md)
160

161
### Transition Timing Specifications
162

163
Animation timing and easing configurations that control the duration and feel of screen transitions.
164

165
```typescript { .api }
166
interface TransitionSpecs {
167
  TransitionIOSSpec: TransitionSpec;
168
  FadeInFromBottomAndroidSpec: TransitionSpec;
169
  FadeOutToBottomAndroidSpec: TransitionSpec;
170
  RevealFromBottomAndroidSpec: TransitionSpec;
171
  ScaleFromCenterAndroidSpec: TransitionSpec;
172
  BottomSheetSlideInSpec: TransitionSpec;
173
  BottomSheetSlideOutSpec: TransitionSpec;
174
}
175
```
176

177
[Transition Specs](./transition-specs.md)
178

179
### Animation Hooks and Context
180

181
Utility hooks and context providers for accessing animation values and gesture handlers within screen components.
182

183
```typescript { .api }
184
function useCardAnimation(): StackCardInterpolationProps;
185
function useGestureHandlerRef(): React.Ref<PanGestureHandler>;
186

187
const CardAnimationContext: React.Context<StackCardInterpolationProps | undefined>;
188
const GestureHandlerRefContext: React.Context<React.Ref<PanGestureHandler> | null>;
189
```
190

191
[Animation Utilities](./animation-utilities.md)
192

193
## Types
194

195
### Core Navigation Types
196

197
```typescript { .api }
198
type StackNavigationProp<
199
  ParamList extends ParamListBase,
200
  RouteName extends keyof ParamList = keyof ParamList,
201
  NavigatorID extends string | undefined = undefined
202
> = NavigationProp<
203
  ParamList,
204
  RouteName,
205
  NavigatorID,
206
  StackNavigationState<ParamList>,
207
  StackNavigationOptions,
208
  StackNavigationEventMap
209
> & StackActionHelpers<ParamList>;
210

211
type StackScreenProps<
212
  ParamList extends ParamListBase,
213
  RouteName extends keyof ParamList = keyof ParamList,
214
  NavigatorID extends string | undefined = undefined
215
> = {
216
  navigation: StackNavigationProp<ParamList, RouteName, NavigatorID>;
217
  route: RouteProp<ParamList, RouteName>;
218
};
219

220
interface StackNavigationEventMap {
221
  transitionStart: { data: { closing: boolean } };
222
  transitionEnd: { data: { closing: boolean } };
223
  gestureStart: { data: undefined };
224
  gestureEnd: { data: undefined };
225
  gestureCancel: { data: undefined };
226
}
227
```
228

229
### Animation and Transition Types
230

231
```typescript { .api }
232
interface TransitionPreset {
233
  gestureDirection: GestureDirection;
234
  transitionSpec: {
235
    open: TransitionSpec;
236
    close: TransitionSpec;
237
  };
238
  cardStyleInterpolator: StackCardStyleInterpolator;
239
  headerStyleInterpolator: StackHeaderStyleInterpolator;
240
}
241

242
type TransitionSpec = {
243
  animation: 'spring';
244
  config: Omit<Animated.SpringAnimationConfig, 'toValue' | keyof Animated.AnimationConfig>;
245
} | {
246
  animation: 'timing';
247
  config: Omit<Animated.TimingAnimationConfig, 'toValue' | keyof Animated.AnimationConfig>;
248
};
249

250
type StackCardStyleInterpolator = (
251
  props: StackCardInterpolationProps
252
) => StackCardInterpolatedStyle;
253

254
type StackHeaderStyleInterpolator = (
255
  props: StackHeaderInterpolationProps
256
) => StackHeaderInterpolatedStyle;
257
```
258

259
### Configuration Types
260

261
```typescript { .api }
262
interface StackNavigationOptions extends StackHeaderOptions {
263
  title?: string;
264
  header?: (props: StackHeaderProps) => React.ReactNode;
265
  headerMode?: StackHeaderMode;
266
  headerShown?: boolean;
267
  cardShadowEnabled?: boolean;
268
  cardOverlayEnabled?: boolean;
269
  cardOverlay?: (props: { style: Animated.WithAnimatedValue<StyleProp<ViewStyle>> }) => React.ReactNode;
270
  cardStyle?: StyleProp<ViewStyle>;
271
  presentation?: 'card' | 'modal' | 'transparentModal';
272
  animationEnabled?: boolean;
273
  animationTypeForReplace?: 'push' | 'pop';
274
  gestureEnabled?: boolean;
275
  gestureResponseDistance?: number;
276
  gestureVelocityImpact?: number;
277
  detachPreviousScreen?: boolean;
278
  keyboardHandlingEnabled?: boolean;
279
  freezeOnBlur?: boolean;
280
}
281

282
interface StackNavigationConfig {
283
  detachInactiveScreens?: boolean;
284
}
285

286
interface StackHeaderProps {
287
  layout: Layout;
288
  back?: {
289
    title: string;
290
  };
291
  progress: SceneProgress;
292
  options: StackNavigationOptions;
293
  route: Route<string>;
294
  navigation: StackNavigationProp<ParamListBase>;
295
  styleInterpolator: StackHeaderStyleInterpolator;
296
}
297

298
type StackHeaderMode = 'float' | 'screen';
299
type GestureDirection = 'horizontal' | 'horizontal-inverted' | 'vertical' | 'vertical-inverted';
300
```
301

302
### Animation Interpolation Types
303

304
```typescript { .api }
305
interface StackCardInterpolationProps {
306
  current: {
307
    progress: Animated.AnimatedInterpolation<number>;
308
  };
309
  next?: {
310
    progress: Animated.AnimatedInterpolation<number>;
311
  };
312
  index: number;
313
  closing: Animated.AnimatedInterpolation<0 | 1>;
314
  swiping: Animated.AnimatedInterpolation<0 | 1>;
315
  inverted: Animated.AnimatedInterpolation<-1 | 1>;
316
  layouts: {
317
    screen: Layout;
318
  };
319
  insets: {
320
    top: number;
321
    right: number;
322
    bottom: number;
323
    left: number;
324
  };
325
}
326

327
interface StackCardInterpolatedStyle {
328
  containerStyle?: any;
329
  cardStyle?: any;
330
  overlayStyle?: any;
331
  shadowStyle?: any;
332
}
333

334
interface StackHeaderInterpolationProps {
335
  current: {
336
    progress: Animated.AnimatedInterpolation<number>;
337
  };
338
  next?: {
339
    progress: Animated.AnimatedInterpolation<number>;
340
  };
341
  layouts: {
342
    header: Layout;
343
    screen: Layout;
344
    title?: Layout;
345
    leftLabel?: Layout;
346
  };
347
}
348

349
interface StackHeaderInterpolatedStyle {
350
  leftLabelStyle?: any;
351
  leftButtonStyle?: any;
352
  rightButtonStyle?: any;
353
  titleStyle?: any;
354
  backgroundStyle?: any;
355
}
356
```