|
| 1 | +--- |
| 2 | +title: 2.0 release candidate |
| 3 | +author: Core Team |
| 4 | +authorURL: https://twitter.com/reactnavigation |
| 5 | +--- |
| 6 | + |
| 7 | +Exactly two months after the release of React Navigation 1.0, we are close to another major version release. We’d like to invite developers that use the library to give the release candidate a try in your app and let us know if you encounter any issues. |
| 8 | + |
| 9 | +We’re bumping the major version because some of the changes in this release are backwards incompatible. This is not a comprehensive changelog - that will come with the 2.0 proper release; the following is a list of the breaking changes, suggestions for how you can update your app to accommodate them, notice of deprecations, and some of my favourite new features. |
| 10 | + |
| 11 | +# Breaking changes |
| 12 | + |
| 13 | +## `navigate(routeName)` in StackNavigator is “less pushy” |
| 14 | + |
| 15 | +In 1.x, `navigate(routeName)` and `push(routeName)` were very similar: every time you called `navigate(routeName)` it would push a new route to the stack, regardless. Now `navigate(routeName)` will first try to find an existing instance of the route and jump to that if it exists, otherwise it will push the route to the stack. |
| 16 | + |
| 17 | +To update your app for this change you may need to change `navigate` to `push` in places where you would like to push a new route every time. Alternatively, you could consider using a `key`: `navigate({routeName: ‘MyRoute’, key: data.uniqueId, params: data})`. [Read more about navigation with keys](). |
| 18 | + |
| 19 | +Read more about this in [RFC 4](https://github.com/react-navigation/rfcs/blob/master/text/0004-less-pushy-navigate.md). |
| 20 | + |
| 21 | +## `push` now propagates between routers like `navigate` |
| 22 | + |
| 23 | +Previously, `push` only applied to the deepest active stack router. This meant that if you had Stack A > Stack B and Stack B fired `push(‘MyRoute’)`, even if Stack B does not have a route with the name `’MyRoute’` and Stack A does, the screen would not be pushed. We made this change to accommodate for the “less pushy” navigate behavior. |
| 24 | + |
| 25 | +When updating your app, you may want to double check where you use `push`to ensure that this doesn’t impact the expected behavior of your app. |
| 26 | + |
| 27 | +## Shallow navigation options |
| 28 | + |
| 29 | +A common source of confusion for developers working with React Navigation has been around `navigationOptions` resolution. For example, if you have a stack navigator with a header, and a drawer inside of that stack, then in some circumstances the title of the stack would change every time you change screens in the drawer. This is because the stack navigator would crawl into child navigators and pull `navigationOptions` off of the deepest active screen. As of 2.0, this no longer happens: navigators will only look at their direct children for `navigationOptions`. Read more about this in [RFC 5](https://github.com/react-navigation/rfcs/blob/master/text/0005-shallow-navigation-options.md). |
| 30 | + |
| 31 | +## New API for creating navigators |
| 32 | + |
| 33 | +This does not impact most users, but if you have any custom navigators in your app, read on. Read more about the changes in [RFC 2](https://github.com/react-navigation/rfcs/blob/master/text/0002-navigator-view-api.md). Also read the [custom navigators documentation](https://v2.reactnavigation.org/docs/en/custom-navigators.html). |
| 34 | + |
| 35 | +## Drawer routes have been replaced with actions |
| 36 | + |
| 37 | +Rather than opening a drawer with `navigation.navigate(‘DrawerOpen’)`, you can now call `navigation.openDrawer()`. Other methods are `closeDrawer()` and `toggleDrawer()`. |
| 38 | + |
| 39 | +## Navigation actions API overhaul |
| 40 | + |
| 41 | +In 1.x, functions on the `navigation` were not contextual - they would be the same regardless of whether your screen was inside of a drawer, a stack, a tab navigator, etc. In 2.0 the functions that are available to you on the `navigation` prop depend on the navigators that it corresponds to. If your screen is inside of both a stack and a drawer navigator, you will have helpers for both -- `push` and `openDrawer`, for example. |
| 42 | + |
| 43 | +Given that we only exposed generic helpers (`navigate`, `goBack`) and helpers specific to the stack in 1.x, this would only impact you if you attempted to use the stack helpers from outside of a stack. For example, if you had a tab navigator with a stack in tab A and just a plain screen in tab B, then tried to `push` a route from the screen in tab B, `push` would not be available. Keep this in mind when you update your app if it follows this type of structure. |
| 44 | + |
| 45 | +One of the big improvements you get from this is that you can now add your own helpers to the `navigation` prop! Read more in [RFC 6](https://github.com/react-navigation/rfcs/blob/master/text/0006-action-creators.md). |
| 46 | + |
| 47 | +# Deprecations |
| 48 | + |
| 49 | +The following APIs are deprecated and will be removed in 3.0. |
| 50 | + |
| 51 | +## XNavigator is now named createXNavigator |
| 52 | + |
| 53 | +``` |
| 54 | +import { createStackNavigator } from ‘react-navigation’; |
| 55 | +createStackNavigator({routeName: Screen}); |
| 56 | +``` |
| 57 | + |
| 58 | +This change was made to improve the ease of learning and understanding the library. The navigator constructors are functions that return components (HOCs), and that was not previously very well communicated by the name. |
| 59 | + |
| 60 | +## `TabNavigator` has been split up into more focused navigators |
| 61 | + |
| 62 | +`TabNavigator` (now `createTabNavigator` as per above) was a frequent source of confusion for users because it would use a bottom tab bar on iOS and a top tab bar on Android by default. Additionally, some of the configuration properties applied to the bottom tab bar, and others to the top tab bar. The equivalent components are now: `createBottomTabNavigator` and `createMaterialTopTabNavigator`. We’ve also introduced a new type of tab navigator, `createMaterialBottomTabNavigator` - a material design styled bottom tab bar based navigator from [react-native-paper](https://github.com/callstack/react-native-paper). Thank you [satya164](http://github.com/satya164) for your great work on this! |
| 63 | + |
| 64 | +# New feature highlights |
| 65 | + |
| 66 | +- State persistence - automatically save state and reload it when the app restarts. See https://v2.reactnavigation.org/docs/en/state-persistence.html |
| 67 | +- Transitions between screens in stack with headers and without headers now animates as expected on iOS. https://github.com/react-navigation/react-navigation/pull/3821. Thanks [skevy](https://github.com/skevy)! |
| 68 | +- As mentioned above, `createMaterialBottomNavigator` is a new navigator type that provides the material design bottom tab bar pattern. |
0 commit comments