Update docs for getId

Author: satya164

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

@@ -282,7 +282,7 @@ In a stack navigator ([stack](stack-navigator.md) or [native stack](native-stack
 
 - 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#id) prop is specified, and another screen in the stack has the same ID, it will navigate to that screen and update its params instead.
+- If the [`getId`](screen.md#id) prop is specified, and another screen in the stack has the same ID, it will bring that screen to focus and update its params instead.
 
 <details>
 <summary>Advanced usage</summary>

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

@@ -248,40 +248,6 @@ In a stack navigator ([stack](stack-navigator.md) or [native stack](native-stack
 - If the [`getId`](screen.md#id) prop is specified, and another screen in the stack has the same ID, it will bring that screen to focus and update its params instead.
 - If none of the above conditions match, it'll push a new screen to the stack.
 
-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#id) prop.
-
-For example, say you have specified a `getId` prop for `Profile` screen:
-
-<Tabs groupId="config" queryString="config">
-<TabItem value="static" label="Static" default>
-
-```js
-const Tabs = createBottomTabNavigator({
-  screens: {
-    Profile: {
-      screen: ProfileScreen,
-      getId: ({ params }) => params.userId,
-    },
-  },
-});
-```
-
-</TabItem>
-<TabItem value="dynamic" label="Dynamic">
-
-```js
-<Tab.Screen
-  name={Profile}
-  component={ProfileScreen}
-  getId={({ params }) => params.userId}
-/>
-```
-
-</TabItem>
-</Tabs>
-
-Now, if you have a stack with the history `Home > Profile (userId: bob) > Settings` and you call `navigate(Profile, { userId: 'alice' })`, the resulting screens will be `Home > Profile (userId: bob) > Settings > Profile (userId: alice)` since it'll add a new `Profile` screen as no matching screen was found.
-
 In a tab or drawer navigator, calling `navigate` will switch to the relevant screen if it's not focused already and update the params of the screen.
 
 ### `navigateDeprecated`
@@ -304,9 +270,8 @@ It takes the following arguments:
 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 a screen with the same name already exists in the stack, it will pop all the screens after it to go back to the existing screen.
-- If the [`getId`](screen.md#id) prop is specified, and another screen in the stack has the same ID, it will pop any screens to navigate to that screen and update its params instead.
-- If none of the above conditions match, it'll push a new screen to the stack.
+- If you're on a different screen, it will push the new screen onto the stack.
+- If the [`getId`](screen.md#id) prop is specified, and another screen in the stack has the same ID, it will bring that screen to focus and update its params instead.
 
 In a tab or drawer navigator, calling `navigate` will switch to the relevant screen if it's not focused already and update the params of the screen.
 

versioned_docs/version-7.x/screen.md

@@ -244,47 +244,14 @@ const Stack = createNativeStackNavigator({
 </TabItem>
 </Tabs>
 
-By default, `navigate('ScreenName', params)` updates the current screen if the screen name matches, otherwise adds a new screen in a stack navigator. So if you're on `ScreenName` and navigate to `ScreenName` again, it won't add a new screen even if the params are different - it'll update the current screen with the new params instead:
+In the above example, `params.userId` is used as an ID for the `Profile` screen with `getId`. This changes how the navigation works to ensure that the screen with the same ID appears only once in the stack.
 
-```js
-// Let's say you're on `Home` screen
-// Then you navigate to `Profile` screen with `userId: 1`
-navigation.navigate('Profile', { userId: 1 });
-
-// Now the stack will have: `Home` -> `Profile` with `userId: 1`
-
-// Then you navigate to `Profile` screen again with `userId: 2`
-navigation.navigate('Profile', { userId: 2 });
-
-// The stack will now have: `Home` -> `Profile` with `userId: 2`
-```
-
-If you specify `getId` and it doesn't return `undefined`, the screen is identified by both the screen name and the returned ID. That means that if you're on `ScreenName` and navigate to `ScreenName` again with different params - and return a different ID from the `getId` callback, it'll add a new screen to the stack:
-
-```js
-// Let's say you're on `Home` screen
-// Then you navigate to `Profile` screen with `userId: 1`
-navigation.navigate('Profile', { userId: 1 });
-
-// Now the stack will have: `Home` -> `Profile` with `userId: 1`
-
-// Then you navigate to `Profile` screen again with `userId: 2`
-navigation.navigate('Profile', { userId: 2 });
-
-// The stack will now have: `Home` -> `Profile` with `userId: 1` -> `Profile` with `userId: 2`
-```
-
-The `getId` callback can also be used to ensure that the screen with the same ID doesn't appear multiple times in the stack:
-
-```js
-// Let's say you have a stack with the screens: `Home` -> `Profile` with `userId: 1` -> `Settings`
-// Then you navigate to `Profile` screen with `userId: 1` again
-navigation.navigate('Profile', { userId: 1 });
-
-// Now the stack will have: `Home` -> `Profile` with `userId: 1`
-```
+Let's say you have a stack with the history `Home > Profile (userId: bob) > Settings`, consider following scenarios:
 
-In the above examples, `params.userId` is used as an ID, subsequent navigation to the screen with the same `userId` will navigate to the existing screen instead of adding a new one to the stack. If the navigation was with a different `userId`, then it'll add a new screen.
+- You call `navigate(Profile, { userId: 'bob' })`:
+  The resulting screens will be `Home > Settings > Profile (userId: bob)` since the existing `Profile` screen matches the ID.
+- You call `navigate(Profile, { userId: 'alice' })`:
+  The resulting screens will be `Home > Profile (userId: bob) > Settings > Profile (userId: alice)` since it'll add a new `Profile` screen as no matching screen was found.
 
 If `getId` is specified in a tab or drawer navigator, the screen will remount if the ID changes.
 

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

@@ -55,7 +55,12 @@ The methods now behave as follows:
 
 See [`popTo`](stack-actions.md#popto) for more details.
 
-To achieve a behavior similar to before with `navigate`, you can use the [`getId`](screen.md#id) prop in which case it'll go to the screen with the matching ID and push or pop screens accordingly.
+To achieve a behavior similar to before with `navigate`, you can use specify `pop: true` in the options:
+
+```diff lang=js
+- navigation.navigate('PreviousScreen', { foo: 42 });
++ navigation.navigate('PreviousScreen', { foo: 42 }, { pop: true });
+```
 
 To help with the migration, we have added a new method called `navigateDeprecated` which will behave like the old `navigate` method. You can replace your current `navigate` calls with [`navigateDeprecated`](navigation-object.md#navigatedeprecated) to gradually migrate to the new behavior:
 
@@ -80,8 +85,7 @@ It's problematic since:
 - None of the other actions support such usage.
 - Specifying a `key` is not type-safe, making it easy to cause bugs.
 
-In React Navigation 5, we added the [`getId`](screen.md#id) prop which can be used for similar use cases - and gives users full control since they provide the ID and it's not autogenerated by the
-library.
+In React Navigation 5, we added the [`getId`](screen.md#id) prop which can be used for similar use cases - and gives users full control since they provide the ID and it's not autogenerated by the library.
 
 So the `key` option is now being removed from the `navigate` action.