Skip to content

Commit 57c00dc

Browse files
committed
Document popToTopOnBlur
1 parent db9b6d7 commit 57c00dc

File tree

4 files changed

+33
-15
lines changed

4 files changed

+33
-15
lines changed

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

+6-6
Original file line numberDiff line numberDiff line change
@@ -413,12 +413,6 @@ When the tab bar is positioned on the `left` or `right`, it is styled as a sideb
413413

414414
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.
415415

416-
#### `unmountOnBlur`
417-
418-
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`.
419-
420-
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.
421-
422416
#### `freezeOnBlur`
423417

424418
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.
428422

429423
Only supported on iOS and Android.
430424

425+
#### `popToTopOnBlur`
426+
427+
Boolean indicating whether any nested stack should be popped to the top of the stack when navigating away from this tab. Defaults to `false`.
428+
429+
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.
430+
431431
### Header related options
432432

433433
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

+6-6
Original file line numberDiff line numberDiff line change
@@ -481,12 +481,6 @@ Minimum swipe distance threshold that should activate opening the drawer.
481481

482482
Whether the keyboard should be dismissed when the swipe gesture begins. Defaults to `'on-drag'`. Set to `'none'` to disable keyboard handling.
483483

484-
#### `unmountOnBlur`
485-
486-
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`.
487-
488-
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.
489-
490484
#### `freezeOnBlur`
491485

492486
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.
496490

497491
Only supported on iOS and Android.
498492

493+
#### `popToTopOnBlur`
494+
495+
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`.
496+
497+
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.
498+
499499
### Header related options
500500

501501
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

+21-2
Original file line numberDiff line numberDiff line change
@@ -281,9 +281,28 @@ If you need to enforce a specific version of `react-native-tab-view` for some re
281281

282282
See [Material Top Tab Navigator](material-top-tab-navigator.md) for usage.
283283

284-
#### The `unmountOnBlur` option is removed in favor of `popToTopOnBlur` in Bottom Tab Navigator
284+
#### The `unmountOnBlur` option is removed in favor of `popToTopOnBlur` in Bottom Tab Navigator and Drawer Navigator
285285

286-
TODO
286+
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:
287+
288+
- It destroyed the local state of the screen in the stack.
289+
- It was slow to remount the nested navigator on tab navigation.
290+
291+
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.
292+
293+
See [Bottom Tab Navigator](bottom-tab-navigator.md#poptoptoponblur) and [Drawer Navigator](drawer-navigator.md#poptoptoponblur) docs for usage.
294+
295+
It's still possible to achieve the old behavior of `unmountOnBlur` by using the useIsFocused hook in the screen:
296+
297+
```js
298+
const isFocused = useIsFocused();
299+
300+
if (!isFocused) {
301+
return null;
302+
}
303+
```
304+
305+
This could also be combined with the new [layout props](#new-layout-props) to specify it at the screen configuration level.
287306

288307
#### The `tabBarTestID` option is renamed to `tabBarButtonTestID` in Bottom Tab Navigator and Material Top Tab Navigator
289308

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

-1
Original file line numberDiff line numberDiff line change
@@ -286,7 +286,6 @@ It also **does not prevent** a screen from being removed when the user is exitin
286286

287287
- 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.
288288
- A screen gets unmounted due to conditional rendering, or due to a parent component being unmounted.
289-
- 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.
290289

291290
## UX considerations
292291

0 commit comments

Comments
 (0)