Skip to content

Commit ee5a430

Browse files
satya164satya164
committed
Complete existing TODOs in upgrade guide
1 parent e322ee8 commit ee5a430

File tree

1 file changed

+247
-15
lines changed

1 file changed

+247
-15
lines changed

‎versioned_docs/version-7.x/upgrading-from-6.x.md

+247-15
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,43 @@ The `buildHref` method acts the same as the previously returned function. The ne
171171
172172
Note that this hook is intended to be primarily used by custom navigators and not by end users. For end users, the `Link` component and `useLinkProps` are the recommended way to navigate.
173173
174+
### Custom navigators now require more type information
175+
176+
Custom navigators now require more type information to work correctly so that we can provide better type-checking and autocompletion in TypeScript when using the navigator.
177+
178+
```diff lang=js
179+
- export const createMyNavigator = createNavigatorFactory<
180+
- MyNavigationState<ParamListBase>,
181+
- MyNavigationOptions,
182+
- MyNavigationEventMap,
183+
- typeof MyNavigator
184+
- >(MyNavigator);
185+
+ export function createMyNavigator<
186+
+ ParamList extends ParamListBase,
187+
+ NavigatorID extends string | undefined = undefined,
188+
+ TypeBag extends NavigatorTypeBagBase = {
189+
+ ParamList: ParamList;
190+
+ NavigatorID: NavigatorID;
191+
+ State: MyNavigationState<ParamList>;
192+
+ ScreenOptions: MyNavigationOptions;
193+
+ EventMap: MyNavigationEventMap;
194+
+ NavigationList: {
195+
+ [RouteName in keyof ParamList]: MyNavigationProp<
196+
+ ParamList,
197+
+ RouteName,
198+
+ NavigatorID
199+
+ >;
200+
+ };
201+
+ Navigator: typeof MyNavigator;
202+
+ },
203+
+ Config extends StaticConfig<TypeBag> | undefined =
204+
+ | StaticConfig<TypeBag>
205+
+ | undefined,
206+
+ >(config?: Config): TypedNavigator<TypeBag, Config> {
207+
+ return createNavigatorFactory(MyNavigator)(config);
208+
+ }
209+
```
210+
174211
### The flipper devtools plugin is now removed
175212
176213
Previously, we added a Flipper plugin for React Navigation to make debugging navigation easier. However, it has added significant maintenance overhead for us. The Flipper team hasn't been focused on React Native recently, so the overall experience of using Flipper with React Native has been poor.
@@ -246,7 +283,12 @@ Here is the full list of removed APIs:
246283

247284
### `customAnimationOnGesture` is renamed to `animationMatchesGesture` in Native Stack Navigator
248285

249-
TODO
286+
The `customAnimationOnGesture` option in Native Stack Navigator is renamed to `animationMatchesGesture` to better reflect its purpose. If you are using `customAnimationOnGesture` in your project, you can rename it to `animationMatchesGesture`:
287+
288+
```diff lang=js
289+
- <Stack.Navigator options={{ customAnimationOnGesture: true }}>
290+
+ <Stack.Navigator options={{ animationMatchesGesture: true }}>
291+
```
250292

251293
### Material Top Tab Navigator no longers requires installing `react-native-tab-view`
252294

@@ -269,46 +311,236 @@ If you are using `@react-navigation/material-bottom-tabs` in your project, you c
269311
270312
### The `tabBarTestID` option is renamed to `tabBarButtonTestID` in Bottom Tab Navigator
271313
272-
TODO
314+
The `tabBarTestID` option in Bottom Tab Navigator is renamed to `tabBarButtonTestID` to better reflect its purpose. If you are using `tabBarTestID` in your project, you can rename it to `tabBarButtonTestID`:
315+
316+
```diff lang=js
317+
- <Tab.Navigator tabBarOptions={{ tabBarTestID: 'test-id' }}>
318+
+ <Tab.Navigator tabBarOptions={{ tabBarButtonTestID: 'test-id' }}>
319+
```
320+
321+
### Drawer Navigator now requires Reanimated 2 or 3 on native platforms
322+
323+
Previously, `@react-navigation/drawer` supported both Reanimated 1 and Reanimated 2 APIs with the `useLegacyImplementation` option. This is now no longer supported and the `useLegacyImplementation` option is removed.
324+
325+
If you are using Reanimated 1 in your project, you'll need to upgrade to Reanimated 2 or 3 to use `@react-navigation/drawer`.
273326

274-
### Drawer Navigator no longer supports Reanimated 1
327+
If you're using Drawer Navigator on the Web, it'll now use CSS transitions instead of Reanimated for a smaller bundle size.
275328

276-
TODO
329+
### Various UI elements now follow Material Design 3 guidelines
330+
331+
Previously, the UI elements in React Navigation such as the header on platforms other than iOS, drawer, material top tabs etc. were following the Material Design 2 guidelines. We have now updated them to follow the Material Design 3 guidelines.
277332

278333
## New features
279334

280335
### Navigators now support a static configuration API
281336

282-
TODO
337+
React Navigation 5 introduced a dynamic API to support more flexible use cases. With React Navigation 7, we are re-introducing a static configuration API:
338+
339+
```js
340+
import { createNativeStackNavigator } from 'react-native-screens/native-stack';
341+
342+
const MyStack = createNativeStackNavigator({
343+
screens: {
344+
Home: {
345+
screen: HomeScreen,
346+
options: {
347+
title: 'My App',
348+
},
349+
},
350+
Details: {
351+
screen: DetailsScreen,
352+
linking: 'details/:id',
353+
},
354+
},
355+
});
356+
```
357+
358+
The static configuration API provides the following benefits:
359+
360+
- Simpler type-checking with TypeScript, it's not necessary to specify screens and their params separately.
361+
- Easier deep linking setup, the linking configuration can be defined next to the screen.
362+
363+
It's also possible to mix the static and dynamic configuration APIs. For example, you can use the static configuration API for the top-level navigators and the dynamic configuration API for the nested navigators where you need more flexibility.
364+
365+
:::note
366+
367+
The static configuration API doesn't replace the dynamic configuration API. Both APIs are equally supported and you can choose the one that fits your use case better.
368+
369+
:::
370+
371+
You can see examples for both the static and dynamic configuration APIs in the documentation by selecting the appropriate tab in the examples.
372+
373+
Go to ["Hello React Navigation"](hello-react-navigation.md?config=static) to start writing some code with the static API.
283374
284375
### Support a top-level `path` configuration in linking config
285376
286-
TODO
377+
The linking configuration now supports a top-level `path` configuration to define the base path for all the screens in the navigator:
378+
379+
```js
380+
const linking = {
381+
prefixes: ['https://mysite.com'],
382+
config: {
383+
// highlight-next-line
384+
path: 'app',
385+
screens: {
386+
Home: 'home',
387+
Details: 'details/:id',
388+
},
389+
},
390+
};
391+
```
392+
393+
This can be useful if your app lives under a subpath on the web. For example, if your app lives under `https://mysite.com/app`, you can define the `path` as `app` and the `Details` screen will be accessible at `https://mysite.com/app/details/42`.
394+
395+
### Add a `layout` prop for Navigators
396+
397+
Navigators now support a `layout` prop. It can be useful for augmenting the navigators with additional UI with a wrapper. The difference from adding a regular wrapper is that the code in `layout` callback has access to the navigator's state, options etc.:
398+
399+
```jsx
400+
<Stack.Navigator
401+
// highlight-start
402+
layout={({ children, state, descriptors, navigation }) => (
403+
<View style={styles.container}>
404+
<Breadcrumbs />
405+
{children}
406+
</View>
407+
)}
408+
// highlight-end
409+
>
410+
{/* ... */}
411+
</Stack.Navigator>
412+
```
287413
288-
### Support custom `layout` prop for Navigators
414+
### Add `layout` and `screenLayout` props for screens
289415
290-
TODO
416+
The `layout` prop makes it easier to provide things such as a global error boundary and suspense fallback for a group of screens without having to manually add HOCs for every screen separately.
291417
292-
### Add experimental API for handling deep link after authentication
418+
It can be used for a single screen with `layout`:
293419
294-
TODO
420+
```jsx
421+
<Stack.Screen
422+
name="MyScreen"
423+
component={MyScreenComponent}
424+
// highlight-start
425+
layout={({ children }) => (
426+
<ErrorBoundary>
427+
<React.Suspense
428+
fallback={
429+
<View style={styles.fallback}>
430+
<Text style={styles.text}>Loading…</Text>
431+
</View>
432+
}
433+
>
434+
{children}
435+
</React.Suspense>
436+
</ErrorBoundary>
437+
)}
438+
// highlight-end
439+
/>
440+
```
441+
442+
Or with a group or navigator with `screenLayout`:
443+
444+
```jsx
445+
<Stack.Group
446+
// highlight-start
447+
screenLayout={({ children }) => (
448+
<ErrorBoundary>
449+
<React.Suspense
450+
fallback={
451+
<View style={styles.fallback}>
452+
<Text style={styles.text}>Loading…</Text>
453+
</View>
454+
}
455+
>
456+
{children}
457+
</React.Suspense>
458+
</ErrorBoundary>
459+
)}
460+
>
461+
// highlight-end
462+
{/* screens */}
463+
</Stack.Group>
464+
```
295465
296466
### Add a `Button` component to Elements
297467
298-
TODO
468+
The `@react-navigation/elements` package now includes a `Button` component. It has built-in support for navigating to screens, and renders an anchor tag on the Web when used for navigation:
469+
470+
```jsx
471+
<Button screen="Profile" params={{ userId: 'jane' }}>
472+
View Jane's Profile
473+
<Button>
474+
```
475+
476+
It can also be used as a regular button:
477+
478+
```jsx
479+
<Button
480+
onPress={() => {
481+
/* do something */
482+
}}
483+
>
484+
Do something
485+
</Button>
486+
```
487+
488+
The button follows the [Material Design 3 guidelines](https://m3.material.io/components/buttons/overview).
299489
300490
### Add `useAnimatedHeaderHeight` hook to Native Stack Navigator
301491
302-
TODO
492+
The `@react-navigation/native-stack` package now exports a `useAnimatedHeaderHeight` hook. It can be used to animate content based on the header height changes - such as when the large title shrinks to a small title on iOS:
493+
494+
```jsx
495+
const headerHeight = useAnimatedHeaderHeight();
496+
497+
return (
498+
<Animated.View style={{ transform: { translateY: headerHeight } }}>
499+
{/* ... */}
500+
</Animated.View>
501+
);
502+
```
303503
304504
### Bottom Tab Navigator now supports animations
305505
306-
TODO
506+
The `@react-navigation/bottom-tabs` package now supports animations. This was one of the most requested features on our Canny board: [TabNavigator Custom Transition](https://react-navigation.canny.io/feature-requests/p/tabnavigator-custom-transition).
507+
508+
You can use the `animation` option to customize the animations for the tab transitions:
509+
510+
```jsx
511+
<Tab.Navigator
512+
screenOptions={{
513+
// highlight-next-line
514+
animation: 'fade',
515+
}}
516+
>
517+
{/* ... */}
518+
</Tab.Navigator>
519+
```
307520
308521
### Bottom Tab Navigator can now show tabs on the side
309522
310-
TODO
523+
The `@react-navigation/bottom-tabs` package now supports showing tabs on the side. This will make it easier to build responsive UIs for where you want to show tabs on the bottom on smaller screens and switch to a sidebar on larger screens.
524+
525+
You can use the `tabBarPosition` option to customize the position of the tabs:
526+
527+
```jsx
528+
<Tab.Navigator
529+
screenOptions={{
530+
// highlight-next-line
531+
tabBarPosition: 'left',
532+
}}
533+
>
534+
{/* ... */}
535+
</Tab.Navigator>
536+
```
311537
312538
### The drawer implementation is now available in `react-native-drawer-layout` as a standalone package
313539
314-
TODO
540+
The drawer implementation used in `@react-navigation/drawer` is now available as a standalone package called `react-native-drawer-layout`. This makes it easier to use the drawer implementation even if you're not using React Navigation, or if you want to use it without a navigator.
541+
542+
You can install it with:
543+
544+
```bash npm2yarn
545+
npm install react-native-drawer-layout
546+
```

0 commit comments

Comments
 (0)