0
# Navigator Creation
1

2
Core functionality for creating and configuring native stack navigators with full TypeScript integration and type safety.
3

4
## Capabilities
5

6
### Create Native Stack Navigator
7

8
Creates a typed native stack navigator factory function that can be used to define screens and navigation structure.
9

10
```typescript { .api }
11
/**
12
 * Creates a native stack navigator with type safety for parameter lists
13
 * @param config - Optional static configuration for the navigator
14
 * @returns TypedNavigator factory function
15
 */
16
function createNativeStackNavigator<
17
  const ParamList extends ParamListBase,
18
  const NavigatorID extends string | undefined = undefined,
19
  const TypeBag extends NavigatorTypeBagBase = {
20
    ParamList: ParamList;
21
    NavigatorID: NavigatorID;
22
    State: StackNavigationState<ParamList>;
23
    ScreenOptions: NativeStackNavigationOptions;
24
    EventMap: NativeStackNavigationEventMap;
25
    NavigationList: {
26
      [RouteName in keyof ParamList]: NativeStackNavigationProp<
27
        ParamList,
28
        RouteName,
29
        NavigatorID
30
      >;
31
    };
32
    Navigator: typeof NativeStackNavigator;
33
  },
34
  const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>
35
>(config?: Config): TypedNavigator<TypeBag, Config>;
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { createNativeStackNavigator } from "@react-navigation/native-stack";
42

43
// Define parameter list type for type safety
44
type RootStackParamList = {
45
  Home: undefined;
46
  Profile: { userId: string };
47
  Settings: undefined;
48
};
49

50
// Create the navigator
51
const Stack = createNativeStackNavigator<RootStackParamList>();
52

53
// Use in component
54
function App() {
55
  return (
56
    <Stack.Navigator initialRouteName="Home">
57
      <Stack.Screen name="Home" component={HomeScreen} />
58
      <Stack.Screen 
59
        name="Profile" 
60
        component={ProfileScreen}
61
        options={({ route }) => ({ 
62
          title: `User ${route.params.userId}` 
63
        })}
64
      />
65
      <Stack.Screen name="Settings" component={SettingsScreen} />
66
    </Stack.Navigator>
67
  );
68
}
69
```
70

71
### Navigator Component
72

73
The navigator component returned by `createNativeStackNavigator()` with standard navigator props.
74

75
```typescript { .api }
76
/**
77
 * Native Stack Navigator component props
78
 */
79
interface NativeStackNavigatorProps extends DefaultNavigatorOptions<
80
  ParamListBase,
81
  string | undefined,
82
  StackNavigationState<ParamListBase>,
83
  NativeStackNavigationOptions,
84
  NativeStackNavigationEventMap,
85
  NativeStackNavigationProp<ParamListBase>
86
>, StackRouterOptions, NativeStackNavigationConfig {
87
  /**
88
   * Navigator ID for identifying this navigator
89
   */
90
  id?: string;
91
  /**
92
   * Initial route name to display
93
   */
94
  initialRouteName?: string;
95
  /**
96
   * Child Screen components
97
   */
98
  children: React.ReactNode;
99
  /**
100
   * Screen options applied to all screens
101
   */
102
  screenOptions?: NativeStackNavigationOptions | ((props: {
103
    route: RouteProp<ParamListBase>;
104
    navigation: any;
105
  }) => NativeStackNavigationOptions);
106
  /**
107
   * Screen listeners applied to all screens
108
   */
109
  screenListeners?: object;
110
}
111
```
112

113
**Navigator Configuration Examples:**
114

115
```typescript
116
// Basic navigator with default options
117
<Stack.Navigator>
118
  <Stack.Screen name="Home" component={HomeScreen} />
119
</Stack.Navigator>
120

121
// Navigator with global screen options
122
<Stack.Navigator
123
  screenOptions={{
124
    headerStyle: { backgroundColor: '#6a51ae' },
125
    headerTintColor: '#fff',
126
    headerTitleStyle: { fontWeight: 'bold' },
127
  }}
128
>
129
  <Stack.Screen name="Home" component={HomeScreen} />
130
  <Stack.Screen name="Details" component={DetailsScreen} />
131
</Stack.Navigator>
132

133
// Navigator with dynamic screen options
134
<Stack.Navigator
135
  screenOptions={({ route, navigation }) => ({
136
    headerTitle: route.name,
137
    headerLeft: () => (
138
      <Button onPress={() => navigation.goBack()} title="Back" />
139
    ),
140
  })}
141
>
142
  <Stack.Screen name="Home" component={HomeScreen} />
143
</Stack.Navigator>
144
```
145

146
### Screen Component
147

148
Individual screen components within the navigator.
149

150
```typescript { .api }
151
/**
152
 * Screen component for defining individual screens in the stack
153
 */
154
interface ScreenProps {
155
  /**
156
   * Screen name - must match a key in the ParamList type
157
   */
158
  name: string;
159
  /**
160
   * React component to render for this screen
161
   */
162
  component?: React.ComponentType<any>;
163
  /**
164
   * Function that returns a React element to render
165
   */
166
  children?: (props: any) => React.ReactNode;
167
  /**
168
   * Screen-specific navigation options
169
   */
170
  options?: NativeStackNavigationOptions | ((props: {
171
    route: RouteProp<ParamListBase>;
172
    navigation: any;
173
  }) => NativeStackNavigationOptions);
174
  /**
175
   * Screen-specific event listeners
176
   */
177
  listeners?: object;
178
  /**
179
   * Initial parameters for the screen
180
   */
181
  initialParams?: object;
182
}
183
```
184

185
**Screen Definition Examples:**
186

187
```typescript
188
// Basic screen definition
189
<Stack.Screen name="Home" component={HomeScreen} />
190

191
// Screen with static options
192
<Stack.Screen 
193
  name="Details" 
194
  component={DetailsScreen}
195
  options={{
196
    title: 'Details',
197
    headerBackTitle: 'Back',
198
  }}
199
/>
200

201
// Screen with dynamic options
202
<Stack.Screen 
203
  name="Profile" 
204
  component={ProfileScreen}
205
  options={({ route }) => ({
206
    title: route.params?.name || 'Profile',
207
  })}
208
/>
209

210
// Screen with children function
211
<Stack.Screen name="Modal">
212
  {(props) => <ModalScreen {...props} customProp="value" />}
213
</Stack.Screen>
214
```
215

216
## Type Definitions
217

218
```typescript { .api }
219
type ParamListBase = Record<string, object | undefined>;
220

221
interface NavigatorTypeBagBase {
222
  ParamList: ParamListBase;
223
  NavigatorID: string | undefined;
224
  State: NavigationState;
225
  ScreenOptions: object;
226
  EventMap: EventMapBase;
227
  NavigationList: Record<string, any>;
228
  Navigator: React.ComponentType<any>;
229
}
230

231
interface StaticConfig<TypeBag extends NavigatorTypeBagBase> {
232
  name?: string;
233
}
234

235
interface TypedNavigator<
236
  TypeBag extends NavigatorTypeBagBase,
237
  Config extends StaticConfig<TypeBag>
238
> {
239
  Navigator: React.ComponentType<any>;
240
  Screen: React.ComponentType<any>;
241
}
242
```