Skip to content

Commit 06f7401

Browse files
satya164satya164
committed
Improve standard navigation docs
1 parent 9abd846 commit 06f7401

2 files changed

Lines changed: 297 additions & 59 deletions

File tree

‎versioned_docs/version-7.x/standard-navigator.md‎

Lines changed: 147 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -51,13 +51,130 @@ Your package exports can point to those entry points:
5151
}
5252
```
5353

54+
To get React Navigation types, you can add `@react-navigation/native` as a `devDependency` and an optional `peerDependency`:
55+
56+
```json
57+
{
58+
"devDependencies": {
59+
"@react-navigation/native": "^7.0.0"
60+
},
61+
"peerDependencies": {
62+
"@react-navigation/native": ">= 7.0.0"
63+
},
64+
"peerDependenciesMeta": {
65+
"@react-navigation/native": {
66+
"optional": true
67+
}
68+
}
69+
}
70+
```
71+
5472
## Standard navigator implementation
5573

5674
The standard navigator file should export the navigator object created with `createStandardNavigator`. This file shouldn't import React Navigation or Expo Router APIs.
5775

5876
To create a standard navigator, use the `createStandardNavigator` function from `standard-navigation`, and pass it a component that renders the desired UI.
5977

60-
Example:
78+
The basic shape looks like this:
79+
80+
```tsx
81+
export type MyTabOptions = {
82+
// screen options type
83+
};
84+
85+
export type MyTabEventMap = {
86+
// event map type
87+
};
88+
89+
export type MyTabNavigatorProps = {
90+
// additional navigator props type
91+
};
92+
93+
export const MyTabNavigator = createStandardNavigator<
94+
MyTabOptions,
95+
MyTabEventMap,
96+
MyTabNavigatorProps
97+
>(({ state, descriptors, actions, emitter, ...props }) => {
98+
// render the navigator UI using the state and descriptors
99+
// use actions to perform navigation and emitter to emit events
100+
});
101+
```
102+
103+
The object returned by `createStandardNavigator` can then be used in the React Navigation and Expo Router entry points to create the navigators for each library.
104+
105+
The `createStandardNavigator` function accepts three generic arguments:
106+
107+
- **`MyTabOptions`**
108+
109+
The type of the options available for each screen. It's a record of option names to their types.
110+
e.g.:
111+
112+
```ts
113+
type MyTabOptions = {
114+
title?: string;
115+
};
116+
```
117+
118+
- **`MyTabEventMap`**
119+
120+
The type of the events that can be emitted by the navigator. It's a mapping of event names to event data and whether the event can be prevented.
121+
e.g.:
122+
123+
```ts
124+
type MyTabEventMap = {
125+
tabPress: {
126+
data: { isAlreadyFocused: boolean };
127+
canPreventDefault: true;
128+
};
129+
};
130+
```
131+
132+
- **`MyTabNavigatorProps`**
133+
134+
The type of any additional props accepted by the navigator.
135+
136+
The callback receives `state`, `descriptors`, `actions`, and `emitter` from the navigation library integration:
137+
138+
- **`state`**
139+
140+
The state object for the navigator. Includes:
141+
- `state.index`: The index of the currently focused route.
142+
- `state.routes`: An array of route objects, each with `key`, `name`, `params` and `href` properties.
143+
144+
For stack navigators, `state.routes` array contains the history of visited screens until `state.index`, and the route objects after `state.index` represent [preloaded](navigation-actions.md#preload) routes.
145+
146+
- **`descriptors`**
147+
148+
An object mapping route keys to their descriptors. `descriptors[route.key]` will give you the descriptor for a specific route, which includes:
149+
- `descriptors[route.key].options`: The options for the route.
150+
- `descriptors[route.key].render()`: Function that returns the react element to render for the route.
151+
152+
- **`actions`**
153+
154+
An object with functions to perform navigation actions. Available actions are:
155+
- `actions.navigate(name, params)`: Navigate to a route with the given name and params.
156+
- `actions.back()`: Go back to the previous route in history.
157+
158+
- **`emitter`**
159+
160+
An object with a function to emit events from the navigator. The `emitter.emit(...)` function accepts an object with the following properties:
161+
- `type`: The name of the event to emit, one of the keys in the event map type.
162+
- `target`: The key of the route that is the target of the event, i.e. the route that can listen for the event.
163+
- `data`: An object with any additional data to include with the event.
164+
- `canPreventDefault`: A boolean indicating whether listeners can call `event.preventDefault()` to prevent the default behavior associated with the event.
165+
166+
Example:
167+
168+
```ts
169+
emitter.emit({
170+
type: 'tabPress',
171+
target: route.key,
172+
canPreventDefault: true,
173+
data: { isAlreadyFocused: isFocused },
174+
});
175+
```
176+
177+
A basic implementation of a tab navigator could look like this:
61178

62179
```tsx title="src/MyTabNavigator.tsx"
63180
import * as React from 'react';
@@ -137,29 +254,43 @@ export const MyTabNavigator = createStandardNavigator<
137254
});
138255
```
139256

140-
The `createStandardNavigator` function accepts three generic arguments:
257+
## React Navigation entry point
141258

142-
- `MyTabOptions` - The type of the options available for each screen.
143-
- `MyTabEventMap` - The type of the events that can be emitted by the navigator.
144-
- `MyTabNavigatorProps` - The type of any additional props accepted by the navigator.
259+
The React Navigation entry point should wrap the standard navigator with `createStandardNavigationFactories` from `@react-navigation/native`.
145260

146-
The callback receives `state`, `descriptors`, `actions`, and `emitter` from the navigation library integration:
261+
The basic shape looks like this:
147262

148-
- `state.routes` contains `{ key, name, params, href }` objects.
149-
- `descriptors[route.key].options` contains the screen options.
150-
- `descriptors[route.key].render()` renders the screen.
151-
- `actions.navigate(name, params)` and `actions.back()` perform navigation.
152-
- `emitter.emit(...)` emits navigator events to screen listeners.
263+
```ts
264+
interface MyTabTypeBag extends StandardNavigationTypeBagBase {
265+
State: TabNavigationState<this['ParamList']>;
266+
ActionHelpers: TabActionHelpers<this['ParamList']>;
267+
ScreenOptions: MyTabOptions;
268+
EventMap: MyTabEventMap;
269+
RouterOptions: TabRouterOptions;
270+
}
153271

154-
:::note
272+
const { createNavigator, createScreen } = createStandardNavigationFactories<
273+
MyTabTypeBag,
274+
MyTabNavigatorProps
275+
>(MyTabNavigator, TabRouter);
276+
```
155277

156-
For stack navigators, `state.routes` array contains the history of visited screens until `state.index`, and the route objects after `state.index` represent [preloaded](navigation-actions.md#preload) routes.
278+
The `createStandardNavigationFactories` function accepts two generic arguments:
157279

158-
:::
280+
- The type bag for the navigator (e.g. `MyTabTypeBag`), which includes the state, action helpers, screen options, event map, and router options types.
281+
- The type of any additional props accepted by the navigator (e.g. `MyTabNavigatorProps`).
159282

160-
## React Navigation entry point
283+
It accepts 3 arguments:
161284

162-
The React Navigation entry point should wrap the standard navigator with `createStandardNavigationFactories` from `@react-navigation/native`:
285+
- The standard navigator component.
286+
- The router factory function from React Navigation (e.g. `TabRouter`, `StackRouter`, etc.).
287+
- An optional function to map `{ navigation, state }` to custom props for the navigator component, in case you need any specific state or action helpers not available in the standard ones.
288+
289+
It returns an object with `createNavigator` and `createScreen` functions that can be used to create the navigator and screens for React Navigation. These should be exported from the entry point.
290+
291+
Additionally, you can export custom navigation prop and screen prop types (e.g. `MyTabNavigationProp` and `MyTabScreenProps`) that can be used by consumers for type annotations.
292+
293+
A basic implementation of the React Navigation entry point could look like this:
163294

164295
```tsx title="src/react-navigation.tsx"
165296
import {
@@ -221,21 +352,6 @@ export const {
221352
);
222353
```
223354

224-
The `createStandardNavigationFactories` function accepts two generic arguments:
225-
226-
- The type bag for the navigator (e.g. `MyTabTypeBag`), which includes the state, action helpers, screen options, event map, and router options types.
227-
- The type of any additional props accepted by the navigator (e.g. `MyTabNavigatorProps`).
228-
229-
It accepts 3 arguments:
230-
231-
- The standard navigator component.
232-
- The router factory function from React Navigation (e.g. `TabRouter`, `StackRouter`, etc.).
233-
- An optional function to map `{ navigation, state }` to custom props for the navigator component, in case you need any specific state or action helpers not available in the standard ones.
234-
235-
It returns an object with `createNavigator` and `createScreen` functions that can be used to create the navigator and screens for React Navigation. These should be exported from the entry point.
236-
237-
Additionally, you can export custom navigation prop and screen prop types (e.g. `MyTabNavigationProp` and `MyTabScreenProps`) that can be used by consumers for type annotations.
238-
239355
Consumers can then use the React Navigation entry point:
240356

241357
```tsx static2dynamic

0 commit comments

Comments
 (0)