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
- 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:
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
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:
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.
4. Handle links that don't match
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.navigateran before the navigator was ready. Subscribe inonReady, as above. - The path has your domain in it. Use
e.path, note.url.e.urlis 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.