Document popTo action

Author: satya164

static/examples/7.x/pop-to-top.js

@@ -23,7 +23,7 @@ function DetailsScreen({ navigation }) {
         title="Go to Details... again"
         onPress={() => navigation.push('Details')}
       />
-      <Button title="Go to Home" onPress={() => navigation.navigate('Home')} />
+      <Button title="Go to Home" onPress={() => navigation.popTo('Home')} />
       <Button title="Go back" onPress={() => navigation.goBack()} />
       <Button
         title="Go back to first screen in stack"

versioned_docs/version-7.x/native-stack-navigator.md

@@ -650,9 +650,11 @@ React.useEffect(() => {
 
 ### Helpers
 
+The nativestack navigator adds the following methods to the navigation prop:
+
 #### `replace`
 
-Replaces the current screen with a new screen in the stack. The method accepts following arguments:
+Replaces the current screen with a new screen in the stack. The method accepts the following arguments:
 
 - `name` - _string_ - Name of the route to push onto the stack.
 - `params` - _object_ - Screen params to pass to the destination route.
@@ -663,7 +665,7 @@ navigation.replace('Profile', { owner: 'Michaś' });
 
 #### `push`
 
-Pushes a new screen to top of the stack and navigate to it. The method accepts following arguments:
+Pushes a new screen to the top of the stack and navigate to it. The method accepts the following arguments:
 
 - `name` - _string_ - Name of the route to push onto the stack.
 - `params` - _object_ - Screen params to pass to the destination route.
@@ -680,6 +682,19 @@ Pops the current screen from the stack and navigates back to the previous screen
 navigation.pop();
 ```
 
+#### `popTo`
+
+Navigates back to a previous screen in the stack by popping screens after it. The method accepts the following arguments:
+
+- `name` - _string_ - Name of the route to navigate to.
+- `params` - _object_ - Screen params to pass to the destination route.
+
+If a matching screen is not found in the stack, this will pop the current screen and add a new screen with the specified name and params.
+
+```js
+navigation.popTo('Profile', { owner: 'Michaś' });
+```
+
 #### `popToTop`
 
 Pops all of the screens in the stack except the first one and navigates to it.

versioned_docs/version-7.x/navigating.md

@@ -133,7 +133,7 @@ On Android, React Navigation hooks in to the hardware back button and fires the
 
 :::
 
-Another common requirement is to be able to go back _multiple_ screens -- for example, if you are several screens deep in a stack and want to dismiss all of them to go back to the first screen. In this case, we know that we want to go back to `Home` so we can use `navigate('Home')` (not `push`! try that out and see the difference). Another alternative would be `navigation.popToTop()`, which goes back to the first screen in the stack.
+Another common requirement is to be able to go back _multiple_ screens -- for example, if you are several screens deep in a stack and want to dismiss all of them to go back to the first screen. In this case, we know that we want to go back to `Home` so we can use `popTo('Home')`. Another alternative would be `navigation.popToTop()`, which goes back to the first screen in the stack.
 
 <samp id="pop-to-top" />
 
@@ -146,7 +146,7 @@ function DetailsScreen({ navigation }) {
         title="Go to Details... again"
         onPress={() => navigation.push('Details')}
       />
-      <Button title="Go to Home" onPress={() => navigation.navigate('Home')} />
+      <Button title="Go to Home" onPress={() => navigation.popTo('Home')} />
       <Button title="Go back" onPress={() => navigation.goBack()} />
       <Button
         title="Go back to first screen in stack"
@@ -162,5 +162,5 @@ function DetailsScreen({ navigation }) {
 - `navigation.navigate('RouteName')` pushes a new route to the native stack navigator if it's not already in the stack, otherwise it jumps to that screen.
 - We can call `navigation.push('RouteName')` as many times as we like and it will continue pushing routes.
 - The header bar will automatically show a back button, but you can programmatically go back by calling `navigation.goBack()`. On Android, the hardware back button just works as expected.
-- You can go back to an existing screen in the stack with `navigation.navigate('RouteName')`, and you can go back to the first screen in the stack with `navigation.popToTop()`.
+- You can go back to an existing screen in the stack with `navigation.popTo('RouteName')`, and you can go back to the first screen in the stack with `navigation.popToTop()`.
 - The `navigation` prop is available to all screen components (components defined as screens in route configuration and rendered by React Navigation as a route).

versioned_docs/version-7.x/navigation-actions.md

@@ -23,11 +23,8 @@ The library exports several action creators under the `CommonActions` namespace.
 
 The `navigate` action allows to navigate to a specific route. It takes the following arguments:
 
-- `name` - _string_ - A destination name of the route that has been registered somewhere..
-- `key` - _string_ - The identifier for the route to navigate to. Navigate back to this route if it already exists..
-- `params` - _object_ - Params to merge into the destination route..
-
-The options object passed should at least contain a `key` or `name` property, and optionally `params`. If both `key` and `name` are passed, stack navigator will create a new route with the specified key if no matches were found.
+- `name` - _string_ - A destination name of the screen in the current or a parent navigator.
+- `params` - _object_ - Params to use for the destination route.
 
 <samp id="common-actions" />
 
@@ -44,9 +41,18 @@ navigation.dispatch(
 );
 ```
 
-In a [stack navigator](stack-navigator.md), calling `navigate` with a screen name will result in different behavior based on if the screen is already present or not. If the screen is already present in the stack's history, it'll go back to that screen and remove any screens after that. If the screen is not present, it'll push a new screen.
+In a stack navigator ([stack](stack-navigator.md) or [native stack](native-stack-navigator.md)), calling `navigate` with a screen name will have the following behavior:
+
+- If you're already on a screen with the same name, it will update its params and not push a new screen.
+- If you're on a different screen, it will push the new screen onto the stack.
+- If the [`getId`](screen.md#getid) prop is specified, and another screen in the stack has the same ID, it will navigate to that screen and update its params instead.
+
+The `navigate` action can also accepts an object as the argument with the following properties:
 
-By default, the screen is identified by its name. But you can also customize it to take the params into account by using the [`getId`](screen.md#getid) prop.
+- `name` - _string_ - A destination name of the screen in the current or a parent navigator
+- `params` - _object_ - Params to use for the destination route.
+- `merge` - _boolean_ - Whether we should merge the params of the current route with the provided `params`. Defaults to `false`.
+- `path` - _string_ - The path (from deep link or universal link) to associate with the screen.
 
 ### reset
 

versioned_docs/version-7.x/navigation-prop.md

@@ -30,6 +30,7 @@ If the navigator is a stack navigator, several alternatives to `navigate` and `g
   - `replace` - replace the current screen with a new one
   - `push` - push a new screen onto the stack
   - `pop` - go back in the stack
+  - `popTo` - go back to a specific screen in the stack
   - `popToTop` - go to the top of the stack
 
 See [Stack navigator helpers](stack-navigator.md#helpers) and [Native Stack navigator helpers](native-stack-navigator.md#helpers) for more details on these methods.
@@ -82,9 +83,11 @@ function HomeScreen({ navigation: { navigate } }) {
 }
 ```
 
-In a [native stack navigator](native-stack-navigator.md), calling `navigate` with a screen name will result in different behavior based on if the screen is already present or not. If the screen is already present in the stack's history, it'll go back to that screen and remove any screens after that. If the screen is not present, it'll push a new screen.
+In a stack navigator ([stack](stack-navigator.md) or [native stack](native-stack-navigator.md)), calling `navigate` with a screen name will have the following behavior:
 
-For example, if you have a stack with the history `Home > Profile > Settings` and you call `navigate(Profile)`, the resulting screens will be `Home > Profile` as it goes back to `Profile` and removes the `Settings` screen.
+- If you're already on a screen with the same name, it will update its params and not push a new screen.
+- If you're on a different screen, it will push the new screen onto the stack.
+- If the [`getId`](screen.md#getid) prop is specified, and another screen in the stack has the same ID, it will navigate to that screen and update its params instead.
 
 By default, the screen is identified by its name. But you can also customize it to take the params into account by using the [`getId`](screen.md#getid) prop.
 
@@ -114,26 +117,6 @@ function ProfileScreen({ navigation: { goBack } }) {
 }
 ```
 
-#### Going back from a specific screen
-
-Consider the following navigation stack history:
-
-```javascript
-navigation.navigate({ name: SCREEN, key: SCREEN_KEY_A });
-navigation.navigate({ name: SCREEN, key: SCREEN_KEY_B });
-navigation.navigate({ name: SCREEN, key: SCREEN_KEY_C });
-navigation.navigate({ name: SCREEN, key: SCREEN_KEY_D });
-```
-
-Now you are on _screen D_ and want to go back to _screen A_ (popping D, C, and B).
-Then you can use `navigate`:
-
-```js
-navigation.navigate({ key: SCREEN_KEY_A }); // will go to screen A FROM screen D
-```
-
-Alternatively, as _screen A_ is the top of the stack, you can use `navigation.popToTop()`.
-
 ### `reset`
 
 The `reset` method lets us replace the navigator state with a new state:

versioned_docs/version-7.x/stack-actions.md

@@ -76,6 +76,27 @@ const popAction = StackActions.pop(1);
 navigation.dispatch(popAction);
 ```
 
+### popTo
+
+The `popTo` action takes you back to a previous screen in the stack by the name. It also allows you to pass params to the route.
+
+If a matching screen is not found in the stack, this will pop the current screen and add a new screen with the specified name and params. This behavior is useful when the screen was opened from a deep link etc. and a previous screen with the name may or may not already be in the stack.
+
+The method accepts the following arguments:
+
+- `name` - _string_ - Name of the route to navigate to.
+- `params` - _object_ - Screen params to pass to the destination route.
+
+If a matching screen is not found in the stack, this will pop the current screen and add a new screen with the specified name and params. This behavior is useful when the screen was opened from a deep link and a previous screen with the name may or may not already be in the stack.
+
+```js
+import { StackActions } from '@react-navigation/native';
+
+const popToAction = StackActions.popTo('Profile', { user: 'jane' });
+
+navigation.dispatch(popToAction);
+```
+
 ### popToTop
 
 The `popToTop` action takes you back to the first screen in the stack, dismissing all the others. It's functionally identical to `StackActions.pop({n: currentIndex})`.

versioned_docs/version-7.x/stack-navigator.md

@@ -68,9 +68,9 @@ Then, you need to install and configure the libraries that are required by the s
 
 4. If you're on a Mac and developing for iOS, you also need to install the pods (via [Cocoapods](https://cocoapods.org/)) to complete the linking.
 
-  ```bash
-  npx pod-install ios
-  ```
+```bash
+npx pod-install ios
+```
 
 ## API Definition
 
@@ -457,7 +457,7 @@ The stack navigator adds the following methods to the navigation prop:
 
 #### `replace`
 
-Replaces the current screen with a new screen in the stack. The method accepts following arguments:
+Replaces the current screen with a new screen in the stack. The method accepts the following arguments:
 
 - `name` - _string_ - Name of the route to push onto the stack.
 - `params` - _object_ - Screen params to pass to the destination route.
@@ -468,7 +468,7 @@ navigation.replace('Profile', { owner: 'Michaś' });
 
 #### `push`
 
-Pushes a new screen to top of the stack and navigate to it. The method accepts following arguments:
+Pushes a new screen to the top of the stack and navigate to it. The method accepts the following arguments:
 
 - `name` - _string_ - Name of the route to push onto the stack.
 - `params` - _object_ - Screen params to pass to the destination route.
@@ -485,6 +485,19 @@ Pops the current screen from the stack and navigates back to the previous screen
 navigation.pop();
 ```
 
+#### `popTo`
+
+Navigates back to a previous screen in the stack by popping screens after it. The method accepts the following arguments:
+
+- `name` - _string_ - Name of the route to navigate to.
+- `params` - _object_ - Screen params to pass to the destination route.
+
+If a matching screen is not found in the stack, this will pop the current screen and add a new screen with the specified name and params.
+
+```js
+navigation.popTo('Profile', { owner: 'Michaś' });
+```
+
 #### `popToTop`
 
 Pops all of the screens in the stack except the first one and navigates to it.

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

@@ -37,7 +37,7 @@ The `navigationInChildEnabled` prop will be removed in the next major.
 
 Previously, `navigate` method navigated back if the screen already exists in the stack. We have seen many people get confused by this behavior.
 
-To avoid this confusion, we have removed the going back behavior from `navigate` and added a new method `popTo` to explicitly go back to a specific screen in the stack:
+To avoid this confusion, we have removed the going back behavior from `navigate` and added a [new method `popTo`](stack-actions.md#popto) to explicitly go back to a specific screen in the stack:
 
 ```diff
 - navigation.navigate('PreviousScreen', { foo: 42 });