0
# Navigation Container
1

2
The NavigationContainer is the root component that manages navigation state, provides navigation context, and handles platform-specific behaviors like deep linking, theming, and back button integration.
3

4
## Capabilities
5

6
### NavigationContainer Component
7

8
The main container component that should wrap your entire navigation tree.
9

10
```typescript { .api }
11
/**
12
 * Container component which holds the navigation state designed for React Native apps.
13
 * This should be rendered at the root wrapping the whole app.
14
 */
15
function NavigationContainer<ParamList extends {} = ReactNavigation.RootParamList>(
16
  props: NavigationContainerProps & {
17
    /** Text direction of the components. Defaults to device locale direction */
18
    direction?: LocaleDirection;
19
    /** Options for deep linking. Deep link handling is enabled when this prop is provided */
20
    linking?: LinkingOptions<ParamList>;
21
    /** Fallback component to render until initial state is ready when linking is enabled */
22
    fallback?: React.ReactNode;
23
    /** Options to configure the document title on Web */
24
    documentTitle?: DocumentTitleOptions;
25
    /** Child elements to render the content */
26
    children: React.ReactNode;
27
  } & React.RefAttributes<NavigationContainerRef<ParamList>>
28
): React.ReactElement;
29

30
type LocaleDirection = 'ltr' | 'rtl';
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import React from 'react';
37
import { NavigationContainer } from '@react-navigation/native';
38
import { createStackNavigator } from '@react-navigation/stack';
39

40
const Stack = createStackNavigator();
41

42
// Basic usage
43
function BasicApp() {
44
  return (
45
    <NavigationContainer>
46
      <Stack.Navigator>
47
        <Stack.Screen name="Home" component={HomeScreen} />
48
        <Stack.Screen name="Profile" component={ProfileScreen} />
49
      </Stack.Navigator>
50
    </NavigationContainer>
51
  );
52
}
53

54
// With deep linking
55
function AppWithLinking() {
56
  const linking = {
57
    prefixes: ['myapp://'],
58
    config: {
59
      screens: {
60
        Home: 'home',
61
        Profile: 'user/:id',
62
      },
63
    },
64
  };
65

66
  return (
67
    <NavigationContainer linking={linking}>
68
      <Stack.Navigator>
69
        <Stack.Screen name="Home" component={HomeScreen} />
70
        <Stack.Screen name="Profile" component={ProfileScreen} />
71
      </Stack.Navigator>
72
    </NavigationContainer>
73
  );
74
}
75

76
// With custom theme and direction
77
function ThemedApp() {
78
  const customTheme = {
79
    ...DefaultTheme,
80
    colors: {
81
      ...DefaultTheme.colors,
82
      primary: '#007AFF',
83
    },
84
  };
85

86
  return (
87
    <NavigationContainer 
88
      theme={customTheme}
89
      direction="rtl"
90
      onReady={() => console.log('Navigation is ready')}
91
      onStateChange={(state) => console.log('Navigation state changed', state)}
92
    >
93
      <Stack.Navigator>
94
        <Stack.Screen name="Home" component={HomeScreen} />
95
      </Stack.Navigator>
96
    </NavigationContainer>
97
  );
98
}
99
```
100

101
### Navigation Container Props
102

103
Properties inherited from NavigationContainerProps and additional platform-specific options.
104

105
```typescript { .api }
106
interface NavigationContainerProps {
107
  /** Initial state object for the navigation tree */
108
  initialState?: NavigationState | PartialState<NavigationState>;
109
  /** Callback which is called after the navigation tree mounts */
110
  onReady?: () => void;
111
  /** Callback which is called with the latest navigation state when it changes */
112
  onStateChange?: (state: NavigationState | undefined) => void;
113
  /** Callback which is called when an action is not handled */
114
  onUnhandledAction?: (action: NavigationAction) => void;
115
  /** Theme object for the UI elements */
116
  theme?: Theme;
117
  /** Whether to render children inside a React.Fragment */
118
  independent?: boolean;
119
}
120

121
interface DocumentTitleOptions {
122
  /** Whether document title updating is enabled. Defaults to true on web */
123
  enabled?: boolean;
124
  /** Custom formatter for the document title */
125
  formatter?: (
126
    options: Record<string, any> | undefined,
127
    route: Route<string> | undefined
128
  ) => string;
129
}
130
```
131

132
### Navigation Container Ref
133

134
Reference object that provides access to navigation methods and state.
135

136
```typescript { .api }
137
interface NavigationContainerRef<ParamList extends {} = ReactNavigation.RootParamList> {
138
  /** Navigate to a route in current navigation tree */
139
  navigate<RouteName extends keyof ParamList>(
140
    name: RouteName,
141
    params?: ParamList[RouteName]
142
  ): void;
143
  /** Navigate to a route in current navigation tree */
144
  navigate<RouteName extends keyof ParamList>(
145
    route: { name: RouteName; params?: ParamList[RouteName]; path?: string }
146
  ): void;
147
  /** Go back to the previous route in history */
148
  goBack(): void;
149
  /** Check if it's possible to go back in current navigation tree */
150
  canGoBack(): boolean;
151
  /** Dispatch a navigation action */
152
  dispatch(action: NavigationAction): void;
153
  /** Get the current navigation state */
154
  getState(): NavigationState;
155
  /** Get the currently focused route */
156
  getCurrentRoute(): Route<string> | undefined;
157
  /** Get options for the currently focused route */
158
  getCurrentOptions(): object | undefined;
159
  /** Check if the screen is focused */
160
  isFocused(): boolean;
161
  /** Subscribe to navigation state updates */
162
  addListener<EventName extends keyof NavigationEventMap>(
163
    type: EventName,
164
    listener: NavigationEventMap[EventName]
165
  ): () => void;
166
  /** Remove all listeners for the given event type */
167
  removeListener<EventName extends keyof NavigationEventMap>(
168
    type: EventName,
169
    listener: NavigationEventMap[EventName]
170
  ): void;
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
import React, { useRef } from 'react';
178
import { NavigationContainer } from '@react-navigation/native';
179
import type { NavigationContainerRef } from '@react-navigation/native';
180

181
function App() {
182
  const navigationRef = useRef<NavigationContainerRef<RootParamList>>(null);
183

184
  const handleDeepLink = (url: string) => {
185
    // Custom deep link handling
186
    if (url.includes('profile')) {
187
      navigationRef.current?.navigate('Profile', { id: '123' });
188
    }
189
  };
190

191
  return (
192
    <NavigationContainer 
193
      ref={navigationRef}
194
      onReady={() => {
195
        // Navigation is ready, can safely navigate
196
        console.log('Current route:', navigationRef.current?.getCurrentRoute()?.name);
197
      }}
198
    >
199
      {/* Your navigation structure */}
200
    </NavigationContainer>
201
  );
202
}
203
```
204

205
### Platform Integration
206

207
The NavigationContainer automatically handles platform-specific behaviors:
208

209
- **Android Back Button**: Automatically handles hardware back button presses
210
- **Web Document Title**: Updates browser document title based on current route
211
- **Deep Linking**: Processes initial URLs and URL changes for navigation
212
- **Locale Direction**: Supports RTL/LTR text direction based on device settings
213
- **Focus Management**: Manages focus states for accessibility
214

215
```typescript { .api }
216
// Platform-specific behavior is handled automatically
217
// No additional configuration required for basic integration
218

219
// For custom back button behavior:
220
interface NavigationContainerProps {
221
  /** Custom handler for unhandled actions (including back button) */
222
  onUnhandledAction?: (action: NavigationAction) => void;
223
}
224
```