0
# Stack Navigation
1

2
Core navigation functionality providing the primary interface for creating and configuring stack-based navigation in React Native applications.
3

4
## Capabilities
5

6
### createStackNavigator
7

8
Factory function that creates a stack navigator with type-safe parameter lists and screen configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a stack navigator factory with TypeScript support
13
 * @returns Object containing Navigator, Screen, and Group components
14
 */
15
function createStackNavigator<ParamList extends ParamListBase = ParamListBase>(): {
16
  Navigator: React.ComponentType<StackNavigatorProps<ParamList>>;
17
  Screen: React.ComponentType<StackScreenConfig<ParamList>>;
18
  Group: React.ComponentType<StackGroupConfig<ParamList>>;
19
};
20

21
interface StackNavigatorProps<ParamList extends ParamListBase> {
22
  id?: string;
23
  initialRouteName?: keyof ParamList;
24
  screenOptions?: StackNavigationOptions | ((props: {
25
    route: RouteProp<ParamList>;
26
    navigation: StackNavigationProp<ParamList>;
27
  }) => StackNavigationOptions);
28
  children: React.ReactNode;
29
  detachInactiveScreens?: boolean;
30
}
31

32
interface StackScreenConfig<ParamList extends ParamListBase> {
33
  name: keyof ParamList;
34
  component?: React.ComponentType<any>;
35
  getComponent?: () => React.ComponentType<any>;
36
  options?: StackNavigationOptions | ((props: {
37
    route: RouteProp<ParamList>;
38
    navigation: StackNavigationProp<ParamList>;
39
  }) => StackNavigationOptions);
40
  initialParams?: ParamList[keyof ParamList];
41
  getId?: ({ params }: { params: ParamList[keyof ParamList] }) => string;
42
  listeners?: StackNavigationEventMap | ((props: {
43
    route: RouteProp<ParamList>;
44
    navigation: StackNavigationProp<ParamList>;
45
  }) => StackNavigationEventMap);
46
}
47

48
interface StackGroupConfig<ParamList extends ParamListBase> {
49
  screenOptions?: StackNavigationOptions | ((props: {
50
    route: RouteProp<ParamList>;
51
    navigation: StackNavigationProp<ParamList>;
52
  }) => StackNavigationOptions);
53
  children: React.ReactNode;
54
}
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { createStackNavigator } from '@react-navigation/stack';
61

62
// Define parameter types
63
type RootStackParamList = {
64
  Home: undefined;
65
  Profile: { userId: string };
66
  Settings: { section?: string };
67
};
68

69
const Stack = createStackNavigator<RootStackParamList>();
70

71
// Basic navigator setup
72
function App() {
73
  return (
74
    <Stack.Navigator
75
      initialRouteName="Home"
76
      screenOptions={{
77
        headerStyle: { backgroundColor: '#f4511e' },
78
        headerTintColor: '#fff',
79
        headerTitleStyle: { fontWeight: 'bold' },
80
      }}
81
    >
82
      <Stack.Screen name="Home" component={HomeScreen} />
83
      <Stack.Screen 
84
        name="Profile" 
85
        component={ProfileScreen}
86
        options={{ title: 'User Profile' }}
87
      />
88
      <Stack.Screen 
89
        name="Settings" 
90
        component={SettingsScreen}
91
        options={({ route, navigation }) => ({
92
          title: route.params?.section ? `${route.params.section} Settings` : 'Settings',
93
        })}
94
      />
95
    </Stack.Navigator>
96
  );
97
}
98

99
// Group configuration
100
function AuthenticatedStack() {
101
  return (
102
    <Stack.Navigator>
103
      <Stack.Group screenOptions={{ headerShown: false }}>
104
        <Stack.Screen name="Home" component={HomeScreen} />
105
        <Stack.Screen name="Feed" component={FeedScreen} />
106
      </Stack.Group>
107
      <Stack.Group screenOptions={{ presentation: 'modal' }}>
108
        <Stack.Screen name="Settings" component={SettingsScreen} />
109
        <Stack.Screen name="Profile" component={ProfileScreen} />
110
      </Stack.Group>
111
    </Stack.Navigator>
112
  );
113
}
114
```
115

116
### StackView Component
117

118
Internal view component that renders the stack navigation interface (exported for advanced customization).
119

120
```typescript { .api }
121
/**
122
 * Main stack view component that renders navigation interface
123
 * @param props - Stack view configuration props
124
 * @returns React component rendering the stack navigation
125
 */
126
interface StackViewProps {
127
  state: StackNavigationState<ParamListBase>;
128
  navigation: StackNavigationHelpers;
129
  descriptors: StackDescriptorMap;
130
  detachInactiveScreens?: boolean;
131
}
132

133
const StackView: React.ComponentType<StackViewProps>;
134
```
135

136
### Header Component
137

138
Customizable header component for stack screens with platform-specific styling and behavior.
139

140
```typescript { .api }
141
/**
142
 * Header component for stack screens with customizable styling
143
 * @param props - Header configuration props
144
 * @returns React component rendering the navigation header
145
 */
146
interface StackHeaderProps {
147
  layout: Layout;
148
  back?: {
149
    title: string;
150
  };
151
  progress: SceneProgress;
152
  options: StackNavigationOptions;
153
  route: Route<string>;
154
  navigation: StackNavigationProp<ParamListBase>;
155
  styleInterpolator: StackHeaderStyleInterpolator;
156
}
157

158
const Header: React.ComponentType<StackHeaderProps>;
159

160
interface Layout {
161
  width: number;
162
  height: number;
163
}
164

165
interface SceneProgress {
166
  current: Animated.AnimatedInterpolation<number>;
167
  next?: Animated.AnimatedInterpolation<number>;
168
  previous?: Animated.AnimatedInterpolation<number>;
169
}
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
import { Header } from '@react-navigation/stack';
176

177
// Custom header usage in screen options
178
function CustomHeaderScreen() {
179
  return (
180
    <Stack.Screen
181
      name="Custom"
182
      component={MyComponent}
183
      options={{
184
        header: (props) => (
185
          <Header
186
            {...props}
187
            options={{
188
              ...props.options,
189
              headerStyle: { backgroundColor: 'red' },
190
              headerTitle: 'Custom Header',
191
            }}
192
          />
193
        ),
194
      }}
195
    />
196
  );
197
}
198
```
199

200
## Navigation Methods
201

202
Stack navigation provides standard navigation methods plus stack-specific actions:
203

204
```typescript { .api }
205
interface StackNavigationHelpers {
206
  // Standard navigation methods
207
  navigate<RouteName extends keyof ParamList>(
208
    route: RouteName,
209
    params?: ParamList[RouteName]
210
  ): void;
211
  push<RouteName extends keyof ParamList>(
212
    route: RouteName,
213
    params?: ParamList[RouteName]
214
  ): void;
215
  pop(count?: number): void;
216
  popToTop(): void;
217
  replace<RouteName extends keyof ParamList>(
218
    route: RouteName,
219
    params?: ParamList[RouteName]
220
  ): void;
221
  goBack(): void;
222
  
223
  // State queries
224
  canGoBack(): boolean;
225
  isFocused(): boolean;
226
  
227
  // Event handling
228
  addListener(type: keyof StackNavigationEventMap, callback: Function): () => void;
229
}
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
function MyScreen({ navigation }: StackScreenProps<ParamList, 'MyScreen'>) {
236
  const handlePress = () => {
237
    // Push new screen onto stack
238
    navigation.push('Details', { id: 123 });
239
    
240
    // Pop current screen
241
    navigation.pop();
242
    
243
    // Pop to top of stack
244
    navigation.popToTop();
245
    
246
    // Replace current screen
247
    navigation.replace('NewScreen', { data: 'example' });
248
  };
249

250
  // Listen to navigation events
251
  React.useEffect(() => {
252
    const unsubscribe = navigation.addListener('transitionEnd', (e) => {
253
      console.log('Transition ended:', e.data.closing);
254
    });
255

256
    return unsubscribe;
257
  }, [navigation]);
258

259
  return (
260
    <View>
261
      <Button title="Navigate" onPress={handlePress} />
262
    </View>
263
  );
264
}
265
```