Document inactiveBehavior: 'unmount'

Author: satya164

versioned_docs/version-8.x/native-stack-navigator.md

@@ -102,12 +102,15 @@ This controls what should happen when screens become inactive.
 It supports the following values:
 
 - `pause`: Effects are cleaned up - e.g. timers are cleared, subscriptions are removed, etc. This avoids unnecessary renders when the screen is inactive.
+- `unmount`: The screen is unmounted when it becomes inactive.
 - `none`: Screen renders normally.
 
 Defaults to `pause`.
 
 If you [`preload`](navigation-actions.md#preload) a screen, it won't be paused until after the first time it becomes focused.
 
+If a screen contains a nested navigator, it won't be unmounted, but paused instead.
+
 See [Inactive screens](navigation-lifecycle.md#inactive-screens) for more details.
 
 #### `title`

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

@@ -333,7 +333,7 @@ To know the focus state inside of an event listener, we can use the [`navigation
 
 ## Inactive screens
 
-Many navigators also have an `inactiveBehavior` option that lets you "pause" screens when they are inactive:
+Many navigators also have an `inactiveBehavior` option that lets you "pause" or "unmount" screens when they are inactive:
 
 ```js static2dynamic
 const MyTabs = createBottomTabNavigator({
@@ -359,6 +359,8 @@ Here, "inactive" and "unfocused" have different meanings:
 - [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
 - Focus and blur are part of navigation lifecycle, but "inactive" is an optimization mechanism
 
+### Paused screens
+
 Paused screens internally use [`<Activity mode="hidden">`](https://react.dev/reference/react/Activity). When a screen is paused, the following things happen:
 
 - Effects are cleaned up (similar to when a component unmounts)
@@ -399,6 +401,39 @@ const MyTabs = createBottomTabNavigator({
 });
 ```
 
+### Unmounted screens
+
+When `inactiveBehavior` is set to `unmount`, screens will be unmounted when they become inactive. This means their content will be unmounted and their local state will be lost.
+
+This is primarily useful for stack navigators where the list of screens can grow. Unmounting inactive screens can help free up resources.
+
+To unmount inactive screens, you can set `inactiveBehavior` to `unmount`:
+
+```js static2dynamic
+const MyStack = createNativeStackNavigator({
+  screenOptions: {
+    // highlight-next-line
+    inactiveBehavior: 'unmount',
+  },
+  screens: {
+    Home: createNativeStackScreen({
+      screen: HomeScreen,
+    }),
+    Details: createNativeStackScreen({
+      screen: DetailsScreen,
+    }),
+  },
+});
+```
+
+Also consider reworking your navigation flow to avoid growing the stack indefinitely if possible - e.g. by using `pop: true` option in [`navigate`](navigation-actions.md#navigate) or using [`replace`](stack-actions.md#replace) when relevant.
+
+:::info
+
+Screens containing nested navigators won't be unmounted even when `inactiveBehavior` is set to `unmount`, and will be paused instead. This avoids losing nested navigation state.
+
+:::
+
 ## Summary
 
 - Screens stay mounted when navigating away from them

versioned_docs/version-8.x/stack-navigator.md

@@ -121,12 +121,15 @@ This controls what should happen when screens become inactive.
 It supports the following values:
 
 - `pause`: Effects are cleaned up - e.g. timers are cleared, subscriptions are removed, etc. This avoids unnecessary renders when the screen is inactive.
+- `unmount`: The screen is unmounted when it becomes inactive.
 - `none`: Screen renders normally.
 
 Defaults to `pause`.
 
 If you [`preload`](navigation-actions.md#preload) a screen, it won't be paused until after the first time it becomes focused.
 
+If a screen contains a nested navigator, it won't be unmounted, but paused instead.
+
 See [Inactive screens](navigation-lifecycle.md#inactive-screens) for more details.
 
 #### `title`