Rework behavior for preload

Author: satya164

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

@@ -450,8 +450,6 @@ The `preload` action allows preloading a screen in the background before navigat
 
 - `name` - _string_ - A destination name of the screen in the current or a parent navigator.
 - `params` - _object_ - Params to use for the destination route.
-- `options` - Options object containing the following properties:
-  - `reuse` - _boolean_ - Whether to reuse a matching preloaded or existing route instead of adding a new preloaded route. Defaults to `false`.
 
 ```js name="Common actions preload" snack static2dynamic
 import * as React from 'react';
@@ -553,7 +551,7 @@ Preloading a screen means that the screen will be rendered in the background. Al
 
 Depending on the navigator, `preload` may work differently:
 
-- In a stack navigator ([stack](stack-navigator.md), [native stack](native-stack-navigator.md)), the screen will be rendered off-screen and animated in when you navigate to it. If [`getId`](screen.md#id) is specified, it'll be used for the navigation to identify the preloaded screen. When `reuse` is `true`, a matching preloaded or existing route will be reused and its params will be updated.
+- In a stack navigator ([stack](stack-navigator.md), [native stack](native-stack-navigator.md)), the screen will be rendered off-screen and animated in when you navigate to it. Calling `preload` for a matching preloaded screen will update its params instead of adding a new preloaded screen. If [`getId`](screen.md#id) is specified, it'll be used for matching the preloaded screen. Otherwise, the screen name is used. If you need multiple preloaded instances of the same screen, use `getId` or [`reset`](#reset).
 - In a tab or drawer navigator ([bottom tabs](bottom-tab-navigator.md), [material top tabs](material-top-tab-navigator.md), [drawer](drawer-navigator.md), etc.), the existing screen will be rendered as if `lazy` was set to `false`. Calling `preload` on a screen that is already rendered will not have any effect.
 
 ### setParams

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

@@ -717,11 +717,9 @@ The `preload` method allows preloading a screen in the background before navigat
 
 - `name` - _string_ - A destination name of the screen in the current or a parent navigator.
 - `params` - _object_ - Params to use for the destination route.
-- `options` - Options object containing the following properties:
-  - `reuse` - _boolean_ - Whether to reuse a matching preloaded or existing route instead of adding a new preloaded route. Defaults to `false`.
 
 ```js
-navigation.preload('Profile', { user: 'jane' }, { reuse: true });
+navigation.preload('Profile', { user: 'jane' });
 ```
 
 <Tabs groupId="config" queryString="config">
@@ -917,7 +915,7 @@ Preloading a screen means that the screen will be rendered in the background. Al
 
 Depending on the navigator, `preload` may work slightly differently:
 
-- In a stack navigator ([stack](stack-navigator.md), [native stack](native-stack-navigator.md)), the screen will be rendered off-screen and animated in when you navigate to it. If [`getId`](screen.md#id) is specified, it'll be used for the navigation to identify the preloaded screen. When `reuse` is `true`, a matching preloaded or existing route will be reused and its params will be updated.
+- In a stack navigator ([stack](stack-navigator.md), [native stack](native-stack-navigator.md)), the screen will be rendered off-screen and animated in when you navigate to it. Calling `preload` for a matching preloaded screen will update its params instead of adding a new preloaded screen. If [`getId`](screen.md#id) is specified, it'll be used for matching the preloaded screen. Otherwise, the screen name is used. If you need multiple preloaded instances of the same screen, use `getId` or [`reset`](#reset).
 - In a tab or drawer navigator ([bottom tabs](bottom-tab-navigator.md), [material top tabs](material-top-tab-navigator.md), [drawer](drawer-navigator.md), etc.), the existing screen will be rendered as if `lazy` was set to `false`. Calling `preload` on a screen that is already rendered will not have any effect.
 
 ### `setParams`

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

@@ -339,6 +339,20 @@ If you use a custom navigator with `StackRouter` and do not want to change the s
 
 See [Navigation state](navigation-state.md) for more details.
 
+##### `preload` reuses matching preloaded routes instead of adding new ones
+
+Previously, calling `preload` for the same screen multiple times in a Stack or Native Stack Navigator would always preload a new instance of screen, leading to multiple preloaded instances. We found that this behavior was not intuitive and most people expected to have a single instance.
+
+In React Navigation 8, calling `preload` for a matching preloaded screen updates its params instead of adding another preloaded screen:
+
+```js
+navigation.preload('Profile', { user: 'jane' });
+```
+
+By default, preloaded screens are matched based on the screen name. The [`getId`](screen.md#id) prop can be used to match based on an ID derived from the params instead.
+
+See [`preload`](navigation-actions.md#preload) for more details.
+
 ##### Preloaded screens behave closer to regular screens
 
 Previously, when a screen was preloaded in Stack and Native Stack Navigators, there were a few restrictions:
@@ -852,18 +866,6 @@ This can be useful in various scenario:
 
 See [`pushParams` docs](navigation-actions.md#pushparams) for more details.
 
-### `preload` now supports a `reuse` option in Stack navigators
-
-Previously, calling `preload` for the same screen multiple times in a Stack or Native Stack Navigator would add another preloaded route.
-
-In React Navigation 8, you can pass `reuse: true` to update params for an existing preloaded or matching route instead:
-
-```js
-navigation.preload('Profile', { user: 'jane' }, { reuse: true });
-```
-
-See [`preload`](navigation-actions.md#preload) for more details.
-
 ### Themes now support `ColorValue` and CSS custom properties
 
 Previously, theme colors only supported string values. In React Navigation 8, theme colors now support `PlatformColor`, `DynamicColorIOS` on native, and CSS custom properties on Web for more flexibility.