Skip to content

Commit bace418

Browse files
committed
Document caveats about paused screens
1 parent abe167e commit bace418

File tree

1 file changed

+25
-1
lines changed

1 file changed

+25
-1
lines changed

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ Here, "inactive" and "unfocused" have different meanings:
359359
- [Preloaded](navigation-actions.md#preload) screens don't become inactive until after the first time they become focused, so their effects can run to initialize the screen
360360
- Focus and blur are part of navigation lifecycle, but "inactive" is an optimization mechanism
361361

362-
When a screen is paused, the following things happen:
362+
Paused screens internally use [`<Activity mode="hidden">`](https://react.dev/reference/react/Activity). When a screen is paused, the following things happen:
363363

364364
- Effects are cleaned up (similar to when a component unmounts)
365365
- Content stays rendered and the state is preserved
@@ -375,6 +375,30 @@ Pausing screens is not a replacement for lifecycle events. Treat it as an optimi
375375

376376
:::
377377

378+
React doesn't provide a way to distinguish paused screens from unmounted screens, which presents some caveats:
379+
380+
- APIs such as [`getRootState`](navigation-container.md#getrootstate) won't include state of navigators nested inside paused screens
381+
- When using [state persistence](state-persistence.md), state of navigators nested inside paused screens won't be persisted
382+
383+
If you don't want this behavior, you can set `inactiveBehavior` to `none` to avoid pausing them:
384+
385+
```js static2dynamic
386+
const MyTabs = createBottomTabNavigator({
387+
screenOptions: {
388+
// highlight-next-line
389+
inactiveBehavior: 'none',
390+
},
391+
screens: {
392+
Home: createBottomTabScreen({
393+
screen: HomeScreen,
394+
}),
395+
Profile: createBottomTabScreen({
396+
screen: ProfileScreen,
397+
}),
398+
},
399+
});
400+
```
401+
378402
## Summary
379403

380404
- Screens stay mounted when navigating away from them

0 commit comments

Comments
 (0)