Root navigator ↔ deep linking config: URL routing across nested navigators

Answer

React Navigation v6 resolves a deep link by turning the URL into a navigation state with getStateFromPath. That state is then dispatched to the root NavigationContainer. Because the container owns the linking object, you only need to supply linking once – on the root. The nested navigators automatically inherit that config; they do not need their own linking prop.

Key points

• The linking object must be defined before the container processes an incoming URL. The order of navigator creation in the component tree does not affect propagation.
• To target a screen deep inside a child stack or tab navigator, nest screens objects in the config so that each key matches the route name of the corresponding Screen component.
• Android intent‑filters and iOS URL types must mirror the prefixes and path segments declared in the linking config. A mismatch means the JavaScript listener never fires, or it fires but no navigation occurs.

Typical linking structure for nested navigators

const linking = {
  prefixes: ['myapp://', 'https://example.com'],
  config: {
    screens: {
      Home: {
        screens: {
          ProfileTab: {
            screens: {
              Settings: 'settings/:id',
            },
          },
        },
      },
      About: 'about',
    },
  },
};

With this config, the URL myapp://settings/42 becomes the state { routes: [{ name: 'Home', state: { routes: [{ name: 'ProfileTab', state: { routes: [{ name: 'Settings', params: { id: '42' } }] }] }] }] }, which the container applies automatically.

Native intent‑filter alignment (Android)

• android:scheme must match a prefix in linking.prefixes (e.g., myapp).
• android:host and android:pathPrefix should cover the first segment of the path. For a universal link like https://example.com/settings/42 you would set android:scheme=\"https\", android:host=\"example.com\", and android:pathPrefix=\"/settings\" (or a more generic prefix if you want to allow any deep link under /settings).
• For App Links you must host an assetlinks.json file that declares the package and the https://example.com domain.

iOS URL types / Universal Links

• In Info.plist, declare CFBundleURLSchemes for custom schemes (e.g., myapp) and CFBundleURLTypes for universal links.
• For universal links, the domain must be verified via an apple-app-site-association file hosted on https://example.com/.well-known/.
• The prefixes array in the linking config must include the same scheme or domain.

Common pitfalls and quick checks

• Route names in linking.screens must match the name prop of the corresponding Screen. Typos silently result in no navigation.
• If a nested route name is omitted from screens, React Navigation falls back to matching the route name as a path segment. This works only when the route name equals the desired URL segment.
• Use linking.getStateFromPath('myapp://settings/42') in a dev console to inspect the generated state tree.
• Verify that the native intent‑filter or URL type actually triggers the JavaScript listener by logging the received URL in a linking.subscribe handler.

Summary of the answer to the open questions

1. Ordering: Define linking once on the root NavigationContainer before any navigation event occurs; the relative placement of nested navigators in the component tree does not matter.
2. Config: Nest screens objects to mirror the navigator hierarchy; each key must match a route name, and the leaf can contain a path pattern (e.g., 'settings/:id').
3. Native attributes: scheme, host, and pathPrefix/pathPattern on Android, and matching CFBundleURLSchemes or apple-app-site-association on iOS, must align with the prefixes and path segments in the linking config.

Need more detail?

If you still experience silent drops, double‑check the exact route names used in your Screen components versus those listed in the linking config. A mismatch is the most common source of failure.