Document sharing screens in navigators

Author: satya164

versioned_docs/version-8.x/configuring-links.md

@@ -274,6 +274,7 @@ When using automatic path generation with `enabled: 'auto'`, the following rules
 - Screen names will be converted from `PascalCase` to `kebab-case` to use as the path (e.g. `NewsFeed` -> `news-feed`).
 - Unless a screen has explicit empty path (`path: ''`) to use for the homepage, the first leaf screen encountered will be used as the homepage.
 - Path generation only handles leaf screens, i.e. no path is generated for screens containing nested navigators. It's still possible to specify a path for them with an explicit `linking` property.
+- If the same screen is used in multiple nested navigators with the same path pattern, the path will be marked as [shared](#shared-paths) automatically. This is detected by comparing the screen component or navigator reference.
 
 Let's say we have the following navigation structure:
 
@@ -1179,6 +1180,87 @@ const config = {
 
 With `exact` property set to `true`, `Profile` will ignore the parent screen's `path` config and you'll be able to navigate to `Profile` using a URL like `users/cal`.
 
+## Shared paths
+
+Sometimes the same screen is present in multiple nested navigators. For example, each tab can have its own stack, and each stack can contain a `Profile` screen. In this case, you may want `/profile/jane` to keep the current tab focused and open the `Profile` screen in that tab.
+
+React Navigation supports this with shared paths:
+
+<Tabs groupId="config" queryString="config">
+<TabItem value="static" label="Static" default>
+
+When using static configuration with automatic path generation (default behavior), shared paths are detected automatically when the same screen component or navigator reference appears in multiple branches with the same full path pattern:
+
+```js
+const Profile = createNativeStackScreen({
+  screen: ProfileScreen,
+  linking: 'profile/:id',
+});
+
+const FeedStack = createNativeStackNavigator({
+  screens: {
+    Feed: FeedScreen,
+    Profile,
+  },
+});
+
+const SearchStack = createNativeStackNavigator({
+  screens: {
+    Search: SearchScreen,
+    Profile,
+  },
+});
+```
+
+You can also set `shared` explicitly, which can be useful if the screen component is different but you still want to share the path:
+
+```js
+const Profile = createNativeStackScreen({
+  screen: ProfileScreen,
+  linking: {
+    path: 'profile/:id',
+    shared: true,
+  },
+});
+```
+
+</TabItem>
+<TabItem value="dynamic" label="Dynamic">
+
+When using dynamic configuration, specify `shared: true` for every screen config that should accept the same path:
+
+```js
+const config = {
+  screens: {
+    FeedTab: {
+      screens: {
+        Feed: '',
+        Profile: {
+          path: 'profile/:id',
+          shared: true,
+        },
+      },
+    },
+    SearchTab: {
+      screens: {
+        Search: 'search',
+        Profile: {
+          path: 'profile/:id',
+          shared: true,
+        },
+      },
+    },
+  },
+};
+```
+
+</TabItem>
+</Tabs>
+
+When a shared path matches more than one screen, React Navigation uses the current navigation state to choose the matching branch when possible to handle deep links.
+
+The first matching path is also the canonical path used when generating URLs. If you use [`alias`](#alias-for-paths), you need to explicitly mark the alias itself as `shared: true` when desired.
+
 ## Omitting a screen from path
 
 Sometimes, you may not want to have the route name of a screen in the path. For example, let's say you have a `Home` screen and the following config. When the page is opened in the browser you'll get `/home` as the URL:
@@ -1506,6 +1588,7 @@ Each item in the `alias` array can be a string matching the syntax of the `path`
 
 - `path` (required) - The path pattern to match.
 - `exact` - Whether to match the path exactly. Defaults to `false`. See [Matching exact paths](#matching-exact-paths) for more details.
+- `shared` - Whether this alias can resolve to multiple routes. Defaults to `false`. See [Shared paths](#shared-paths) for more details.
 - `parse` - Function to parse path segments into param values. See [Passing params](#passing-params) for more details.
 
 ## Advanced cases

versioned_docs/version-8.x/nesting-navigators.md

@@ -591,6 +591,116 @@ function RootStack() {
 </TabItem>
 </Tabs>
 
+## Sharing the same screen in multiple navigators
+
+A common pattern in mobile apps is to nest stack navigators inside each tab of a bottom tab navigator. Often, there can be some screens that exist in each stack.
+
+Let's say you have a `FeedStack` tab and a `SearchStack` tab, and both of them can navigate to a `Profile` screen. You can add the `Profile` screen to both stacks, so that when you navigate to it from the `Feed` screen, the `FeedStack` tab stays selected and the tab bar remains visible. Pressing back from `Profile` will take you back to the previous screen in the same tab.
+
+<Tabs groupId="config" queryString="config">
+<TabItem value="static" label="Static" default>
+
+```js
+// highlight-start
+const Profile = createNativeStackScreen({
+  screen: ProfileScreen,
+  linking: 'profile/:id',
+});
+// highlight-end
+
+const FeedStack = createNativeStackNavigator({
+  screens: {
+    Feed: FeedScreen,
+    // highlight-next-line
+    Profile,
+  },
+});
+
+const SearchStack = createNativeStackNavigator({
+  screens: {
+    Search: SearchScreen,
+    // highlight-next-line
+    Profile,
+  },
+});
+
+const HomeTabs = createBottomTabNavigator({
+  screens: {
+    FeedTab: createBottomTabScreen({
+      screen: FeedStack,
+      options: {
+        title: 'Feed',
+      },
+    }),
+    SearchTab: createBottomTabScreen({
+      screen: SearchStack,
+      options: {
+        title: 'Search',
+      },
+    }),
+  },
+});
+```
+
+</TabItem>
+<TabItem value="dynamic" label="Dynamic">
+
+```js
+function FeedStack() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="Feed" component={FeedScreen} />
+      <Stack.Screen
+        name="Profile"
+        // highlight-next-line
+        component={ProfileScreen}
+      />
+    </Stack.Navigator>
+  );
+}
+
+function SearchStack() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="Search" component={SearchScreen} />
+      <Stack.Screen
+        name="Profile"
+        // highlight-next-line
+        component={ProfileScreen}
+      />
+    </Stack.Navigator>
+  );
+}
+
+function HomeTabs() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name="FeedTab"
+        component={FeedStack}
+        options={{
+          title: 'Feed',
+        }}
+      />
+      <Tab.Screen
+        name="SearchTab"
+        component={SearchStack}
+        options={{
+          title: 'Search',
+        }}
+      />
+    </Tab.Navigator>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+
+Each `Profile` screen belongs to the stack where it was opened. Calling `navigate('Profile', { id: 'jane' })` from inside `FeedStack` opens `Profile` in `FeedStack`, while the same call from inside `SearchStack` opens it in `SearchStack`.
+
+For deep linking and browser URL integration, you can [configure the same path for both screens](configuring-links.md#shared-paths) so that the URL is the same regardless of which stack it was opened from.
+
 ## Best practices when nesting
 
 We recommend keeping navigator nesting to a minimum. Try to achieve the behavior you want with as little nesting as possible.

versioned_docs/version-8.x/upgrading-from-7.x.md

@@ -1163,6 +1163,43 @@ const RootStack = createNativeStackNavigator({
 });
 ```
 
+### Multiple screens can now share the same path pattern for deep linking
+
+In React Navigation 7, each screen needed to have a unique path pattern for deep linking.
+
+React Navigation 8, we now supported shared paths, which allows multiple screens to share the same path pattern. This is useful for cases where the same screen appears in multiple nested navigators, but you want them to use a single URL. e.g. each tab contains its own stack with a `Profile` screen, while both copies still use a single URL such as `/profile/jane`.
+
+When using static configuration, this is detected automatically. It can also be explicitly specified with `shared: true` when using dynamic configuration, or when automatic detection won't detect this in static configuration:
+
+```js
+const config = {
+  screens: {
+    FeedTab: {
+      screens: {
+        Feed: '',
+        Profile: {
+          path: 'profile/:id',
+          shared: true,
+        },
+      },
+    },
+    SearchTab: {
+      screens: {
+        Search: 'search',
+        Profile: {
+          path: 'profile/:id',
+          shared: true,
+        },
+      },
+    },
+  },
+};
+```
+
+When handling deep links that have shared paths, React Navigation will try to automatically select the correct navigator based on the current navigation state.
+
+See [Shared paths](configuring-links.md#shared-paths) for more details.
+
 ### Navigators now accept a `router` prop
 
 A router defines how the navigator updates its state based on navigation actions. Previously, custom routers could only be used by [creating a custom navigator](custom-navigators.md#extending-navigators).