Deep Linking is a technique in which a given URL or resource is used to open a specific page or screen on mobile. So, instead of just launching the app on mobile, a deep link can lead a user to a specific screen within the app, providing a better user experience. This particular screen may reside under a series of hierarchical pages, hence the term "deep" in deep linking.

It is useful for marketing campaigns, app-user retention, etc. As an application user, you probably have experienced deep linking when opening a link, for example, for a product in an ecommerce store from the web browser. If you have the app of that shop installed, it may use a deep link to open the app navigate you directly to that product’s screen.

In this tutorial, let's learn how to handle deep linking in a React Native app by creating an example app. We will create a simple app that will handle deep linking and go through configuring deep linking using React Navigation library.

Source code of the example app is available at this GitHub Repo.

Let's start by creating a new React Native application. First, open up a terminal and run the following command:

Copy
npx react-native init rnDeepLinking

# after the project is generated by the above command
# navigate to the rnDeepLinking directory
cd rnDeepLinking

The example app you will build in this tutorial will contain two screens. The first screen will be the Home screen with a list of items. The second screen will be the Details screen which shows an item's details.

Let's configure React Navigation version 6 and install the required dependencies. This will allow configuring deep linking via navigation and navigating between two screens.

Copy
yarn add @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context

The next step is to link all the libraries you just installed. This example app uses the 0.67.x React Native version.

On iOS devices, you have to run the following set of commands.

Copy
npx pod-install ios

For Android, open the file android/app/src/main/java/<Your React Native Project Name>/MainActivity.java and add the following code snippet:

Copy
1package com.rndeeplinking;
2
3import android.os.Bundle;
4import com.facebook.react.ReactActivity;
5
6public class MainActivity extends ReactActivity {
7
8  /**
9   * Returns the name of the main component registered from JavaScript. This is used to schedule
10   * rendering of the component.
11   */
12  @Override
13  protected String getMainComponentName() {
14    return "rnDeepLinking";
15  }
16  @Override
17  protected void onCreate(Bundle savedInstanceState) {
18    super.onCreate(null);
19  }
20}

That's all you need to configure React Navigation library in a bare React Native app.

Note: The process to configure React Navigation library in a bare React Native project may change in the future. It is recommended to follow instructions from their official documentation.

Create a new directory called src/screens. This will contain all the screen components of the app. Inside it, create two new files: HomeScreen.js and DetailsScreen.js.

The HomeScreen.js file displays a list of persons from an array of mock data from a Json placeholder API. The list is rendered using a FlatList component from React Native.

Each list person is wrapped by the Pressable component so that when an app user presses a user's name from the list, they will navigate to the Details screen.

Copy
1// src/screens/HomeScreen.js
2
3import React, { useState, useEffect } from 'react';
4import {
5  ActivityIndicator,
6  View,
7  Text,
8  FlatList,
9  Pressable
10} from 'react-native';
11
12import Separator from '../components/Separator';
13
14const HomeScreen = ({ navigation }) => {
15  const [data, setData] = useState([]);
16  const [isLoading, setIsLoading] = useState(true);
17
18  useEffect(() => {
19    fetch('https://jsonplaceholder.typicode.com/users')
20      .then(res => res.json())
21      .then(res => {
22        setData(res);
23        setIsLoading(false);
24      })
25      .catch(error => {
26        console.log(error);
27      });
28  }, []);
29
30  const renderList = ({ item }) => {
31    return (
32      <Pressable
33        onPress={() => alert('Navigate to Details screen')}
34        style={{ paddingHorizontal: 10 }}
35      >
36        <Text style={{ fontSize: 24, color: '#000' }}>{item.name}</Text>
37      </Pressable>
38    );
39  };
40
41  return (
42    <View style={{ flex: 1 }}>
43      {isLoading ? (
44        <ActivityIndicator color="blue" size="large" />
45      ) : (
46        <>
47          <FlatList
48            data={data}
49            contentContainerStyle={{
50              paddingVertical: 20
51            }}
52            keyExtractor={item => item.id}
53            ItemSeparatorComponent={Separator}
54            renderItem={renderList}
55          />
56        </>
57      )}
58    </View>
59  );
60};
61
62export default HomeScreen;

Let's also create a new file inside the src/components directory and call it Separator.js. This file contains a <Separator /> component is used to divide a list item in the HomeScreen. The <Separator /> component is a simple View with some additional styles.

It is used as a value for the prop ItemSeparatorComponent in the FlatList component. The ItemSeparatorComponent prop defines a custom separator and is rendered between each item in the list.

Copy
1// src/components/Separator.js
2
3import React from 'react';
4import { View } from 'react-native';
5
6const Separator = () => (
7  <View
8    style={{
9      borderBottomColor: '#d3d3d3',
10      borderBottomWidth: 1,
11      marginTop: 10,
12      marginBottom: 10
13    }}
14  />
15);
16
17export default Separator;

For the details screen, for now, let us just display a text string in the screen component file DetailsScreen.js:

Copy
1import React from 'react';
2import { View, Text } from 'react-native';
3
4const DetailsScreen = ({ navigation }) => {
5  return (
6    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
7      <Text>Details Screen</Text>
8    </View>
9  );
10};
11
12export default DetailsScreen;

To set up a Stack Navigator in the app, create a new file called src/navigation/RootNavigator.js and add the following code snippet:

Copy
1// src/navigation/RootNavigator.js
2
3import * as React from 'react';
4import { NavigationContainer } from '@react-navigation/native';
5import { createNativeStackNavigator } from '@react-navigation/native-stack';
6
7import HomeScreen from '../screens/HomeScreen';
8import DetailsScreen from '../screens/DetailsScreen';
9
10const RootStack = createNativeStackNavigator();
11
12const RootNavigator = () => {
13  return (
14    <NavigationContainer>
15      <RootStack.Navigator>
16        <RootStack.Screen name="Home" component={HomeScreen} />
17        <RootStack.Screen name="Details" component={DetailsScreen} />
18      </RootStack.Navigator>
19    </NavigationContainer>
20  );
21};
22
23export default RootNavigator;

Then, import RootNavigator in the App.js file:

Copy
1// App.js
2
3import React from 'react';
4
5import RootNavigator from './src/navigation/RootNavigator';
6
7const App = () => {
8  return <RootNavigator />;
9};
10
11export default App;

To build and run the app, open two instances of the terminal window. In the first instance, run npx react-native start. This will start the React Native packager.

To build the app for iOS or Android, run the appropriate command from the second instance of the terminal window. This will build the app for the platform you specify.

Copy
# for iOS
npx react-native run-ios

# for android
npx react-native run-android

Once the app is built, the above command will install it on the specified platform. Here is an example of the app running on an iOS simulator and a real Android device:

There are two ways to handle Deep Linking in a React Native app:

• Without navigation: by invoking React Native's core library via JavaScript and directly calling Linking. You can learn more about this in React Native's official documentation
• With navigation: by configuring React Navigation library

Most production-grade applications have multiple screens and nested navigators. So let's see how to implement it with React Navigation in our example app.

To allow React Navigation library to handle deep links through its routing logic, you need to define a configuration object. In this object, define a prefixes property that contains a URI scheme. The app is open based on this URI scheme.

This configuration object is then passed to a prop called linking on the NavigationContainer. Also, add a fallback prop on the container. It will render and display a loading indicator until the deep link is resolved.

Copy
1// src/navigation/RootNavigator.js
2
3// rest of the import statement remains same
4import { ActivityIndicator } from 'react-native';
5
6const linking = {
7  prefixes: ['peoplesapp://']
8};
9
10const RootNavigator = () => {
11  return (
12    <NavigationContainer
13      linking={linking}
14      fallback={<ActivityIndicator color="blue" size="large" />}
15    >
16      <RootStack.Navigator>
17        <RootStack.Screen name="Home" component={HomeScreen} />
18        <RootStack.Screen name="Details" component={DetailsScreen} />
19      </RootStack.Navigator>
20    </NavigationContainer>
21  );
22};

Instead of manually setting up URI schemes for iOS and Android, you can use the uri-scheme npm package. It allows configuring and testing native URI schemes on iOS and Android devices. Thanks to the Expo team for creating this package and making it available to make our developer life easier.

Note: If you want to dive deep and set up URI schemes manually for both iOS and Android, check out the next two sections.

To set up the scheme, run the following command for the appropriate platform:

Copy
# for iOS
npx uri-scheme add peoplesapp --ios

# for Android
npx uri-scheme add peoplesapp --android

After this step, make sure to build the app again for the specific platform using either npx react-native run-ios or npx react-native run-android.

To manually set up the scheme for iOS devices, open the ios/your-project-name/AppDelegate.m file and add the following code snippet:

Copy
1// Add the header at the top of the file:
2#import <React/RCTLinkingManager.h>
3
4// Add this above `@end`:
5- (BOOL)application:(UIApplication *)application
6   openURL:(NSURL *)url
7   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
8{
9  return [RCTLinkingManager application:application openURL:url options:options];
10}

Now, let's add the URI scheme to the iOS project configuration. Open, Your-app-name/ios/app-name.xcworkspace in Xcode.

Then, select the project name in the left sidebar and navigate to the Info tab:

Next, go to the URL Types, click the + (plus) button, and under the Identifier and URL schemes, add peoplesapp.

The URL Types are similar to what http represents in a web URL. It is what is used by iOS to open the app.

After this configuration step, rebuild your iOS app using npx react-native run-ios.

To manually set up a scheme for Android devices, you have to configure the scheme. Open /android/app/src/main/AndroidManifest.xml and set the value of launchMode to singleTask. To add the scheme, add a new intent-filter tag as shown below:

Copy
1<!-- Set the launchMode to singleTask in <activity> -->
2<activity
3  android:name=".MainActivity"
4  android:label="@string/app_name"
5  android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode"
6  android:launchMode="singleTask"
7  android:windowSoftInputMode="adjustResize">
8  <intent-filter>
9    <action android:name="android.intent.action.MAIN" />
10    <category android:name="android.intent.category.LAUNCHER" />
11  </intent-filter>
12  <!-- Add this new intent-filter tag -->
13  <!-- Make sure to set the value of android:scheme to your own scheme -->
14  <intent-filter>
15    <action android:name="android.intent.action.VIEW" />
16    <category android:name="android.intent.category.DEFAULT" />
17    <category android:name="android.intent.category.BROWSABLE" />
18    <data android:scheme="peoplesapp" />
19  </intent-filter>
20</activity>

After this configuration step, rebuild your Android app using npx react-native run-android.

To test out the configuration you have set up so far, run the iOS app, and open up the iOS simulator. If the example app is already running, close it before testing.

Then, from a terminal window, run the following command:

Copy
# replace peoplesapp:// with your own URL
xcrun simctl openurl booted peoplesapp://

# OR use uri-scheme package to test
npx uri-scheme open peoplesapp:// --ios

This will open the example app:

You can also test it by opening up a web browser in your simulator device and running the URL peoplesapp://. It is going to ask you to whether open the external URI or not, as shown below:

To test out the configuration set up so far, I am using a real Android device. You can also use an Android emulator. Make sure to close the example app if it is already running before testing.

From a terminal window, run the following command:

Copy
# replace peoplesapp:// with your own URL
adb shell am start -W -a android.intent.action.VIEW -d "peoplesapp://"

# OR use uri-scheme package to test
npx uri-scheme open peoplesapp:// --android

Here is the output after running the above command:

You can extend the linking config object to define a specific path for each screen. This is useful, especially when you have multiple screens and link to each specific screen.

In the example app, let's define linking paths for both the Home and Details screen. Modify the linking config object in the src/navigation/RootNavigator.js file as shown below:

Copy
1const linking = {
2  prefixes: ['peoplesapp://'],
3  config: {
4    initialRouteName: 'Home',
5    screens: {
6      Home: {
7        path: 'home'
8      },
9      Details: {
10        path: 'details'
11      }
12    }
13  }
14};

The initialRouteName is the name of the initial screen. The back button is not shown by default when linking to a nested screen. Using the property, you can define a screen name to go back, within the app.

The screens property maps screen names to screen paths. The screen path is the path that is used to link to the screen.

Now, let's test it out. Make sure to quit the app before testing.

The screen path configuration works as expected.

To display information of each person when visiting the Details screen with the URL scheme, you have to configure the path for the Details screen and add a dynamic parameter that represents the person's id from the list.

Copy
1const linking = {
2  prefixes: ['peoplesapp://'],
3  config: {
4    initialRouteName: 'Home',
5    screens: {
6      Home: {
7        path: 'home'
8      },
9      Details: {
10        path: 'details/:personId'
11      }
12    }
13  }
14};

The personId is now available to the Details screen as a route paramater. Route parameters are accessible to a screen using route.params from React Navigation library.

Based on the personId value, the Details screen will fetch the data from the API and display the person's information.

Let's also handle the case where an app user navigates to the Details screen from the Home screen, that is, without using linking. In this case, open HomeScreen.js and replace the value onPress prop on the Pressable component as shown below:

Copy
1// src/screens/HomeScreen.js
2
3<Pressable
4  onPress={() => navigation.navigate('Details', { personDetailsId: item.id })}
5  style={{ paddingHorizontal: 10 }}
6>
7  <Text style={{ fontSize: 24, color: '#000' }}>{item.name}</Text>
8</Pressable>

Notice that the personDetailsId is a route parameter passed to the Details screen in the above snippet. This will only fetch a person's details when the user navigates to the Details screen from the Home screen.

In the Details screen, let's get both personDetailsId (the id coming from the Home screen) and personId (the id used from the URL scheme) from the route.params object.

Then using a useEffect hook, fetch data from Json Placeholder API and render the details:

Copy
1import React, { useState, useEffect } from 'react';
2import { View, Text, ActivityIndicator } from 'react-native';
3
4const DetailsScreen = ({ route }) => {
5  const params = route.params || {};
6  const { personDetailsId, personId } = params;
7
8  const [data, setData] = useState([]);
9  const [isLoading, setIsLoading] = useState(true);
10
11  useEffect(() => {
12    if (personId) {
13      fetch(`https://jsonplaceholder.typicode.com/users/${personId}`)
14        .then(res => res.json())
15        .then(res => {
16          const fetchedDetails = [];
17
18          Object.keys(res).forEach(key => {
19            fetchedDetails.push({ key, value: `${res[key]}` });
20          });
21          setData(fetchedDetails);
22          setIsLoading(false);
23        })
24        .catch(error => {
25          console.log(error);
26        });
27    } else {
28      fetch(`https://jsonplaceholder.typicode.com/users/${personDetailsId}`)
29        .then(res => res.json())
30        .then(res => {
31          const fetchedDetails = [];
32
33          Object.keys(res).forEach(key => {
34            fetchedDetails.push({ key, value: `${res[key]}` });
35          });
36
37          setData(fetchedDetails);
38          setIsLoading(false);
39        })
40        .catch(error => {
41          console.log(error);
42        });
43    }
44  }, []);
45
46  return (
47    <View style={{ flex: 1 }}>
48      {isLoading ? (
49        <ActivityIndicator color="blue" size="large" />
50      ) : (
51        <View style={{ paddingTop: 10, paddingHorizontal: 10 }}>
52          {data.map(person => (
53            <Text
54              style={{ fontSize: 24, paddingBottom: 2 }}
55              key={person.key}
56            >{`${person.key}: ${person.value}`}</Text>
57          ))}
58        </View>
59      )}
60    </View>
61  );
62};
63
64export default DetailsScreen;

Here is the output when you navigate from the Home to Details screen by pressing on a person's name from the list:

Here is the output when using the URL scheme:

You have now finished a complete demo of a React Native app that handles deep linking using React Navigation library.

Deep linking can bring significant improvements to the user experience of your mobile apps and enable search engines to provide context-sensitive searches and results. Hopefully, this guide will help you achieve great results in your own app.