Document popToTopOnBlur

versioned_docs/version-7.x/bottom-tab-navigator.md

@@ -413,12 +413,6 @@ When the tab bar is positioned on the `left` or `right`, it is styled as a sideb
 
 Whether this screens should render the first time it's accessed. Defaults to `true`. Set it to `false` if you want to render the screen on initial render.
 
-#### `unmountOnBlur`
-
-Whether this screen should be unmounted when navigating away from it. Unmounting a screen resets any local state in the screen as well as state of nested navigators in the screen. Defaults to `false`.
-
-Normally, we don't recommend enabling this prop as users don't expect their navigation history to be lost when switching tabs. If you enable this prop, please consider if this will actually provide a better experience for the user.
-
 #### `freezeOnBlur`
 
 Boolean indicating whether to prevent inactive screens from re-rendering. Defaults to `false`.
@@ -428,6 +422,12 @@ Requires `react-native-screens` version >=3.16.0.
 
 Only supported on iOS and Android.
 
+#### `popToTopOnBlur`
+
+Boolean indicating whether any nested stack should be popped to the top of the stack when navigating away from this tab. Defaults to `false`.
+
+It only works when there is a stack navigator (e.g. [stack navigator](stack-navigator.md) or [native stack navigator](native-stack-navigator.md)) nested under the tab navigator.
+
 ### Header related options
 
 You can find the list of header related options [here](elements.md#header). These [options](screen-options.md) can be specified under `screenOptions` prop of `Tab.navigator` or `options` prop of `Tab.Screen`. You don't have to be using `@react-navigation/elements` directly to use these options, they are just documented in that page.

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

@@ -481,12 +481,6 @@ Minimum swipe distance threshold that should activate opening the drawer.
 
 Whether the keyboard should be dismissed when the swipe gesture begins. Defaults to `'on-drag'`. Set to `'none'` to disable keyboard handling.
 
-#### `unmountOnBlur`
-
-Whether this screen should be unmounted when navigating away from it. Unmounting a screen resets any local state in the screen as well as state of nested navigators in the screen. Defaults to `false`.
-
-Normally, we don't recommend enabling this prop as users don't expect their navigation history to be lost when switching screens. If you enable this prop, please consider if this will actually provide a better experience for the user.
-
 #### `freezeOnBlur`
 
 Boolean indicating whether to prevent inactive screens from re-rendering. Defaults to `false`.
@@ -496,6 +490,12 @@ Requires `react-native-screens` version >=3.16.0.
 
 Only supported on iOS and Android.
 
+#### `popToTopOnBlur`
+
+Boolean indicating whether any nested stack should be popped to the top of the stack when navigating away from this drawer screen. Defaults to `false`.
+
+It only works when there is a stack navigator (e.g. [stack navigator](stack-navigator.md) or [native stack navigator](native-stack-navigator.md)) nested under the drawer navigator.
+
 ### Header related options
 
 You can find the list of header related options [here](elements.md#header). These [options](screen-options.md) can be specified under `screenOptions` prop of `Drawer.navigator` or `options` prop of `Drawer.Screen`. You don't have to be using `@react-navigation/elements` directly to use these options, they are just documented in that page.

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

@@ -281,9 +281,28 @@ If you need to enforce a specific version of `react-native-tab-view` for some re
 
 See [Material Top Tab Navigator](material-top-tab-navigator.md) for usage.
 
-#### The `unmountOnBlur` option is removed in favor of `popToTopOnBlur` in Bottom Tab Navigator
+#### The `unmountOnBlur` option is removed in favor of `popToTopOnBlur` in Bottom Tab Navigator and Drawer Navigator
 
-TODO
+In many cases, the desired behavior is to return to the first screen of the stack nested in a tab or drawer navigator after it's unfocused. Previously, the `unmountOnBlur` option was used to achieve this behavior. However, it had some issues:
+
+- It destroyed the local state of the screen in the stack.
+- It was slow to remount the nested navigator on tab navigation.
+
+The `popToTopOnBlur` option provides an alternative approach - it pops the screens on a nested stack to go back to the first screen in the stack and doesn't have the above issues.
+
+See [Bottom Tab Navigator](bottom-tab-navigator.md#poptoptoponblur) and [Drawer Navigator](drawer-navigator.md#poptoptoponblur) docs for usage.
+
+It's still possible to achieve the old behavior of `unmountOnBlur` by using the useIsFocused hook in the screen:
+
+```js
+const isFocused = useIsFocused();
+
+if (!isFocused) {
+  return null;
+}
+```
+
+This could also be combined with the new [layout props](#new-layout-props) to specify it at the screen configuration level.
 
 #### The `tabBarTestID` option is renamed to `tabBarButtonTestID` in Bottom Tab Navigator and Material Top Tab Navigator
 

versioned_docs/version-7.x/use-prevent-remove.md

@@ -286,7 +286,6 @@ It also **does not prevent** a screen from being removed when the user is exitin
 
 - The user closes the app (e.g. by pressing the back button on the home screen, closing the tab in the browser, closing it from the app switcher etc.). You can additionally use [`hardwareBackPress`](https://reactnative.dev/docs/backhandler) event on Android, [`beforeunload`](https://developer.mozilla.org/en-US/docs/web/api/window/beforeunload_event) event on the Web etc. to handle some of these cases. See [Prevent the user from leaving the app](preventing-going-back.md#prevent-the-user-from-leaving-the-app) for more details.
 - A screen gets unmounted due to conditional rendering, or due to a parent component being unmounted.
-- A screen gets unmounted due to the usage of `unmountOnBlur` options with [`@react-navigation/bottom-tabs`](bottom-tab-navigator.md), [`@react-navigation/drawer`](drawer-navigator.md) etc.
 
 ## UX considerations