Document inactiveBehavior

Author: satya164

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

@@ -168,12 +168,6 @@ It supports the following values:
 - `fullHistory` - return to last visited screen in the navigator; doesn't drop duplicate entries unlike `history` - this behavior is useful to match how web pages work
 - `none` - do not handle back button
 
-#### `detachInactiveScreens`
-
-Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. This enables integration with [react-native-screens](https://github.com/software-mansion/react-native-screens). Defaults to `true`.
-
-Only supported with `custom` implementation.
-
 #### `tabBar`
 
 Function that returns a React element to display as the tab bar.
@@ -316,6 +310,29 @@ function MyTabBar({ navigation }) {
 
 The following [options](screen-options.md) can be used to configure the screens in the navigator. These can be specified under `screenOptions` prop of `Tab.Navigator` or `options` prop of `Tab.Screen`.
 
+#### `inactiveBehavior`
+
+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.
+- `none`: Screen renders normally.
+
+Defaults to `pause`.
+
+If you set [`lazy: false`](#lazy) or [`preload`](navigation-actions.md#preload) a screen, it won't be paused until after the first time it becomes focused. This makes sure that effects are run to initialize the screen.
+
+:::info
+
+React Navigation determines whether a screen is inactive based on various factors such as gestures, animations, and other interactions after it becomes unfocused.
+
+:::
+
+#### `lazy`
+
+Whether this screen should render only after the first time it's accessed. Defaults to `true`. Set it to `false` if you want to render the screen on the initial render of the navigator.
+
 #### `title`
 
 Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.
@@ -1026,10 +1043,6 @@ Defaults to `automatic` for each edge.
 
 Only supported with `native` implementation on iOS 26 and above.
 
-#### `lazy`
-
-Whether this screen should render only after the first time it's accessed. Defaults to `true`. Set it to `false` if you want to render the screen on the initial render of the navigator.
-
 #### `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`.

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

@@ -132,10 +132,6 @@ The default status of the drawer - whether the drawer should stay `open` or `clo
 
 When this is set to `open`, the drawer will be open from the initial render. It can be closed normally using gestures or programmatically. However, when going back, the drawer will re-open if it was closed. This is essentially the opposite of the default behavior of the drawer where it starts `closed`, and the back button closes an open drawer.
 
-#### `detachInactiveScreens`
-
-Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. This enables integration with [react-native-screens](https://github.com/software-mansion/react-native-screens). Defaults to `true`.
-
 #### `drawerContent`
 
 Function that returns React element to render as the content of the drawer, for example, navigation items
@@ -267,14 +263,27 @@ To use the custom component, we need to pass it in the `drawerContent` prop:
 
 The following [options](screen-options.md) can be used to configure the screens in the navigator. These can be specified under `screenOptions` prop of `Drawer.Navigator` or `options` prop of `Drawer.Screen`.
 
-#### `title`
+#### `inactiveBehavior`
 
-A generic title that can be used as a fallback for `headerTitle` and `drawerLabel`.
+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.
+- `none`: Screen renders normally.
+
+Defaults to `pause`.
+
+If you set [`lazy: false`](#lazy) or [`preload`](navigation-actions.md#preload) a screen, it won't be paused until after the first time it becomes focused. This makes sure that effects are run to initialize the screen.
 
 #### `lazy`
 
 Whether this screen 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.
 
+#### `title`
+
+A generic title that can be used as a fallback for `headerTitle` and `drawerLabel`.
+
 #### `drawerLabel`
 
 String or a function that given `{ focused: boolean, color: string }` returns a React.Node, to display in drawer sidebar. When undefined, scene `title` is used.

versioned_docs/version-8.x/material-top-tab-navigator.md

@@ -354,6 +354,25 @@ export default function App() {
 }
 ```
 
+#### `inactiveBehavior`
+
+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.
+- `none`: Screen renders normally.
+
+Defaults to `pause`.
+
+If you set [`lazy: false`](#lazy) or [`preload`](navigation-actions.md#preload) a screen, it won't be paused until after the first time it becomes focused. This makes sure that effects are run to initialize the screen.
+
+:::info
+
+React Navigation determines whether a screen is inactive based on various factors such as gestures, animations, and other interactions after it becomes unfocused.
+
+:::
+
 #### `title`
 
 Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.

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

@@ -95,6 +95,25 @@ The native stack navigator accepts the [common props](navigator.md#configuration
 
 The following [options](screen-options.md) can be used to configure the screens in the navigator:
 
+#### `inactiveBehavior`
+
+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.
+- `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. This makes sure that effects are run to initialize the screen.
+
+:::info
+
+React Navigation determines whether a screen is inactive based on various factors such as gestures, animations, and other interactions after it becomes unfocused.
+
+:::
+
 #### `title`
 
 String that can be used as a fallback for `headerTitle`.

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

@@ -110,19 +110,28 @@ export default function App() {
 
 ## API Definition
 
-### Props
+### Options
 
-In addition to the [common props](navigator.md#configuration) shared by all navigators, the stack navigator accepts the following additional props:
+The following [options](screen-options.md) can be used to configure the screens in the navigator. These can be specified under `screenOptions` prop of `Stack.Navigator` or `options` prop of `Stack.Screen`.
 
-#### `detachInactiveScreens`
+#### `inactiveBehavior`
 
-Boolean used to indicate whether inactive screens should be detached from the view hierarchy to save memory. This enables integration with [react-native-screens](https://github.com/software-mansion/react-native-screens). Defaults to `true`.
+This controls what should happen when screens become inactive.
 
-If you need to disable this optimization for specific screens (e.g. you want to screen to stay in view even when unfocused) [`detachPreviousScreen`](#detachpreviousscreen) option.
+It supports the following values:
 
-### Options
+- `pause`: Effects are cleaned up - e.g. timers are cleared, subscriptions are removed, etc. This avoids unnecessary renders when the screen is inactive.
+- `none`: Screen renders normally.
 
-The following [options](screen-options.md) can be used to configure the screens in the navigator. These can be specified under `screenOptions` prop of `Stack.Navigator` or `options` prop of `Stack.Screen`.
+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. This makes sure that effects are run to initialize the screen.
+
+:::info
+
+React Navigation determines whether a screen is inactive based on various factors such as gestures, animations, and other interactions after it becomes unfocused.
+
+:::
 
 #### `title`
 
@@ -144,7 +153,7 @@ Function which returns a React Element to display as the overlay for the card. M
 
 Style object for the card in stack. You can provide a custom background color to use instead of the default background here.
 
-You can also specify `{ backgroundColor: 'transparent' }` to make the previous screen visible underneath (for transparent modals). This is useful to implement things like modal dialogs. You should also specify `presentation: 'modal'` in the options when using a transparent background so previous screens aren't detached and stay visible underneath.
+You can also specify `{ backgroundColor: 'transparent' }` to make the previous screen visible underneath (for transparent modals). This is useful to implement things like modal dialogs. You should also specify `presentation: 'modal'` in the options when using a transparent background so previous screens stay visible underneath.
 
 On Web, the height of the screen isn't limited to the height of the viewport. This is by design to allow the browser's address bar to hide when scrolling. If this isn't desirable behavior, you can set `cardStyle` to `{ flex: 1 }` to force the screen to fill the viewport.
 
@@ -159,7 +168,6 @@ This is shortcut option which configures several options to configure the style
 - `transparentModal`: Similar to `modal`. This changes following things:
   - Sets `headerMode` to `screen` for the screen unless specified otherwise.
   - Sets background color of the screen to transparent, so previous screen is visible
-  - Adjusts the `detachPreviousScreen` option so that the previous screen stays rendered.
   - Prevents the previous screen from animating from its last position.
   - Changes the screen animation to a vertical slide animation.
 
@@ -223,12 +231,6 @@ Interpolated styles for various parts of the header. Refer the [Animations secti
 
 If `false`, the keyboard will NOT automatically dismiss when navigating to a new screen from this screen. Defaults to `true`.
 
-#### `detachPreviousScreen`
-
-Boolean used to indicate whether to detach the previous screen from the view hierarchy to save memory. Set it to `false` if you need the previous screen to be seen through the active screen. Only applicable if `detachInactiveScreens` isn't set to `false`.
-
-This is automatically adjusted when using [`presentation`](#presentation) as `transparentModal` or `modal` to keep the required screens visible. Defaults to `true` in other cases.
-
 #### `freezeOnBlur`
 
 Boolean indicating whether to prevent inactive screens from re-rendering. Defaults to `false`.