Receive links in React Native

After this page, every link that opens your React Native app lands on its screen, from a closed app, from the background, and on the first open after an install.

On this page 6
  1. 1. Map paths to screens
  2. 2. Subscribe when the navigator is ready
  3. 3. Show a loading state (optional)
  4. 4. Handle links that don't match
  5. Common errors
  6. Next steps
Time
About 10 minutes
You need
The SDK installed and started (Install & set up)
Works on
Android, iPhone

e.path is the destination's path (/product/42) and e.params its query parameters. One onLink callback covers every case. Expo Router has its own recipe on the Expo page.

1. Map paths to screens

Keep the mapping in one place, using a navigation ref so it works outside components:

navigation.ts
import { createNavigationContainerRef } from '@react-navigation/native';

export const navigationRef = createNavigationContainerRef<any>();

// Map a link's path to one of your screens.
export function openPath(path: string, params: Record<string, string> = {}) {
  const product = /^\/product\/([^/]+)$/.exec(path);
  if (product) navigationRef.navigate('Product', { id: product[1], ...params });
  else navigationRef.navigate('Home');
}

You should see: the app compiles. Nothing calls openPath yet.

2. Subscribe when the navigator is ready

App.tsx
import { NavigationContainer } from '@react-navigation/native';
import { links } from './links';
import { navigationRef, openPath } from './navigation';

export default function App() {
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => links.onLink((e) => e.matched && e.path && openPath(e.path, e.params))}
    >
      {/* your navigator */}
    </NavigationContainer>
  );
}

Don't also list your link domain in React Navigation's linking option, or each link is handled twice.

You should see: with the app closed, adb shell am start -W -a android.intent.action.VIEW -d "yourapp://shop.example.com/product/42" opens the Product screen with id 42. Run it again with the app in the background: same screen.

3. Show a loading state (optional)

A short link can take a second or more to resolve on a slow network. onLinkStart fires as soon as a link arrives:

LinkLoading.tsx
import { useEffect, useState } from 'react';
import { ActivityIndicator, StyleSheet } from 'react-native';
import { links } from './links';

export function LinkLoading() {
  const [opening, setOpening] = useState(false);
  useEffect(() => {
    const offStart = links.onLinkStart(() => setOpening(true));
    const offLink = links.onLink(() => setOpening(false));
    return () => { offStart(); offLink(); };
  }, []);
  return opening ? <ActivityIndicator style={StyleSheet.absoluteFill} size="large" /> : null;
}

Render <LinkLoading /> once, above your navigator.

You should see: a spinner for a moment when you tap a https://hilltop.strait.link/… link on a slow connection, then the screen.

When matched is false, reason says why: not_found, expired, password_protected, no_match (a first open with no recent tap) or network. The app has already opened, so show your home screen. A first open with no link at all is normal: most installs don't come from a link.

You should see: tapping a link to a slug that doesn't exist opens the app on the home screen, and e.reason is not_found.

Common errors

  • The screen opens twice. Your link domain is also in React Navigation's linking.prefixes. Remove it.
  • Nothing happens on a cold start. navigationRef.navigate ran before the navigator was ready. Subscribe in onReady, as above.
  • The path has your domain in it. Use e.path, not e.url. e.url is the full destination.

Next steps

  • Events & revenue: record purchases on the tap that brought them.
  • Reference: every field of the link event and every method.