0
# React Navigation Native Stack
1

2
React Navigation Native Stack provides a native stack navigator for React Native applications that uses react-native-screens under the hood to deliver optimal performance by leveraging native navigation primitives. It offers screen management capabilities with smooth transitions, gesture-based navigation, and proper integration with the native navigation stack on both iOS and Android platforms.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  createNativeStackNavigator, 
16
  NativeStackView, 
17
  useAnimatedHeaderHeight,
18
  type NativeStackHeaderLeftProps,
19
  type NativeStackHeaderProps,
20
  type NativeStackHeaderRightProps,
21
  type NativeStackNavigationEventMap,
22
  type NativeStackNavigationOptions,
23
  type NativeStackNavigationProp,
24
  type NativeStackNavigatorProps,
25
  type NativeStackOptionsArgs,
26
  type NativeStackScreenProps,
27
  type NativeStackDescriptor,
28
  type NativeStackDescriptorMap
29
} from "@react-navigation/native-stack";
30
```
31

32
For CommonJS:
33

34
```javascript
35
const { 
36
  createNativeStackNavigator, 
37
  NativeStackView, 
38
  useAnimatedHeaderHeight 
39
} = require("@react-navigation/native-stack");
40
```
41

42
## Basic Usage
43

44
```typescript
45
import { createNativeStackNavigator } from "@react-navigation/native-stack";
46
import { NavigationContainer } from "@react-navigation/native";
47

48
type RootStackParamList = {
49
  Home: undefined;
50
  Details: { itemId: number };
51
};
52

53
const Stack = createNativeStackNavigator<RootStackParamList>();
54

55
function App() {
56
  return (
57
    <NavigationContainer>
58
      <Stack.Navigator initialRouteName="Home">
59
        <Stack.Screen name="Home" component={HomeScreen} />
60
        <Stack.Screen 
61
          name="Details" 
62
          component={DetailsScreen}
63
          options={{ title: "Item Details" }}
64
        />
65
      </Stack.Navigator>
66
    </NavigationContainer>
67
  );
68
}
69
```
70

71
## Architecture
72

73
React Navigation Native Stack is built around several key components:
74

75
- **Native Stack Navigator**: Core navigation component using native platform primitives
76
- **Screen Management**: Handles screen lifecycle, transitions, and gesture interactions
77
- **Header System**: Flexible header configuration with platform-specific adaptations
78
- **Type Safety**: Full TypeScript integration with parameter list type checking
79
- **Performance Optimization**: Leverages react-native-screens for native performance
80

81
## Capabilities
82

83
### Navigator Creation
84

85
Core functionality for creating and configuring native stack navigators with type safety.
86

87
```typescript { .api }
88
function createNativeStackNavigator<
89
  ParamList extends ParamListBase,
90
  NavigatorID extends string | undefined = undefined
91
>(config?: StaticConfig): TypedNavigator<NavigatorTypeBag, StaticConfig>;
92
```
93

94
[Navigator Creation](./navigator-creation.md)
95

96
### Native Stack View
97

98
Low-level view component that renders the native stack interface, typically used internally by the navigator but can be customized for advanced use cases.
99

100
```typescript { .api }
101
function NativeStackView(props: {
102
  state: StackNavigationState<ParamListBase>;
103
  navigation: NativeStackNavigationHelpers;
104
  descriptors: NativeStackDescriptorMap;
105
  describe: (route: RouteProp<ParamListBase>, placeholder: boolean) => NativeStackDescriptor;
106
}): React.ReactElement;
107
```
108

109
### Screen Configuration
110

111
Comprehensive screen options for headers, animations, presentations, and platform-specific behaviors.
112

113
```typescript { .api }
114
interface NativeStackNavigationOptions {
115
  title?: string;
116
  headerShown?: boolean;
117
  presentation?: 'card' | 'modal' | 'transparentModal' | 'containedModal' | 'containedTransparentModal' | 'fullScreenModal' | 'formSheet';
118
  animation?: 'default' | 'fade' | 'fade_from_bottom' | 'flip' | 'simple_push' | 'slide_from_bottom' | 'slide_from_right' | 'slide_from_left' | 'ios_from_right' | 'ios_from_left' | 'none';
119
  // ... extensive additional options
120
}
121
```
122

123
[Screen Configuration](./screen-configuration.md)
124

125
### Navigation Props and Hooks
126

127
Navigation properties, screen props, and utility hooks for accessing navigation state and header information.
128

129
```typescript { .api }
130
type NativeStackScreenProps<
131
  ParamList extends ParamListBase,
132
  RouteName extends keyof ParamList = string
133
> = {
134
  navigation: NativeStackNavigationProp<ParamList, RouteName>;
135
  route: RouteProp<ParamList, RouteName>;
136
};
137

138
function useAnimatedHeaderHeight(): Animated.AnimatedInterpolation<number>;
139
```
140

141
[Navigation Props and Hooks](./navigation-props-hooks.md)
142

143
## Core Types
144

145
```typescript { .api }
146
type ParamListBase = Record<string, object | undefined>;
147

148
interface NativeStackNavigationEventMap {
149
  transitionStart: { data: { closing: boolean } };
150
  transitionEnd: { data: { closing: boolean } };
151
  gestureCancel: { data: undefined };
152
  sheetDetentChange: { data: { index: number; stable: boolean } };
153
}
154

155
type NativeStackNavigationProp<
156
  ParamList extends ParamListBase,
157
  RouteName extends keyof ParamList = string,
158
  NavigatorID extends string | undefined = undefined
159
> = NavigationProp<
160
  ParamList,
161
  RouteName,
162
  NavigatorID,
163
  StackNavigationState<ParamList>,
164
  NativeStackNavigationOptions,
165
  NativeStackNavigationEventMap
166
> & StackActionHelpers<ParamList>;
167

168
interface NativeStackHeaderProps {
169
  back?: { title: string | undefined; href: string | undefined };
170
  options: NativeStackNavigationOptions;
171
  route: Route<string>;
172
  navigation: NativeStackNavigationProp<ParamListBase>;
173
}
174

175
interface NativeStackHeaderLeftProps {
176
  tintColor?: string;
177
  canGoBack?: boolean;
178
  label?: string;
179
  href?: string;
180
}
181

182
interface NativeStackHeaderRightProps {
183
  tintColor?: string;
184
  canGoBack?: boolean;
185
}
186

187
type NativeStackOptionsArgs<
188
  ParamList extends ParamListBase,
189
  RouteName extends keyof ParamList = keyof ParamList,
190
  NavigatorID extends string | undefined = undefined
191
> = NativeStackScreenProps<ParamList, RouteName, NavigatorID> & {
192
  theme: Theme;
193
};
194

195
interface NativeStackNavigatorProps extends DefaultNavigatorOptions<
196
  ParamListBase,
197
  string | undefined,
198
  StackNavigationState<ParamListBase>,
199
  NativeStackNavigationOptions,
200
  NativeStackNavigationEventMap,
201
  NativeStackNavigationProp<ParamListBase>
202
>, StackRouterOptions, NativeStackNavigationConfig {}
203

204
type NativeStackDescriptor = Descriptor<
205
  NativeStackNavigationOptions,
206
  NativeStackNavigationProp<ParamListBase>,
207
  RouteProp<ParamListBase>
208
>;
209

210
type NativeStackDescriptorMap = {
211
  [key: string]: NativeStackDescriptor;
212
};
213

214
type NativeStackNavigationConfig = {};
215
```