Document UNSTABLE_router prop

Author: satya164

versioned_docs/version-7.x/auth-flow.md

@@ -953,7 +953,7 @@ To achieve this, you can pass `UNSTABLE_routeNamesChangeBehavior="lastUnhandled"
 
 :::warning
 
-This option is experimental and may change in a minor release.
+This API is experimental and may change in a minor release.
 
 :::
 

versioned_docs/version-7.x/custom-navigators.md

@@ -438,3 +438,14 @@ const { state, descriptors, navigation, NavigationContent } =
 
 // ...
 ```
+
+:::note
+
+Customizing built-in navigators like this is an advanced use case and generally not necessary. Consider alternatives such as:
+
+- [`layout`](navigator.md#layout) prop on navigators to add a wrapper around the navigator
+- [`UNSTABLE_router`](navigator.md#router) prop on navigators to customize the router behavior
+
+Also refer to the navigator's documentation to see if any existing API meets your needs.
+
+:::

versioned_docs/version-7.x/custom-routers.md

@@ -150,9 +150,10 @@ The library ships with a few standard routers:
 
 ## Customizing Routers
 
-You can reuse a router and override the router functions as per your needs, such as customizing how existing actions are handled, adding additional actions etc.
+There are two main ways to customize routers:
 
-See [custom navigators](custom-navigators.md) for details on how to override the router with a custom router in an existing navigator.
+- Override an existing router with the [`UNSTABLE_router`](navigator.md#router) prop on navigators
+- Customized navigators with a custom router, see [extending navigators](custom-navigators.md#extending-navigators)
 
 ### Custom Navigation Actions
 

versioned_docs/version-7.x/navigator.md

@@ -309,3 +309,77 @@ function MyStack() {
 
 </TabItem>
 </Tabs>
+
+### Router
+
+:::warning
+
+This API is experimental and may change in a minor release.
+
+:::
+
+Routers can be customized with the `UNSTABLE_router` prop on navigator to override how navigation actions are handled.
+
+It takes a function that receives the original router and returns an object with overrides:
+
+<Tabs groupId="config" queryString="config">
+<TabItem value="static" label="Static" default>
+
+```js
+const MyStack = createNativeStackNavigator({
+  // highlight-start
+  UNSTABLE_router: (original) => ({
+    getStateForAction(state, action) {
+      if (action.type === 'SOME_ACTION') {
+        // Custom logic
+      }
+
+      // Fallback to original behavior
+      return original.getStateForAction(state, action);
+    },
+  }),
+  // highlight-end
+  screens: {
+    Home: HomeScreen,
+    Profile: ProfileScreen,
+  },
+});
+```
+
+</TabItem>
+<TabItem value="dynamic" label="Dynamic">
+
+```js
+const Stack = createNativeStackNavigator();
+
+function MyStack() {
+  return (
+    <Stack.Navigator
+      // highlight-start
+      UNSTABLE_router={(original) => ({
+        getStateForAction(state, action) {
+          if (action.type === 'SOME_ACTION') {
+            // Custom logic
+          }
+
+          // Fallback to original behavior
+          return original.getStateForAction(state, action);
+        },
+      })}
+      // highlight-end
+    >
+      <Stack.Screen name="Home" component={HomeScreen} />
+      <Stack.Screen name="Profile" component={ProfileScreen} />
+    </Stack.Navigator>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+
+The function passed to `UNSTABLE_router` **must be a pure function and cannot reference outside dynamic variables**.
+
+The overrides object is shallow merged with the original router. So you don't need to specify all properties of the router, only the ones you want to override.
+
+See [custom routers](custom-routers.md) for more details on routers.