diff --git a/docs/navigation-key.md b/docs/navigation-key.md new file mode 100644 index 00000000000..2f2b227c4f4 --- /dev/null +++ b/docs/navigation-key.md @@ -0,0 +1,30 @@ +--- +id: navigation-key +title: Using the navigation key +sidebar_label: Using the navigation key +--- + +The `key` parameter comes up repeatedly across different navigation functions. Let's take a look at a summary of its use cases: + +### Usage with the [`navigate`](/docs/navigation-actions.html#navigate) call + +If no key is provided, `StackRouter` will behave as follows: + +* if a route with the given name already exists in the state, `StackRouter` will jump to the existing route, along with setting the new parameters. +* if no such route exists, `StackRouter` will push it onto the stack + +If, however, you want to push several instances of the same route, you can do so by providing a unique `key` parameter each time you call `navigate`, or you can use the `push` action available on `StackRouter`. See the related [RFC](https://github.com/react-navigation/rfcs/blob/master/text/0004-less-pushy-navigate.md) for more background. + +> Note: the behavior of `navigate` without a `key` is significantly different in the 1.x series of releases. Read more about it [here](https://gist.github.com/vonovak/ef72f5efe1d36742de8968ff6a708985). + +### Usage with [`reset`](/docs/navigation-actions.html#reset) + +When resetting, `key` is also optional and can be a string or `null`. If set, the navigator with the given key will reset. If `null`, the root navigator will reset. You can obtain a route's navigator key by calling `this.props.navigation.dangerouslyGetParent().state.key`. Reason why the function is called `dangerouslyGetParent` is to warn developers against overusing it to eg. get parent of parent and other hard-to-follow patterns. + +### Usage with [`replace`](/docs/navigation-actions.html#replace) + +With the `replace` navigation action, `key` is a required parameter used for identifying the route to be replaced. If you use the helper function `this.props.navigation.replace`, we will automatically substitute the key of the current route. + +### Usage with `goBack` + +Please refer to the [`goBack docs`](/docs/navigation-prop.html#goback-close-the-active-screen-and-move-back) for a detailed explanation. diff --git a/website/i18n/en.json b/website/i18n/en.json index 06ccb84666f..23362058462 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -71,6 +71,8 @@ "Moving between screens": "Moving between screens", "navigation-actions": "NavigationActions reference", "NavigationActions": "NavigationActions", + "navigation-key": "Using the navigation key", + "Using the navigation key": "Using the navigation key", "navigation-options": "navigation-options", "Configuring Navigation Options": "Configuring Navigation Options", "navigation-prop": "Navigation prop reference", diff --git a/website/sidebars.json b/website/sidebars.json index ac33c305823..18693d3057f 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -25,7 +25,8 @@ "deep-linking", "screen-tracking", "state-persistence", - "redux-integration" + "redux-integration", + "navigation-key" ], "Build your own Navigator": [ "custom-navigator-overview",