0Pricing
React Native Academy · Lesson

React Navigation Deep Link Configuration

Configure the linking prop on NavigationContainer with a screen map, so React Navigation automatically navigates to the correct screen when a deep link is opened.

React Navigation Deep Link Configuration is a free React Native Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the React Native Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

React Navigation Built-In Deep Linking

React Navigation provides built-in deep linking support via a linking prop on the NavigationContainer. When configured, React Navigation automatically handles both cold-start and warm-start URLs by parsing them against a screen map and navigating to the matching screen — you don't need to write URL parsing or Linking API code manually.

This declarative approach is far less error-prone than manual URL handling and integrates seamlessly with the navigation library's state management.

import { NavigationContainer } from '@react-navigation/native';

const linking = {
  prefixes: ['myapp://'],
  config: {
    screens: {
      Home: 'home',
      Profile: 'profile/:userId',
      Settings: 'settings',
    },
  },
};

<NavigationContainer linking={linking}>
  <RootNavigator />
</NavigationContainer>

The linking Prop: prefixes and config

The linking prop has two main fields: prefixes (an array of URL prefixes to handle) and config (the screen map). The prefixes array tells React Navigation which URL schemes to intercept. You can include both your custom scheme and your HTTPS domain for universal links.

The config.screens object maps screen component names to URL path patterns. The URL path after the prefix is matched against these patterns to determine which screen to navigate to.

const linking = {
  prefixes: [
    'myapp://',
    'https://www.myapp.com',  // universal links too
    'https://myapp.com',
  ],
  config: {
    screens: {
      Home: '',           // matches myapp:// (empty path)
      Profile: 'profile/:userId',   // myapp://profile/123
      Product: 'product/:id',        // myapp://product/abc
      Settings: 'settings',          // myapp://settings
    },
  },
};

Path Parameters and Query Strings

URL path parameters are defined with a colon prefix like :userId. When a URL matches, the parameter is automatically extracted and passed as a route param to the screen component. Query string parameters are also automatically parsed and added to route params.

For example, myapp://profile/123?tab=posts matches profile/:userId and the screen receives route.params = { userId: '123', tab: 'posts' }. No manual URL parsing needed.

// URL: myapp://profile/123?tab=posts
// Matches: profile/:userId
// Screen receives:
// route.params = { userId: '123', tab: 'posts' }

function ProfileScreen({ route }) {
  const { userId, tab } = route.params;
  // userId = '123', tab = 'posts'
}

Nested Navigator Configuration

When screens are inside nested navigators (e.g., a tab navigator with stacks in each tab), the screen map must reflect the nesting structure. Use a screens key inside the parent screen's config to define nested screen paths.

React Navigation handles the navigation state correctly — it sets up the entire stack needed to arrive at the deeply nested screen, including any parent navigators that need to be initialized first.

const linking = {
  prefixes: ['myapp://'],
  config: {
    screens: {
      Tabs: {                    // bottom tab navigator
        screens: {
          HomeTab: {             // home tab stack
            screens: {
              Home: 'home',
              PostDetail: 'post/:postId',
            },
          },
          ProfileTab: {          // profile tab stack
            screens: {
              Profile: 'profile/:userId',
            },
          },
        },
      },
    },
  },
};

Exact Path Matching

By default React Navigation does prefix matching on paths. Add exact: true to a screen config to require an exact path match instead. Exact matching is important when paths could partially match multiple screens.

For example, without exact matching, the pattern post would match myapp://post and also myapp://post-list. With exact: true only the precise path matches.

const linking = {
  prefixes: ['myapp://'],
  config: {
    screens: {
      PostList: {
        path: 'post',
        exact: true,  // only matches exactly myapp://post
      },
      PostDetail: 'post/:id', // matches myapp://post/123
    },
  },
};

Custom Parse and Stringify Functions

The linking config also accepts parse and stringify functions per screen to transform route params before passing them to the component. parse converts URL param strings to the correct types (e.g., string '123' to number 123). stringify converts params back to URL strings for link generation.

These functions give you full control over param transformation without needing to implement URL parsing yourself.

const linking = {
  prefixes: ['myapp://'],
  config: {
    screens: {
      Profile: {
        path: 'profile/:userId',
        parse: {
          userId: (id) => Number(id),  // string to number
        },
        stringify: {
          userId: (id) => String(id),  // number back to string
        },
      },
    },
  },
};

getPathFromState and getStateFromPath

React Navigation provides getPathFromState and getStateFromPath utilities that convert between navigation state objects and URL path strings. These are useful for generating shareable deep links from the current navigation state and for custom state restoration logic.

getPathFromState(state, config) returns a URL path for the current navigation state. getStateFromPath(path, config) returns a navigation state for a given URL. Both require the same config object used in the linking prop.

import { getPathFromState, getStateFromPath } from '@react-navigation/native';

// Generate a shareable link for the current screen:
const currentState = navigationRef.current.getRootState();
const path = getPathFromState(currentState, linking.config);
const shareUrl = 'myapp://' + path;
// shareUrl = 'myapp://profile/123'

// Parse a URL to a navigation state:
const state = getStateFromPath('profile/123', linking.config);
// state = { routes: [{ name: 'Profile', params: { userId: '123' } }] }

Enabling Deep Links in Expo (Expo Go)

When running in Expo Go during development, your app's deep link URL uses the exp:// scheme with the Expo Go host. React Navigation handles this automatically when you include Linking.createURL('') in the prefixes array (using the expo-linking package), which resolves to the correct prefix for both Expo Go and production builds.

This means your deep link config works in both development (Expo Go) and production (your app's custom scheme) without any changes to the config.

import * as ExpoLinking from 'expo-linking';

const linking = {
  prefixes: [
    ExpoLinking.createURL('/'), // works in Expo Go AND production
    'myapp://',
    'https://www.myapp.com',
  ],
  config: {
    screens: {
      Home: '',
      Profile: 'profile/:userId',
    },
  },
};

Generating Deep Links Programmatically

Use Linking.createURL(path, options) from expo-linking to generate deep link URLs that work in both development and production. Pass query params in the queryParams option. Use the generated URLs in notifications, share sheets, and email campaigns.

This approach is safer than hardcoding scheme URLs because createURL produces the correct prefix for the current runtime environment automatically.

import * as ExpoLinking from 'expo-linking';

// Generate a profile deep link:
const profileLink = ExpoLinking.createURL('profile/123', {
  queryParams: { tab: 'posts', source: 'share_button' },
});
// In production: 'myapp://profile/123?tab=posts&source=share_button'
// In Expo Go: 'exp://127.0.0.1:19000/--/profile/123?tab=posts...'

await Share.share({ url: profileLink });

Testing the Linking Configuration

React Navigation provides a linking debug tool — set linking.enabled: 'auto' and the library logs URL matching results to the console in development. This helps diagnose why a URL is not navigating to the expected screen.

For comprehensive testing, write a test function that calls getStateFromPath with each of your expected deep link URLs and asserts the resulting navigation state is correct. This catches config errors before they reach users.

// Test your linking config:
import { getStateFromPath } from '@react-navigation/native';

const testCases = [
  { url: 'profile/123', expected: 'Profile' },
  { url: 'product/abc', expected: 'Product' },
  { url: 'settings', expected: 'Settings' },
];

testCases.forEach(({ url, expected }) => {
  const state = getStateFromPath(url, linking.config);
  const routeName = state.routes[0].name;
  console.assert(routeName === expected, 'Mismatch for ' + url);
});

Not Found Screen for Invalid Links

Configure a fallback screen for URLs that don't match any defined pattern. In the linking config, add a NotFound screen and set it as the fallback. This is important because deep links from third parties may use incorrect paths, and you should gracefully show a useful message instead of crashing or silently failing.

The not-found screen should explain that the link is no longer valid, provide a way to navigate to the home screen, and optionally log the invalid URL for analysis.

const linking = {
  prefixes: ['myapp://'],
  config: {
    screens: {
      Home: '',
      Profile: 'profile/:userId',
      NotFound: '*',  // catch-all for unmatched paths
    },
  },
};

function NotFoundScreen() {
  const navigation = useNavigation();
  return (
    <View>
      <Text>This link is no longer valid.</Text>
      <Button
        title='Go Home'
        onPress={() => navigation.replace('Home')}
      />
    </View>
  );
}

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

In this lesson you learned: the linking prop on NavigationContainer automatically handles deep link parsing and navigation using a declarative screen map, nested navigators are supported by nesting screens configs within parent screen configs, and ExpoLinking.createURL generates environment-aware deep links that work in both Expo Go and production builds. Next up we configure universal links using HTTPS URLs with Apple App Site Association and Android App Links.

Frequently asked questions

Is the “React Navigation Deep Link Configuration” lesson free?

Yes — the full text of “React Navigation Deep Link Configuration” is free to read here on the web, and the React Native Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the React Native Academy course, upgrade to CoddyKit PRO.

What will I learn in “React Navigation Deep Link Configuration”?

Configure the linking prop on NavigationContainer with a screen map, so React Navigation automatically navigates to the correct screen when a deep link is opened. You practise React Native Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start React Native Academy?

No prior experience is required. React Native Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “React Navigation Deep Link Configuration” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this React Native Academy lesson?

Yes. Every React Native Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Configuring Custom URL Schemes
  2. Linking API and URL Parsing
  3. React Navigation Deep Link Configuration
  4. Universal Links (HTTPS Deep Links) on iOS and Android
← Back to React Native Academy