|
| 1 | +--- |
| 2 | +title: React Navigation 6.0 |
| 3 | +author: Satyajit Sahoo |
| 4 | +author_url: https://twitter.com/satya164 |
| 5 | +author_title: Core Team |
| 6 | +author_image_url: https://avatars2.githubusercontent.com/u/1174278?s=200&v=4 |
| 7 | +tags: [release, announcement] |
| 8 | +--- |
| 9 | + |
| 10 | +The documentation is now live at [reactnavigation.org](https://reactnavigation.org), and v5 lives [here](/docs/5.x/getting-started). |
| 11 | + |
| 12 | +React Navigation 6 keeps mostly the same core API as React Navigation 5, and you can think of it as further polishing what was in React Navigation 5. Let's talk about the highlights of this release in this blog post. |
| 13 | + |
| 14 | +<!--truncate--> |
| 15 | + |
| 16 | +## Highlights |
| 17 | + |
| 18 | +### More flexible navigators |
| 19 | + |
| 20 | +Navigators accept many of their customization options as props, which means we can’t customize them based on the active screen. To make this level of control possible, we needed to move these props to options that you can configure per screen. |
| 21 | + |
| 22 | +In React Navigation 6, many of these props are now screen options. The most significant changes are `tabBarOptions` and `drawerContentOptions`, which now all live on `options` instead. For example: |
| 23 | + |
| 24 | +```js |
| 25 | +// Before (v5) |
| 26 | +<Tab.Navigator |
| 27 | + tabBarOptions={{ |
| 28 | + inactiveTintColor: 'rgba(255, 255, 255, 0.5)', |
| 29 | + activeTintColor: '#fff', |
| 30 | + style: { |
| 31 | + position: 'absolute', |
| 32 | + borderTopColor: 'rgba(0, 0, 0, .2)', |
| 33 | + }, |
| 34 | + }} |
| 35 | +> |
| 36 | +``` |
| 37 | + |
| 38 | +```js |
| 39 | +// After (v6) |
| 40 | +<Tab.Navigator |
| 41 | + screenOptions={{ |
| 42 | + tabBarInactiveTintColor: 'rgba(255, 255, 255, 0.5)', |
| 43 | + tabBarActiveTintColor: '#fff', |
| 44 | + tabBarStyle: { |
| 45 | + position: 'absolute', |
| 46 | + borderTopColor: 'rgba(0, 0, 0, .2)', |
| 47 | + }, |
| 48 | + }} |
| 49 | +> |
| 50 | +``` |
| 51 | + |
| 52 | +See [deprecations](/docs/upgrading-from-5.x#deprecations) for more details. |
| 53 | + |
| 54 | +### Elements library |
| 55 | + |
| 56 | +We extracted some of the components and helpers used across various navigators in React Navigation and published them under a new package called [`@react-navigation/elements`](/docs/elements). It can be useful if you're building your own navigator, or just want to reuse some of the components in your app. |
| 57 | + |
| 58 | +Currently only a small set of components are exported, but there are more to come. |
| 59 | + |
| 60 | +### Simplified APIs for existing functionality |
| 61 | + |
| 62 | +We simplified many APIs with React Navigation 6 to address common use cases. For example: |
| 63 | + |
| 64 | +- Single option to use a modal presentation style and transparent modal with [`presentation`](/docs/stack-navigator#presentation) |
| 65 | +- Custom header doesn't require setting `headerMode="screen"` manually anymore |
| 66 | +- The `useHeaderHeight` hook now ignores hidden headers and returns the height of the closest visible header in parent |
| 67 | +- New option to set a [custom background](/docs/bottom-tab-navigator#tabbarbackground) (such as `BlurView`) for tab bar without having to use a custom tab bar |
| 68 | +- New API to manage ref on the container [(`createNavigationContainerRef` and `useNavigationContainerRef`)](/docs/navigating-without-navigation-prop) |
| 69 | + |
| 70 | +### New `Group` component for organization |
| 71 | + |
| 72 | +The [`Group`](/docs/group) component helps you organize screens inside your navigators and share common `screenOptions` between the `Group`s. Passing `screenOptions` to a group configures all the screens inside that group to use these options. You can override `Group` options by passing `options` to each Screen component, similar to how you can with `screenOptions` on Navigator. You can also nest `Group` components inside other `Group` components. They are lightweight and don’t render anything - like fragments, so they won’t affect performance. |
| 73 | + |
| 74 | +In this code snippet, you can see that we group regular screens under one group and modal screens under another group: |
| 75 | + |
| 76 | +```js |
| 77 | +function App() { |
| 78 | + return ( |
| 79 | + <Stack.Navigator> |
| 80 | + <Stack.Group> |
| 81 | + <Stack.Screen name="Home" component={HomeScreen} /> |
| 82 | + <Stack.Screen name="Details" component={DetailsScreen} /> |
| 83 | + </Stack.Group> |
| 84 | + <Stack.Group screenOptions={{ presentation: 'modal' }}> |
| 85 | + <Stack.Screen |
| 86 | + name="CreatePost" |
| 87 | + component={CreatePostScreen} |
| 88 | + /> |
| 89 | + </Stack.Group> |
| 90 | + </Stack.Navigator> |
| 91 | + ); |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +### Headers by default in Bottom Tabs & Drawer |
| 96 | + |
| 97 | +Developers often want to show a header for screens inside of drawers and bottom tabs. To do this, we had to nest a stack navigator which provides a header, even if it was a navigator with just one screen. So we now show headers by default in screens of drawer and bottom tabs. No nesting necessary. |
| 98 | + |
| 99 | +We also export a [`Header`](/docs/elements#header) component in the new elements library to use anywhere in your components. |
| 100 | + |
| 101 | +### Native navigation by default |
| 102 | + |
| 103 | +Historically, React Navigation has been mostly JS based, with animations and gestures written in JavaScript on top of `react-native-gesture-handler`, and `react-native-reanimated` or `Animated`. While this works for a lot of apps, apps with heavy screens can suffer from poor performance, and some native features are difficult to re-create exactly (such as the large header on iOS). So, we wanted to address this by using native primitives for navigation. |
| 104 | + |
| 105 | +With React Navigation 5, we introduced [`@react-navigation/native-stack`](/docs/native-stack-navigator) package powered by [`react-native-screens`](https://github.com/software-mansion/react-native-screens), as well as a native backend for [`@react-navigation/material-top-tabs`](/docs/material-top-tab-navigator) powered by [`react-native-pager-view`](https://github.com/callstack/react-native-pager-view). |
| 106 | + |
| 107 | +In React Navigation 6, we made `@react-navigation/native-stack` the default choice for setting up Stack navigation. It uses `UINavigationController` on iOS and Fragments on Android to implement navigation natively. We also focused a lot on aligning the API of `@react-navigation/native-stack` with `@react-navigation/stack` so that it’ll be easier to switch between them. |
| 108 | + |
| 109 | +> While `@react-navigation/native-stack` is now used as the default choice in the documentation, it doesn't replace `@react-navigation/stack`. Both packages are maintained and are valid options for your projects. If you're currently using `@react-navigation/stack`, you can keep using it. You don't need to move to `@react-navigation/native-stack` unless you really want to. |
| 110 | +
|
| 111 | +Similarly, we switched `@react-navigation/material-top-tabs` to use `react-native-pager-view` by default. |
| 112 | + |
| 113 | +### Better type-safety |
| 114 | + |
| 115 | +React Navigation 5’s TypeScript support was much better than React Navigation 4; but, some things such as `useNavigation` were still untyped by default. |
| 116 | + |
| 117 | +In React Navigation 6, you don’t need to annotate `useNavigation` to get autocompletion and type checking. This is possible by defining a type for the screens globally using declaration merging: |
| 118 | + |
| 119 | +```js |
| 120 | +declare global { |
| 121 | + namespace ReactNavigation { |
| 122 | + interface RootParamList { |
| 123 | + Home: undefined; |
| 124 | + Profile: { userId: string }; |
| 125 | + NotFound: undefined; |
| 126 | + } |
| 127 | + } |
| 128 | +} |
| 129 | +``` |
| 130 | + |
| 131 | +You can read [more about it in our TypeScript docs](/docs/typescript#specifying-default-types-for-usenavigation-link-ref-etc). |
| 132 | + |
| 133 | +### Flipper plugin |
| 134 | + |
| 135 | +Our new [Flipper](https://fbflipper.com/) plugin includes similar functionality to the currently available Redux Devtools Extensions integration. You can see all navigation actions, and jump back and forth between earlier and new navigation states. In addition, it also includes a tab to test your linking configuration. |
| 136 | + |
| 137 | +Since the dev tools is built from scratch, we’re now free to add new features to make debugging easier in future. |
| 138 | + |
| 139 | +One advantage of the Flipper plugin over Redux Devtools Extension is that it doesn’t need Chrome Debugger to work. Since Chrome Debugger can sometimes affect performance and even potentially change behavior, we think this is a more reliable solution. |
| 140 | + |
| 141 | + |
| 142 | + |
| 143 | + |
| 144 | + |
| 145 | +See the [guide for setting it up](/docs/devtools#useflipper) for more details. Note that Flipper support in Expo managed apps requires a [Custom Development Client](https://docs.expo.dev/clients/introduction/) and it does not work in Expo Go at the time of writing. |
| 146 | + |
| 147 | +## Upgrading |
| 148 | + |
| 149 | +While React Navigation 6 doesn't introduce changes of the same magnitude as React Navigation 5, there are still some breaking changes. It is possible, however, to mix packages from React Navigation 5 and React Navigation 6 (with a few caveats) so that you can gradually upgrade packages. |
| 150 | + |
| 151 | +See the [upgrade guide](/docs/upgrading-from-5.x) for a full list of changes and more details. |
| 152 | + |
| 153 | +## Sponsor us |
| 154 | + |
| 155 | +If React Navigation helps you to deliver value to your customers, it'd awesome a lot if you could sponsor us. Sponsorships will help us to move more quickly towards our goal of building the best cross-platform navigation library and continue to provide timely support for bug reports in our GitHub issues. |
| 156 | + |
| 157 | +👉 [Visit our GitHub Sponsors page](https://github.com/sponsors/react-navigation) 👈 |
0 commit comments