{"id":893,"date":"2026-04-24T09:00:00","date_gmt":"2026-04-24T14:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=893"},"modified":"2026-03-07T03:48:33","modified_gmt":"2026-03-07T08:48:33","slug":"react-navigation-deep-links","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/react-navigation-deep-links\/","title":{"rendered":"React Navigation Deep Links: Configuration Guide"},"content":{"rendered":"\n

React Navigation is the standard navigation library for React Native. Its deep linking integration maps URLs directly to your navigation state, so a URL like \/product\/123<\/code> opens the Product screen with id: "123"<\/code> as a parameter. This guide covers configuration for React Navigation v6 and v7.<\/p>\n\n\n\n

For the native platform setup (AppDelegate, AndroidManifest), see React Native Deep Linking: Complete Setup Tutorial<\/a>. For a cross-platform overview, see Cross-Platform Deep Linking Guide<\/a>.<\/p>\n\n\n\n

Basic Linking Configuration<\/h2>\n\n\n\n

React Navigation's linking<\/code> prop on NavigationContainer<\/code> connects URLs to screens.<\/p>\n\n\n\n

Define the Linking Config<\/h3>\n\n\n\n
import * as Linking from 'expo-linking';\n\nconst linking = {\n  prefixes: [\n    'https:\/\/go.yourapp.com',       \/\/ Universal Links \/ App Links\n    'yourapp:\/\/',                     \/\/ Custom URL scheme\n  ],\n  config: {\n    screens: {\n      Home: '',\n      Product: 'product\/:id',\n      Category: 'category\/:slug',\n      Profile: 'profile\/:username',\n      Settings: 'settings',\n      NotFound: '*',\n    },\n  },\n};\n<\/code><\/pre>\n\n\n\n
Apply to NavigationContainer<\/h3>\n\n\n\n
function App() {\n  return (\n    <NavigationContainer linking={linking} fallback={<LoadingScreen \/>}>\n      <Stack.Navigator>\n        <Stack.Screen name="Home" component={HomeScreen} \/>\n        <Stack.Screen name="Product" component={ProductScreen} \/>\n        <Stack.Screen name="Category" component={CategoryScreen} \/>\n        <Stack.Screen name="Profile" component={ProfileScreen} \/>\n        <Stack.Screen name="Settings" component={SettingsScreen} \/>\n        <Stack.Screen name="NotFound" component={NotFoundScreen} \/>\n      <\/Stack.Navigator>\n    <\/NavigationContainer>\n  );\n}\n<\/code><\/pre>\n\n\n\n
The fallback<\/code> prop shows a loading screen while React Navigation resolves the initial deep link. Without it, users may briefly see the home screen before being redirected.<\/p>\n\n\n\n
Access Parameters in Screens<\/h3>\n\n\n\n
function ProductScreen({ route }) {\n  const { id } = route.params;\n\n  return <Text>Product ID: {id}<\/Text>;\n}\n<\/code><\/pre>\n\n\n\n
Nested Navigators<\/h2>\n\n\n\n
Real apps have nested navigators: a tab navigator containing stack navigators. Deep linking configuration must mirror this nesting.<\/p>\n\n\n\n
Example: Tabs with Nested Stacks<\/h3>\n\n\n\n
\/\/ Navigation structure:\n\/\/ TabNavigator\n\/\/   \u251c\u2500\u2500 HomeTab (Stack)\n\/\/   \u2502     \u251c\u2500\u2500 Home\n\/\/   \u2502     \u2514\u2500\u2500 Product\n\/\/   \u251c\u2500\u2500 SearchTab (Stack)\n\/\/   \u2502     \u251c\u2500\u2500 Search\n\/\/   \u2502     \u2514\u2500\u2500 SearchResults\n\/\/   \u2514\u2500\u2500 ProfileTab (Stack)\n\/\/         \u251c\u2500\u2500 Profile\n\/\/         \u2514\u2500\u2500 Settings\n\nconst linking = {\n  prefixes: ['https:\/\/go.yourapp.com', 'yourapp:\/\/'],\n  config: {\n    screens: {\n      Tabs: {\n        screens: {\n          HomeTab: {\n            screens: {\n              Home: '',\n              Product: 'product\/:id',\n            },\n          },\n          SearchTab: {\n            screens: {\n              Search: 'search',\n              SearchResults: 'search\/results',\n            },\n          },\n          ProfileTab: {\n            screens: {\n              Profile: 'profile\/:username',\n              Settings: 'settings',\n            },\n          },\n        },\n      },\n      NotFound: '*',\n    },\n  },\n};\n<\/code><\/pre>\n\n\n\n
When a user opens https:\/\/go.yourapp.com\/product\/123<\/code>, React Navigation:<\/p>\n\n\n\n
    \n
  1. Navigates to the Tabs<\/code> navigator<\/li>\n
  2. Selects the HomeTab<\/code> tab<\/li>\n
  3. Pushes the Product<\/code> screen with { id: "123" }<\/code><\/li>\n<\/ol>\n\n\n\n
    The user sees the Product screen with the HomeTab selected in the tab bar.<\/p>\n\n\n\n
    Query Parameters<\/h2>\n\n\n\n
    Handle query parameters alongside path parameters:<\/p>\n\n\n\n
    const linking = {\n  config: {\n    screens: {\n      Search: {\n        path: 'search',\n        parse: {\n          query: (query) => query || '',\n          sort: (sort) => sort || 'relevance',\n        },\n      },\n    },\n  },\n};\n<\/code><\/pre>\n\n\n\n
    URL: https:\/\/go.yourapp.com\/search?query=shoes&sort=price<\/code><\/p>\n\n\n\n
    function SearchScreen({ route }) {\n  const { query, sort } = route.params;\n  \/\/ query = "shoes", sort = "price"\n}\n<\/code><\/pre>\n\n\n\n
    Custom Parameter Parsing<\/h2>\n\n\n\n
    By default, path parameters are strings. Use parse<\/code> and stringify<\/code> to transform them:<\/p>\n\n\n\n
    const linking = {\n  config: {\n    screens: {\n      Product: {\n        path: 'product\/:id',\n        parse: {\n          id: Number,  \/\/ Convert string "123" to number 123\n        },\n        stringify: {\n          id: (id) => String(id),  \/\/ Convert back for URL generation\n        },\n      },\n      DateFilter: {\n        path: 'events\/:date',\n        parse: {\n          date: (date) => new Date(date),\n        },\n        stringify: {\n          date: (date) => date.toISOString().split('T')[0],\n        },\n      },\n    },\n  },\n};\n<\/code><\/pre>\n\n\n\n
    Handling Authentication Guards<\/h2>\n\n\n\n
    A common scenario: a deep link points to a screen that requires authentication. The user taps the link but isn't logged in.<\/p>\n\n\n\n
    Approach 1: Redirect After Login<\/h3>\n\n\n\n
    Store the intended deep link and redirect after authentication:<\/p>\n\n\n\n
    function App() {\n  const [isLoggedIn, setIsLoggedIn] = useState(false);\n  const [pendingDeepLink, setPendingDeepLink] = useState(null);\n\n  const linking = {\n    prefixes: ['https:\/\/go.yourapp.com'],\n    config: {\n      screens: isLoggedIn\n        ? {\n            Home: '',\n            Product: 'product\/:id',\n            Profile: 'profile\/:username',\n          }\n        : {\n            Login: '*',  \/\/ All links go to Login when not authenticated\n          },\n    },\n    getStateFromPath: (path, options) => {\n      if (isLoggedIn === false) {\n        \/\/ Save the path for after login\n        setPendingDeepLink(path);\n      }\n      return undefined; \/\/ Use default behavior\n    },\n  };\n\n  \/\/ After login, navigate to the saved deep link\n  useEffect(() => {\n    if (isLoggedIn && pendingDeepLink) {\n      navigation.navigate(pendingDeepLink);\n      setPendingDeepLink(null);\n    }\n  }, [isLoggedIn]);\n\n  return (\n    <NavigationContainer linking={linking}>\n      {\/* ... *\/}\n    <\/NavigationContainer>\n  );\n}\n<\/code><\/pre>\n\n\n\n
    Approach 2: Conditional Screens<\/h3>\n\n\n\n
    Use React Navigation's conditional rendering:<\/p>\n\n\n\n
    <Stack.Navigator>\n  {isLoggedIn ? (\n    <>\n      <Stack.Screen name="Home" component={HomeScreen} \/>\n      <Stack.Screen name="Product" component={ProductScreen} \/>\n      <Stack.Screen name="Profile" component={ProfileScreen} \/>\n    <\/>\n  ) : (\n    <>\n      <Stack.Screen name="Login" component={LoginScreen} \/>\n      <Stack.Screen name="Register" component={RegisterScreen} \/>\n    <\/>\n  )}\n<\/Stack.Navigator>\n<\/code><\/pre>\n\n\n\n
    React Navigation handles this gracefully: if a deep link targets a screen that doesn't exist in the current navigator state, it falls through to the wildcard or default screen.<\/p>\n\n\n\n
    Advanced: Custom getStateFromPath<\/h2>\n\n\n\n
    For complex routing logic that the declarative config can't handle, override getStateFromPath<\/code>:<\/p>\n\n\n\n
    import { getStateFromPath as defaultGetStateFromPath } from '@react-navigation\/native';\n\nconst linking = {\n  prefixes: ['https:\/\/go.yourapp.com'],\n  config: {\n    screens: {\n      Home: '',\n      Product: 'product\/:id',\n    },\n  },\n  getStateFromPath: (path, options) => {\n    \/\/ Custom logic: redirect legacy paths\n    if (path.startsWith('\/item\/')) {\n      path = path.replace('\/item\/', '\/product\/');\n    }\n\n    \/\/ Custom logic: extract campaign tracking\n    const url = new URL('https:\/\/go.yourapp.com' + path);\n    const utm_source = url.searchParams.get('utm_source');\n    if (utm_source) {\n      trackCampaignOpen(utm_source);\n    }\n\n    \/\/ Fall back to default parsing\n    return defaultGetStateFromPath(path, options);\n  },\n};\n<\/code><\/pre>\n\n\n\n
    This is useful for:<\/p>\n\n\n\n