0
# React Navigation Core
1

2
React Navigation Core provides the foundational utilities and building blocks for creating custom navigation components in React Native applications. It offers fundamental hooks like `useNavigationBuilder` for building custom navigators, core navigation context providers, and essential utilities for managing navigation state and lifecycle.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import {
15
  BaseNavigationContainer,
16
  useNavigation,
17
  useRoute,
18
  useFocusEffect,
19
  useIsFocused,
20
  useNavigationBuilder,
21
  useNavigationState,
22
  useNavigationContainerRef,
23
  usePreventRemove,
24
  useTheme,
25
  createNavigationContainerRef,
26
  createNavigatorFactory,
27
  getPathFromState,
28
  getStateFromPath,
29
  getActionFromState,
30
  findFocusedRoute,
31
  NavigationContext,
32
  ThemeProvider,
33
  NavigationIndependentTree,
34
  PreventRemoveProvider
35
} from "@react-navigation/core";
36
```
37

38
For CommonJS:
39

40
```javascript
41
const {
42
  BaseNavigationContainer,
43
  useNavigation,
44
  useRoute,
45
  useFocusEffect,
46
  useIsFocused,
47
  useNavigationBuilder,
48
  createNavigationContainerRef,
49
  getPathFromState,
50
  getStateFromPath
51
} = require("@react-navigation/core");
52
```
53

54
## Basic Usage
55

56
```typescript
57
import React from 'react';
58
import {
59
  BaseNavigationContainer,
60
  useNavigation,
61
  useRoute,
62
  useFocusEffect
63
} from "@react-navigation/core";
64

65
// Basic navigation container setup
66
function App() {
67
  return (
68
    <BaseNavigationContainer>
69
      <MyNavigator />
70
    </BaseNavigationContainer>
71
  );
72
}
73

74
// Using navigation and route hooks
75
function MyScreen() {
76
  const navigation = useNavigation();
77
  const route = useRoute();
78

79
  // Focus effect for screen lifecycle
80
  useFocusEffect(
81
    React.useCallback(() => {
82
      console.log('Screen focused');
83
      return () => {
84
        console.log('Screen unfocused');
85
      };
86
    }, [])
87
  );
88

89
  return (
90
    <View>
91
      <Text>Current route: {route.name}</Text>
92
      <Button
93
        title="Go Back"
94
        onPress={() => navigation.goBack()}
95
      />
96
    </View>
97
  );
98
}
99
```
100

101
## Architecture
102

103
React Navigation Core is built around several key architectural components:
104

105
- **Hook System**: Core hooks (`useNavigation`, `useRoute`, `useFocusEffect`) provide navigation functionality throughout the component tree
106
- **Context Providers**: React contexts distribute navigation state, theme, and route information across components
107
- **Navigation Container**: `BaseNavigationContainer` manages the root navigation state and provides the foundation for all navigation
108
- **Builder Pattern**: `useNavigationBuilder` enables creation of custom navigators with consistent APIs
109
- **State Management**: Navigation state is managed centrally with utilities for serialization and deep linking
110
- **Event System**: Navigation events (focus, blur, state changes) enable reactive programming patterns
111

112
## Capabilities
113

114
### Navigation Hooks
115

116
Core hooks for accessing navigation functionality from anywhere in the component tree, including navigation methods, route information, screen lifecycle, and navigator building.
117

118
```typescript { .api }
119
function useNavigation<T = NavigationProp<ParamListBase>>(): T;
120
function useRoute<T = RouteProp<ParamListBase>>(): T;
121
function useIsFocused(): boolean;
122
function useFocusEffect(effect: () => undefined | void | (() => void)): void;
123
function useNavigationBuilder<State, RouterOptions, ActionHelpers, ScreenOptions, EventMap>(
124
  router: RouterFactory<State, NavigationAction, RouterOptions>,
125
  options: DefaultNavigatorOptions<ParamListBase, string, State, ScreenOptions, EventMap, any> & RouterOptions
126
): NavigationBuilderResult<State, RouterOptions, ActionHelpers, ScreenOptions, EventMap>;
127
function useNavigationState<ParamList extends ParamListBase, T>(
128
  selector: (state: NavigationState<ParamList>) => T
129
): T;
130
function useNavigationContainerRef<ParamList extends ParamListBase>(): NavigationContainerRef<ParamList>;
131
function usePreventRemove(preventRemove: boolean, callback: (data: { action: NavigationAction }) => void): void;
132
function useTheme(): ReactNavigation.Theme;
133
```
134

135
[Navigation Hooks](./hooks.md)
136

137
### Container and Context Components
138

139
Navigation container and context providers that manage navigation state and distribute it throughout the app component tree.
140

141
```typescript { .api }
142
function BaseNavigationContainer(props: NavigationContainerProps): React.JSX.Element;
143

144
interface NavigationContainerProps {
145
  initialState?: InitialState;
146
  onStateChange?: (state: NavigationState | undefined) => void;
147
  onReady?: () => void;
148
  theme?: ReactNavigation.Theme;
149
  children: React.ReactNode;
150
}
151
```
152

153
[Containers and Contexts](./containers-and-contexts.md)
154

155
### State and Path Utilities
156

157
Utilities for converting navigation state to URL paths and vice versa, enabling deep linking and URL generation.
158

159
```typescript { .api }
160
function getPathFromState(
161
  state: NavigationState | PartialState<NavigationState>,
162
  options?: PathConfigOptions
163
): string;
164

165
function getStateFromPath(
166
  path: string,
167
  options?: PathConfigOptions
168
): PartialState<NavigationState> | undefined;
169
```
170

171
[State and Path Utilities](./utilities.md)
172

173
### Static Navigation
174

175
Utilities for creating navigation structures from static configuration objects, enabling declarative navigation setup.
176

177
```typescript { .api }
178
function createComponentForStaticNavigation<T extends StaticNavigation<any, any, any>>(
179
  tree: T,
180
  displayName?: string
181
): React.ComponentType<{}>;
182

183
function createPathConfigForStaticNavigation(
184
  tree: StaticNavigation<any, any, any>,
185
  options?: { initialRouteName?: string },
186
  auto?: boolean
187
): any;
188
```
189

190
[Static Navigation](./static-navigation.md)
191

192
### Navigator Factory Functions
193

194
Factory functions for creating navigation containers and navigator components with proper typing and lifecycle management.
195

196
```typescript { .api }
197
function createNavigationContainerRef<ParamList extends ParamListBase>(): React.RefObject<NavigationContainerRef<ParamList>>;
198

199
function createNavigatorFactory<State, ScreenOptions, EventMap, Navigation>(
200
  Navigator: React.ComponentType<any>
201
): NavigatorFactory<State, ScreenOptions, EventMap, Navigation>;
202
```
203

204
### Additional Utilities
205

206
Additional utility functions for navigation state manipulation, route finding, and validation.
207

208
```typescript { .api }
209
function getActionFromState(
210
  state: NavigationState | PartialState<NavigationState>,
211
  options?: PathConfigOptions
212
): NavigationAction | undefined;
213

214
function findFocusedRoute(
215
  state: NavigationState | PartialState<NavigationState>
216
): NavigationRoute<ParamListBase> | undefined;
217

218
function getFocusedRouteNameFromRoute(
219
  route: NavigationRoute<ParamListBase>
220
): string | undefined;
221

222
function validatePathConfig(
223
  config: PathConfigMap<ParamListBase>,
224
  root?: boolean
225
): void;
226
```
227

228
### Core Types and Interfaces
229

230
Essential TypeScript interfaces and types for navigation props, route objects, and configuration.
231

232
```typescript { .api }
233
interface NavigationProp<
234
  ParamList extends ParamListBase = ParamListBase,
235
  RouteName extends keyof ParamList = keyof ParamList
236
> {
237
  navigate<RouteName extends keyof ParamList>(
238
    name: RouteName,
239
    params?: ParamList[RouteName]
240
  ): void;
241
  goBack(): void;
242
  dispatch(action: NavigationAction): void;
243
  setOptions(options: Partial<ScreenOptions>): void;
244
  isFocused(): boolean;
245
  canGoBack(): boolean;
246
}
247

248
interface RouteProp<
249
  ParamList extends ParamListBase = ParamListBase,
250
  RouteName extends keyof ParamList = keyof ParamList
251
> {
252
  key: string;
253
  name: RouteName;
254
  params: ParamList[RouteName];
255
}
256
```
257

258
[Core Types and Interfaces](./types.md)
259

260
### Router Actions and Types
261

262
Re-exported functionality from `@react-navigation/routers` including action creators and router implementations.
263

264
```typescript { .api }
265
namespace CommonActions {
266
  function navigate(name: string, params?: object): NavigationAction;
267
  function goBack(): NavigationAction;
268
  function reset(state: PartialState<NavigationState>): NavigationAction;
269
  function setParams(params: object): NavigationAction;
270
}
271

272
namespace StackActions {
273
  function push(name: string, params?: object): NavigationAction;
274
  function pop(count?: number): NavigationAction;
275
  function popToTop(): NavigationAction;
276
  function replace(name: string, params?: object): NavigationAction;
277
}
278

279
namespace TabActions {
280
  function jumpTo(name: string, params?: object): NavigationAction;
281
}
282

283
namespace DrawerActions {
284
  function openDrawer(): NavigationAction;
285
  function closeDrawer(): NavigationAction;
286
  function toggleDrawer(): NavigationAction;
287
}
288
```
289

290
[Core Types and Interfaces](./types.md)