0
# Navigation and Routing
1

2
Navigation capabilities including programmatic navigation, event handling, route management, and TypeScript integration for bottom tab navigation.
3

4
## Capabilities
5

6
### Navigation Prop
7

8
The navigation prop provides methods for programmatic navigation and tab management.
9

10
```typescript { .api }
11
interface BottomTabNavigationProp<
12
  ParamList extends ParamListBase,
13
  RouteName extends keyof ParamList = keyof ParamList,
14
  NavigatorID extends string | undefined = undefined
15
> extends NavigationProp<
16
  ParamList,
17
  RouteName,
18
  NavigatorID,
19
  TabNavigationState<ParamList>,
20
  BottomTabNavigationOptions,
21
  BottomTabNavigationEventMap
22
>, TabActionHelpers<ParamList> {
23
  /**
24
   * Navigate to a tab by name
25
   */
26
  navigate<RouteName extends keyof ParamList>(
27
    name: RouteName,
28
    params?: ParamList[RouteName]
29
  ): void;
30
  
31
  /**
32
   * Jump to a tab without invoking navigation logic
33
   */
34
  jumpTo<RouteName extends keyof ParamList>(
35
    name: RouteName,
36
    params?: ParamList[RouteName]
37
  ): void;
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { BottomTabNavigationProp } from '@react-navigation/bottom-tabs';
45

46
type TabParamList = {
47
  Home: undefined;
48
  Profile: { userId: string };
49
  Settings: undefined;
50
};
51

52
type HomeScreenNavigationProp = BottomTabNavigationProp<TabParamList, 'Home'>;
53

54
function HomeScreen({ navigation }: { navigation: HomeScreenNavigationProp }) {
55
  const navigateToProfile = () => {
56
    navigation.navigate('Profile', { userId: '123' });
57
  };
58
  
59
  const jumpToSettings = () => {
60
    navigation.jumpTo('Settings');
61
  };
62
  
63
  return (
64
    <View>
65
      <Button title="Go to Profile" onPress={navigateToProfile} />
66
      <Button title="Jump to Settings" onPress={jumpToSettings} />
67
    </View>
68
  );
69
}
70
```
71

72
### Tab Action Helpers
73

74
Methods for managing tab-specific navigation actions.
75

76
```typescript { .api }
77
interface TabActionHelpers<ParamList extends ParamListBase> {
78
  /**
79
   * Jump to a tab, focusing it without animation
80
   */
81
  jumpTo<RouteName extends keyof ParamList>(
82
    name: RouteName,
83
    params?: ParamList[RouteName]
84
  ): void;
85
}
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
// Inside a screen component
92
function QuickActionsComponent({ navigation }) {
93
  const quickJumpToTab = (tabName) => {
94
    navigation.jumpTo(tabName);
95
  };
96
  
97
  return (
98
    <View style={styles.quickActions}>
99
      <TouchableOpacity onPress={() => quickJumpToTab('Home')}>
100
        <Text>Home</Text>
101
      </TouchableOpacity>
102
      <TouchableOpacity onPress={() => quickJumpToTab('Settings')}>
103
        <Text>Settings</Text>
104
      </TouchableOpacity>
105
    </View>
106
  );
107
}
108
```
109

110
### Navigation Events
111

112
Handle navigation events for tab interactions and transitions.
113

114
```typescript { .api }
115
interface BottomTabNavigationEventMap {
116
  /**
117
   * Event which fires on tapping on the tab in the tab bar.
118
   */
119
  tabPress: { data: undefined; canPreventDefault: true };
120
  
121
  /**
122
   * Event which fires on long press on the tab in the tab bar.
123
   */
124
  tabLongPress: { data: undefined };
125
  
126
  /**
127
   * Event which fires when a transition animation starts.
128
   */
129
  transitionStart: { data: undefined };
130
  
131
  /**
132
   * Event which fires when a transition animation ends.
133
   */
134
  transitionEnd: { data: undefined };
135
}
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
import { useFocusEffect } from '@react-navigation/native';
142

143
function ProfileScreen({ navigation }) {
144
  // Listen to tab press events
145
  React.useEffect(() => {
146
    const unsubscribe = navigation.addListener('tabPress', (e) => {
147
      // Prevent default behavior
148
      e.preventDefault();
149
      
150
      // Custom behavior
151
      Alert.alert('Tab pressed!', 'Do something custom');
152
    });
153
    
154
    return unsubscribe;
155
  }, [navigation]);
156
  
157
  // Listen to transition events
158
  React.useEffect(() => {
159
    const unsubscribeStart = navigation.addListener('transitionStart', () => {
160
      console.log('Transition started');
161
    });
162
    
163
    const unsubscribeEnd = navigation.addListener('transitionEnd', () => {
164
      console.log('Transition ended');
165
    });
166
    
167
    return () => {
168
      unsubscribeStart();
169
      unsubscribeEnd();
170
    };
171
  }, [navigation]);
172
  
173
  return <View>{/* screen content */}</View>;
174
}
175
```
176

177
### Screen Props and Route Information
178

179
Access route information and parameters from screen components.
180

181
```typescript { .api }
182
interface BottomTabScreenProps<
183
  ParamList extends ParamListBase,
184
  RouteName extends keyof ParamList = keyof ParamList,
185
  NavigatorID extends string | undefined = undefined
186
> {
187
  navigation: BottomTabNavigationProp<ParamList, RouteName, NavigatorID>;
188
  route: RouteProp<ParamList, RouteName>;
189
}
190

191
interface RouteProp<ParamList extends ParamListBase, RouteName extends keyof ParamList> {
192
  key: string;
193
  name: RouteName;
194
  params: ParamList[RouteName];
195
  path?: string;
196
}
197
```
198

199
**Usage Examples:**
200

201
```typescript
202
import { BottomTabScreenProps } from '@react-navigation/bottom-tabs';
203

204
type TabParamList = {
205
  Profile: { userId: string; tab?: string };
206
};
207

208
type ProfileScreenProps = BottomTabScreenProps<TabParamList, 'Profile'>;
209

210
function ProfileScreen({ navigation, route }: ProfileScreenProps) {
211
  const { userId, tab } = route.params;
212
  
213
  React.useEffect(() => {
214
    // Access route parameters
215
    console.log('User ID:', userId);
216
    console.log('Active tab:', tab);
217
    console.log('Route key:', route.key);
218
    console.log('Route name:', route.name);
219
  }, [route]);
220
  
221
  return (
222
    <View>
223
      <Text>Profile for user: {userId}</Text>
224
      {tab && <Text>Active tab: {tab}</Text>}
225
    </View>
226
  );
227
}
228
```
229

230
### Navigation State Management
231

232
Access and monitor the navigation state for advanced use cases.
233

234
```typescript { .api }
235
interface TabNavigationState<ParamList extends ParamListBase> {
236
  /**
237
   * Type of the navigation state
238
   */
239
  type: 'tab';
240
  
241
  /**
242
   * Unique key for the navigation state
243
   */
244
  key: string;
245
  
246
  /**
247
   * Index of the currently active tab
248
   */
249
  index: number;
250
  
251
  /**
252
   * Array of route objects for each tab
253
   */
254
  routes: Array<{
255
    key: string;
256
    name: keyof ParamList;
257
    params?: ParamList[keyof ParamList];
258
    path?: string;
259
  }>;
260
  
261
  /**
262
   * History of navigation actions
263
   */
264
  history?: NavigationAction[];
265
}
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
import { useNavigationState } from '@react-navigation/native';
272

273
function TabIndicator() {
274
  const state = useNavigationState(state => state);
275
  
276
  if (state?.type !== 'tab') return null;
277
  
278
  return (
279
    <View>
280
      <Text>Active tab: {state.routes[state.index].name}</Text>
281
      <Text>Total tabs: {state.routes.length}</Text>
282
      {state.routes.map((route, index) => (
283
        <Text key={route.key}>
284
          {index === state.index ? '● ' : '○ '}
285
          {route.name}
286
        </Text>
287
      ))}
288
    </View>
289
  );
290
}
291
```
292

293
### Navigation Listeners
294

295
Set up global navigation listeners for the entire tab navigator.
296

297
```typescript { .api }
298
interface NavigationListeners {
299
  /**
300
   * Listener for tab press events
301
   */
302
  tabPress?: (e: EventArg<'tabPress', true, undefined>) => void;
303
  
304
  /**
305
   * Listener for tab long press events  
306
   */
307
  tabLongPress?: (e: EventArg<'tabLongPress', false, undefined>) => void;
308
  
309
  /**
310
   * Listener for focus events
311
   */
312
  focus?: (e: EventArg<'focus', false, undefined>) => void;
313
  
314
  /**
315
   * Listener for blur events
316
   */
317
  blur?: (e: EventArg<'blur', false, undefined>) => void;
318
}
319
```
320

321
**Usage Examples:**
322

323
```typescript
324
<Tab.Navigator
325
  screenListeners={({ navigation, route }) => ({
326
    tabPress: (e) => {
327
      // Global tab press handler
328
      console.log(`Tab pressed: ${route.name}`);
329
    },
330
    tabLongPress: (e) => {
331
      // Global tab long press handler
332
      console.log(`Tab long pressed: ${route.name}`);
333
    },
334
    focus: () => {
335
      // Screen came into focus
336
      console.log(`Screen focused: ${route.name}`);
337
    },
338
    blur: () => {
339
      // Screen lost focus
340
      console.log(`Screen blurred: ${route.name}`);
341
    },
342
  })}
343
>
344
  {/* screens */}
345
</Tab.Navigator>
346
```
347

348
### Deep Linking Integration
349

350
Support for deep linking with tab navigation.
351

352
```typescript { .api }
353
interface LinkingConfiguration {
354
  screens: {
355
    [K in keyof ParamList]: string | {
356
      path: string;
357
      parse?: Record<string, (value: string) => any>;
358
      stringify?: Record<string, (value: any) => string>;
359
    };
360
  };
361
}
362
```
363

364
**Usage Examples:**
365

366
```typescript
367
import { NavigationContainer } from '@react-navigation/native';
368

369
const linking = {
370
  prefixes: ['myapp://'],
371
  config: {
372
    screens: {
373
      TabNavigator: {
374
        screens: {
375
          Home: 'home',
376
          Profile: {
377
            path: 'profile/:userId',
378
            parse: {
379
              userId: (userId: string) => userId,
380
            },
381
          },
382
          Settings: 'settings',
383
        },
384
      },
385
    },
386
  },
387
};
388

389
function App() {
390
  return (
391
    <NavigationContainer linking={linking}>
392
      <Tab.Navigator>
393
        {/* screens */}
394
      </Tab.Navigator>
395
    </NavigationContainer>
396
  );
397
}
398
```
399

400
### Navigation Actions
401

402
Programmatically dispatch navigation actions.
403

404
```typescript { .api }
405
interface NavigationActions {
406
  /**
407
   * Navigate to a route
408
   */
409
  navigate(name: string, params?: object): void;
410
  
411
  /**
412
   * Go back to previous screen
413
   */
414
  goBack(): void;
415
  
416
  /**
417
   * Reset navigation state
418
   */
419
  reset(state: Partial<TabNavigationState>): void;
420
  
421
  /**
422
   * Set new navigation params
423
   */
424
  setParams(params: object): void;
425
}
426
```
427

428
**Usage Examples:**
429

430
```typescript
431
import { CommonActions } from '@react-navigation/native';
432

433
function CustomNavigationComponent({ navigation }) {
434
  const resetToHome = () => {
435
    navigation.dispatch(
436
      CommonActions.reset({
437
        index: 0,
438
        routes: [{ name: 'Home' }],
439
      })
440
    );
441
  };
442
  
443
  const updateParams = () => {
444
    navigation.dispatch(
445
      CommonActions.setParams({
446
        userId: 'newUserId',
447
        refresh: true,
448
      })
449
    );
450
  };
451
  
452
  return (
453
    <View>
454
      <Button title="Reset to Home" onPress={resetToHome} />
455
      <Button title="Update Params" onPress={updateParams} />
456
    </View>
457
  );
458
}
459
```