Awesome Open Source
Awesome Open Source


Build Status npm version NPM Downloads


React Native deep linking library. If you need to handle deep links in your project, just create a schemes config, the package will do the rest!

Why do I need this package?

This package allows you to handle deep links in React Native applications. The package can be added to your project irrespective of what solution you are using for navigation, what state management library you decided to use. I will try to provide some examples below just to show why you may need this package.

If you are using react-navigation, you should know that it supports deep linking out of the box, but sometimes this solution does not meet your needs well.

React-navigation deep linking implementation only allows you to navigate user to some screen when application receives the url. This package provides you an ability to decide how to handle the url by specifying your own handler in the config, read the docs below.

Also, in real applications it is a common practice to add navigation state to Redux. According to the react-navigation documentation, in this case you have to handle deep links manually, react-native-deep-link provides a solution. Adding navigation to Redux gives you more control on the navigation state, allows to dispatch navigation actions from your redux-thunk actions.

The package does not require Redux as a dependency, so you can use it in your React Native apps without Redux. For example, you can implement your own NavigationService as it is described in react-navigation docs and use it in route callbacks, read the docs below.


yarn add react-native-deep-link
# or with npm
# npm install --save react-native-deep-link

Configuring Android

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.


Configuring iOS

On iOS, you'll need to link RCTLinking to your project by following the steps described here. If you also want to listen to incoming app links during your app's execution, you'll need to add the following lines to your *AppDelegate.m:

// iOS 9.x or newer
#import <React/RCTLinkingManager.h>

- (BOOL)application:(UIApplication *)application
   openURL:(NSURL *)url
   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
  return [RCTLinkingManager application:application openURL:url options:options];

If you're targeting iOS 8.x or older, you can use the following code instead:

// iOS 8.x or older
#import <React/RCTLinkingManager.h>

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
  return [RCTLinkingManager application:application openURL:url
                      sourceApplication:sourceApplication annotation:annotation];

If your app is using Universal Links, you'll need to add the following code as well:

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
 return [RCTLinkingManager application:application


An Example of usage this package in the Redux application available in the example/ folder.

In the NavigationServiceExample/ folder you can find an example of usage the package in the application without Redux.


After installing the package, you need to follow a few simple steps:

  1. Use createDeepLinkingHandler to get a higher order component, pass schemes config to this function.
import { createDeepLinkingHandler } from 'react-native-deep-link';

 * This function receives a result of url parsing,
 * you can find the structure of this object in the API docs below, and returns a function.
 * The returned function receives component props.
const handleInvitationToChannel = ({ params: { channelId } }) => ({ dispatch }) => {
    // addCurrentUserToChannel is a redux-thunk action,
    // which was defined somewhere in the code.

const schemes = [
        name: 'example:',
        routes: [
                expression: '/channels/:channelId',
                callback: handleInvitationToChannel

const withDeepLinking = createDeepLinkingHandler(schemes);
  1. Use the higher-order component returned from createDeepLinkingHandler.
export default compose(
    connect(mapStateToProps, mapDispatchToProps),

That was it, you have added react-native-deep-link package to the project!

Optionally, if you need to handle situations, when the url is not supported or a handler was not found for the url, you can pass callbacks to withDeepLinking:

import { createDeepLinkingHandler } from 'react-native-deep-link';

const App = createDeepLinkingHandler(schemes)(AppComponent);

class Root extends Component {
    render() {
        return (
                onGetInitialUrlError={err => console.log(err)}
                onCanOpenUrlError={err => console.log(err)}
                onUrlIsNotSupported={url => console.log(`The ${url} is not supported.`)}
                onCannotHandleUrl={url => console.log(`A handler for the ${url} was not found.`)}


createDeepLinkingHandler takes an array of schemes as a parameter. Each scheme should have a name and an array of routes.

Each route should have an expression and a callback to be invoked in case of successful matching of the url to the route specified using an expression property. Follow the next pattern to specify named url parameters :<parameter_name>. Examples: /users/:userId, /conversations/:conversationId/messages/:messageId.

Route callback is a higher-order function which receives the result of url parsing and returns a function. This returned function receives component props.

A result of url parsing is an object with the next set of properties:

    scheme: 'example:', // Scheme name
    route: '/colors/:color', // Route expression
    query: {}, // Query string parameters
    params: {} // Url parameters

createDeepLinkingHandler returns a higher order component, the next props can be passed to this component:

Property Type Optional Default Description
onGetInitialUrlError function true () => {} a callback, which will be called in case the application throws an error trying to get initial url. The function receives the error.
onCanOpenUrlError function true () => {} a callback, which will be called in case the application throws an error trying to open url. The function receives the error.
onUrlIsNotSupported function true () => {} a callback, which will be called in case the application does not support received url. The function receives the url.
onCannotHandleUrl function true () => {} a callback, which will be called in case a handler for the given url was not specified. The function receives the url.


You are welcome! Create pull requests and help to improve the package.


react-native-deep-link is licensed under the MIT License.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (68,711
android (6,226
react (5,295
ios (3,545
react-native (1,502

Find Open Source By Browsing 7,000 Topics Across 59 Categories