Skip to content

Commit de3124f

Browse files
satya164satya164
committed
Update upgrade guide
1 parent 29f5745 commit de3124f

File tree

1 file changed

+201
-23
lines changed

1 file changed

+201
-23
lines changed

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

Lines changed: 201 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,33 @@ const theme = {
133133
134134
If you want to customize the fonts, see [the themes guide](themes.md) for more details.
135135
136+
### Encoding of params in path position is now more relaxed
137+
138+
Previously, params were always URL encoded with `encodeURIComponent` regardless of their position (e.g. query position such as `?user=jane` or path position such as `/users/jane`) when generating a link for a screen (e.g. URL on the Web). This made it hard to use special characters in the params.
139+
140+
Now, only the params in the query position are URL encoded. For the params in the path position, we only encode the characters that are not allowed in the path position.
141+
142+
With this change, it's easier to use special characters such as `@` in the path. For example, to have a URL such as `profile/@username`, you can use the following in the linking config:
143+
144+
```js
145+
const config = {
146+
prefixes: ['https://mysite.com'],
147+
config: {
148+
screens: {
149+
Profile: {
150+
path: 'profile/:username',
151+
parse: {
152+
username: (username) => username.replace(/^@/, ''),
153+
},
154+
stringify: {
155+
username: (username) => `@${username}`,
156+
},
157+
},
158+
},
159+
},
160+
};
161+
```
162+
136163
### The `Link` component and `useLinkProps` hook now use screen names instead of paths
137164

138165
Previously, the `Link` component and `useLinkProps` hook were designed to work with path strings via the `to` prop. But it had few issues:
@@ -281,6 +308,31 @@ Here is the full list of removed APIs:
281308
- `contentContainerStyle` - use `tabBarContentContainerStyle` option instead
282309
- `style` - use `tabBarStyle` option instead
283310
311+
### Various UI elements now follow Material Design 3 guidelines
312+
313+
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.
314+
315+
### Screens pushed on top of modals are now shown as modals in the Stack and Native Stack navigators
316+
317+
Previously, screens pushed on top of modals were shown as regular screens in the Stack and Native Stack navigators. This often caused glitchy animation on Stack Navigator and appeared behind the modal on Native Stack Navigator. This can be especially confusing if the user came to the screen from a deep link.
318+
319+
Now, screens pushed on top of modals are automatically shown as modals to avoid these issues. This behavior can be disabled by explicitly setting the `presentation` option to `card`:
320+
321+
```jsx
322+
<Stack.Screen
323+
name="MyModal"
324+
component={MyModalScreen}
325+
options={{
326+
// highlight-next-line
327+
presentation: 'card',
328+
}}
329+
/>
330+
```
331+
332+
### `animationEnabled` option is removed in favor of `animation` option in Stack Navigator
333+
334+
TODO
335+
284336
### `customAnimationOnGesture` is renamed to `animationMatchesGesture` in Native Stack Navigator
285337

286338
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`:
@@ -290,7 +342,7 @@ The `customAnimationOnGesture` option in Native Stack Navigator is renamed to `a
290342
+ <Stack.Navigator options={{ animationMatchesGesture: true }}>
291343
```
292344

293-
### Material Top Tab Navigator no longers requires installing `react-native-tab-view`
345+
### Material Top Tab Navigator no longer requires installing `react-native-tab-view`
294346

295347
Previously, `@react-navigation/material-top-tabs` required installing `react-native-tab-view` as a dependency in the project. We have now moved this package to the React Navigation monorepo and able to coordinate the releases together, so it's no longer necessary to install it separately.
296348

@@ -309,6 +361,10 @@ If you are using `@react-navigation/material-bottom-tabs` in your project, you c
309361
+ import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation';
310362
```
311363

364+
### The `unmountOnBlur` option is removed in favor of `popToTopOnBlur` in Bottom Tab Navigator
365+
366+
TODO
367+
312368
### The `tabBarTestID` option is renamed to `tabBarButtonTestID` in Bottom Tab Navigator
313369

314370
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`:
@@ -326,9 +382,9 @@ If you are using Reanimated 1 in your project, you'll need to upgrade to Reanima
326382

327383
If you're using Drawer Navigator on the Web, it'll now use CSS transitions instead of Reanimated for a smaller bundle size.
328384

329-
### Various UI elements now follow Material Design 3 guidelines
385+
### React Native Tab View now has a new API to specify various options
330386

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.
387+
TODO
332388

333389
## New features
334390

@@ -372,7 +428,43 @@ You can see examples for both the static and dynamic configuration APIs in the d
372428

373429
Go to ["Hello React Navigation"](hello-react-navigation.md?config=static) to start writing some code with the static API.
374430

375-
### Support a top-level `path` configuration in linking config
431+
### Improved TypeScript support for `options`, `listeners` etc
432+
433+
Previously, the `navigation` object received in `options` and `listeners` callbacks were typed as `any` and required manual type annotation. Now, the `navigation` object has a more accurate type based on the navigator it's used in, and the type annotation is no longer required.
434+
435+
We also export a new `XOptionsArgs` (where `X` is the navigator name, e.g. `StackOptionsArgs`, `BottomTabOptionsArgs` etc.) type which can be used to type the arguments of the `options` callback. This can be useful if you want to define the options callback separately.
436+
437+
```ts
438+
const options = ({
439+
route,
440+
}: StackOptionsArgs<RootStackParamList, 'Details'>) => {
441+
return {
442+
title: route.params.title,
443+
};
444+
};
445+
```
446+
447+
### The `options` callback now receives `theme` in its arguments
448+
449+
The `options` callback now receives the `theme` object to allow customizing the UI elements specified in the options:
450+
451+
```jsx
452+
<Stack.Screen
453+
name="Details"
454+
component={DetailsScreen}
455+
options={({ theme }) => ({
456+
headerRight: () => (
457+
<IconButton
458+
icon="dots-horizontal"
459+
onPress={() => {}}
460+
color={theme.colors.primary}
461+
/>
462+
),
463+
})}
464+
/>
465+
```
466+
467+
### Linking config now supports a top-level `path` property
376468

377469
The linking configuration now supports a top-level `path` configuration to define the base path for all the screens in the navigator:
378470

@@ -392,7 +484,11 @@ const linking = {
392484

393485
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`.
394486

395-
### Add a `layout` prop for Navigators
487+
### There's a new `usePreventRemove` hook that works with Native Stack Navigator
488+
489+
TODO
490+
491+
### Navigators now support a `layout` prop
396492

397493
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.:
398494

@@ -411,7 +507,7 @@ Navigators now support a `layout` prop. It can be useful for augmenting the navi
411507
</Stack.Navigator>
412508
```
413509

414-
### Add `layout` and `screenLayout` props for screens
510+
### Screens now support a `layout` and `screenLayout` props
415511

416512
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.
417513

@@ -463,9 +559,41 @@ Or with a group or navigator with `screenLayout`:
463559
</Stack.Group>
464560
```
465561

466-
### Add a `Button` component to Elements
562+
### Many navigators now support preloading screens
563+
564+
Many navigators now support preloading screens prior to navigating to them. This can be useful to improve the perceived performance of the app by preloading the screens that the user is likely to navigate to next. Preloading a screen will render it off-screen and execute its side-effects such as data fetching.
565+
566+
To preload a screen, you can use the `preload` method on the navigation object:
567+
568+
```js
569+
navigation.preload('Details', { id: 42 });
570+
```
571+
572+
Preloading is supported in the following navigators:
573+
574+
- Stack Navigator
575+
- Bottom Tab Navigator
576+
- Material Top Tab Navigator
577+
- Drawer Navigator
578+
579+
The Native Stack navigator doesn't currently support preloading screens.
580+
581+
### More UI elements are now links on the Web
467582

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:
583+
More built-in UI elements that trigger navigation now render `a` tags on the Web for better accessibility and SEO. This includes:
584+
585+
- Back button in the header
586+
- The tab buttons in material top tab navigator
587+
588+
UI elements such as the bottom tab bar and drawer items already rendered `a` tags on the Web.
589+
590+
### Elements library now includes many new components
591+
592+
The `@react-navigation/elements` package now includes new components that can be used in your app:
593+
594+
#### `Button`
595+
596+
The `Button` component has built-in support for navigating to screens, and renders an anchor tag on the Web when used for navigation:
469597

470598
```jsx
471599
<Button screen="Profile" params={{ userId: 'jane' }}>
@@ -487,18 +615,52 @@ It can also be used as a regular button:
487615
488616
The button follows the [Material Design 3 guidelines](https://m3.material.io/components/buttons/overview).
489617
490-
### Add `useAnimatedHeaderHeight` hook to Native Stack Navigator
618+
#### `HeaderButton`
491619
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:
620+
The `HeaderButton` component can be used to render buttons in the header with appropriate styling:
621+
622+
```js
623+
headerRight: ({ tintColor }) => (
624+
<HeaderButton
625+
accessibilityLabel="More options"
626+
onPress={() => {
627+
/* do something */
628+
}}
629+
>
630+
<MaterialCommunityIcons
631+
name="dots-horizontal-circle-outline"
632+
size={24}
633+
color={tintColor}
634+
/>
635+
</HeaderButton>
636+
),
637+
```
638+
639+
#### `Label`
640+
641+
The `Label` component can be used to render label text, such as the label in a tab bar button:
493642
494643
```jsx
495-
const headerHeight = useAnimatedHeaderHeight();
644+
<Label>Home</Label>
645+
```
496646
497-
return (
498-
<Animated.View style={{ transform: { translateY: headerHeight } }}>
499-
{/* ... */}
500-
</Animated.View>
501-
);
647+
### Bottom Tab Navigator can now show tabs on the side and top
648+
649+
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.
650+
651+
Similarly, showing tabs on the top is also supported which can be useful for Android TV or Apple TV apps.
652+
653+
You can use the `tabBarPosition` option to customize the position of the tabs:
654+
655+
```jsx
656+
<Tab.Navigator
657+
screenOptions={{
658+
// highlight-next-line
659+
tabBarPosition: 'left',
660+
}}
661+
>
662+
{/* ... */}
663+
</Tab.Navigator>
502664
```
503665
504666
### Bottom Tab Navigator now supports animations
@@ -518,23 +680,39 @@ You can use the `animation` option to customize the animations for the tab trans
518680
</Tab.Navigator>
519681
```
520682
521-
### Bottom Tab Navigator can now show tabs on the side
522-
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.
683+
### Stack Navigator now supports an `animation` option
524684
525-
You can use the `tabBarPosition` option to customize the position of the tabs:
685+
The `@react-navigation/stack` package now supports an `animation` option to customize the animations for the screen transitions:
526686
527687
```jsx
528-
<Tab.Navigator
688+
<Stack.Navigator
529689
screenOptions={{
530690
// highlight-next-line
531-
tabBarPosition: 'left',
691+
animation: 'slide_from_right',
532692
}}
533693
>
534694
{/* ... */}
535-
</Tab.Navigator>
695+
</Stack.Navigator>
696+
```
697+
698+
The `animation` option is an alternative to the `TransitionPresets` API, and is intended to make migrating between JS stack and native stack navigators easier.
699+
700+
### Native Stack Navigator now exports a `useAnimatedHeaderHeight` hook
701+
702+
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:
703+
704+
```jsx
705+
const headerHeight = useAnimatedHeaderHeight();
706+
707+
return (
708+
<Animated.View style={{ transform: { translateY: headerHeight } }}>
709+
{/* ... */}
710+
</Animated.View>
711+
);
536712
```
537713
714+
### Drawer Navigator now
715+
538716
### The drawer implementation is now available in `react-native-drawer-layout` as a standalone package
539717
540718
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.

0 commit comments

Comments
 (0)