0
# @react-navigation/native
1

2
@react-navigation/native provides React Native integration for React Navigation, serving as the foundational bridge between React Navigation's core navigation logic and React Native's platform-specific implementations. It handles navigation containers, deep linking, theming, and platform-specific behaviors across iOS and Android.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { NavigationContainer, Link, createStaticNavigation } from "@react-navigation/native";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { NavigationContainer, Link, createStaticNavigation } = require("@react-navigation/native");
21
```
22

23
Theme imports:
24

25
```typescript
26
import { DefaultTheme, DarkTheme } from "@react-navigation/native";
27
```
28

29
Hook imports:
30

31
```typescript
32
import { 
33
  useLinkProps, 
34
  useLinkTo, 
35
  useLinkBuilder, 
36
  useScrollToTop, 
37
  useLocale 
38
} from "@react-navigation/native";
39
```
40

41
## Basic Usage
42

43
```typescript
44
import React from 'react';
45
import { NavigationContainer } from '@react-navigation/native';
46
import { createStackNavigator } from '@react-navigation/stack';
47

48
const Stack = createStackNavigator();
49

50
function App() {
51
  return (
52
    <NavigationContainer>
53
      <Stack.Navigator>
54
        <Stack.Screen name="Home" component={HomeScreen} />
55
        <Stack.Screen name="Details" component={DetailsScreen} />
56
      </Stack.Navigator>
57
    </NavigationContainer>
58
  );
59
}
60
```
61

62
## Architecture
63

64
@react-navigation/native is built around several key components:
65

66
- **Navigation Container**: The root component that manages navigation state and provides context
67
- **Deep Linking System**: URL-based navigation with configurable path matching and prefixes
68
- **Theme System**: Built-in light/dark themes with full customization support
69
- **Platform Integration**: Native back button handling, document title management, and platform-specific behaviors
70
- **Hook System**: React hooks for navigation, linking, and scroll management
71
- **Server Rendering**: SSR support for web deployments via ServerContainer
72

73
## Capabilities
74

75
### Navigation Container
76

77
The root navigation container that manages navigation state and provides linking, theming, and platform integration.
78

79
```typescript { .api }
80
function NavigationContainer<ParamList extends {} = ReactNavigation.RootParamList>(
81
  props: NavigationContainerProps & {
82
    direction?: LocaleDirection;
83
    linking?: LinkingOptions<ParamList>;
84
    fallback?: React.ReactNode;
85
    documentTitle?: DocumentTitleOptions;
86
    children: React.ReactNode;
87
  }
88
): React.ReactElement;
89

90
type LocaleDirection = 'ltr' | 'rtl';
91
```
92

93
[Navigation Container](./navigation-container.md)
94

95
### Deep Linking
96

97
Comprehensive URL-based navigation system with path matching, prefixes, and state synchronization.
98

99
```typescript { .api }
100
interface LinkingOptions<ParamList extends {}> {
101
  enabled?: boolean;
102
  prefixes: string[];
103
  filter?: (url: string) => boolean;
104
  config?: {
105
    path?: string;
106
    screens: PathConfigMap<ParamList>;
107
    initialRouteName?: keyof ParamList;
108
  };
109
  getInitialURL?: () => string | null | undefined | Promise<string | null | undefined>;
110
  subscribe?: (listener: (url: string) => void) => undefined | void | (() => void);
111
  getStateFromPath?: typeof getStateFromPath;
112
  getPathFromState?: typeof getPathFromState;
113
  getActionFromState?: typeof getActionFromState;
114
}
115
```
116

117
[Deep Linking](./deep-linking.md)
118

119
### Link Components
120

121
React components for rendering navigational links with proper web semantics and native behavior.
122

123
```typescript { .api }
124
function Link<ParamList extends ReactNavigation.RootParamList>(
125
  props: LinkProps<ParamList> & Omit<TextProps, 'disabled'> & {
126
    target?: string;
127
    onPress?: (e: React.MouseEvent<HTMLAnchorElement> | GestureResponderEvent) => void;
128
    disabled?: boolean | null;
129
    children: React.ReactNode;
130
  }
131
): React.ReactElement;
132

133
type LinkProps<ParamList, RouteName extends keyof ParamList = keyof ParamList> =
134
  | ({ href?: string; action?: NavigationAction; } & 
135
     (undefined extends ParamList[RouteName]
136
       ? { screen: RouteName; params?: ParamList[RouteName] }
137
       : { screen: RouteName; params: ParamList[RouteName] }))
138
  | { href?: string; action: NavigationAction; screen?: undefined; params?: undefined; };
139
```
140

141
[Link Components](./link-components.md)
142

143
### Navigation Hooks
144

145
React hooks for programmatic navigation, link building, and navigation state management.
146

147
```typescript { .api }
148
function useLinkTo(): (href: string) => void;
149

150
function useLinkProps<ParamList extends ReactNavigation.RootParamList>(
151
  props: LinkProps<ParamList>
152
): { href?: string; role: 'link'; onPress: (e?: any) => void; };
153

154
function useLinkBuilder(): {
155
  buildHref: (name: string, params?: object) => string | undefined;
156
  buildAction: (href: string) => NavigationAction;
157
};
158

159
function useScrollToTop(ref: React.RefObject<ScrollableWrapper>): void;
160

161
function useLocale(): { direction: LocaleDirection };
162
```
163

164
[Navigation Hooks](./navigation-hooks.md)
165

166
### Static Navigation
167

168
Type-safe navigation configuration system that generates navigation components from static definitions.
169

170
```typescript { .api }
171
function createStaticNavigation(
172
  tree: StaticNavigation<any, any, any>
173
): React.ForwardRefExoticComponent<
174
  StaticNavigationProps & React.RefAttributes<NavigationContainerRef<ParamListBase>>
175
>;
176

177
type StaticNavigationProps = Omit<
178
  React.ComponentProps<typeof NavigationContainer>,
179
  'linking' | 'children'
180
> & {
181
  linking?: Omit<LinkingOptions<ParamListBase>, 'config' | 'enabled'> & {
182
    enabled?: 'auto' | true | false;
183
    config?: Omit<NonNullable<LinkingOptions<ParamListBase>['config']>, 'screens'>;
184
  };
185
};
186
```
187

188
[Static Navigation](./static-navigation.md)
189

190
### Theming
191

192
Built-in theme system with light and dark variants, plus full customization support.
193

194
```typescript { .api }
195
const DefaultTheme: Theme;
196
const DarkTheme: Theme;
197

198
interface Theme {
199
  dark: boolean;
200
  colors: {
201
    primary: string;
202
    background: string;
203
    card: string;
204
    text: string;
205
    border: string;
206
    notification: string;
207
  };
208
  fonts: {
209
    regular: FontStyle;
210
    medium: FontStyle;
211
    bold: FontStyle;
212
    heavy: FontStyle;
213
  };
214
}
215

216
interface FontStyle {
217
  fontFamily: string;
218
  fontWeight: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
219
}
220
```
221

222
[Theming](./theming.md)
223

224
### Server-Side Rendering
225

226
Components and utilities for server-side rendering support in web applications.
227

228
```typescript { .api }
229
function ServerContainer(
230
  props: {
231
    location: { pathname: string; search?: string; hash?: string; };
232
    children: React.ReactNode;
233
  } & React.RefAttributes<ServerContainerRef>
234
): React.ReactElement;
235

236
interface ServerContainerRef {
237
  getCurrentOptions(): Record<string, any> | undefined;
238
}
239
```
240

241
[Server-Side Rendering](./server-side-rendering.md)
242

243
## Types
244

245
```typescript { .api }
246
interface DocumentTitleOptions {
247
  enabled?: boolean;
248
  formatter?: (
249
    options: Record<string, any> | undefined,
250
    route: Route<string> | undefined
251
  ) => string;
252
}
253

254
type ScrollableWrapper =
255
  | { scrollToTop(): void }
256
  | { scrollTo(options: { x?: number; y?: number; animated?: boolean }): void }
257
  | { scrollToOffset(options: { offset: number; animated?: boolean }): void }
258
  | { scrollResponderScrollTo(options: { x?: number; y?: number; animated?: boolean }): void }
259
  | { getScrollResponder(): React.ReactNode | ScrollView }
260
  | { getNode(): ScrollableWrapper }
261
  | null;
262
```