React Native Deep Linking and the Unhandled URL UI

Deep linking lets a URL open a specific screen in your app, but the feature people forget is the unhandled case: a link that matches no route, arrives malformed, or lands on a cold start. Handled badly, it shows a blank screen or crashes. VP0 is the free, AI-readable iOS design library builders start from for these screens, including the graceful fallback, so a bad link still lands somewhere sensible.

Who this is for

You are building a React Native or Expo app, maybe with Cursor or Claude Code, that opens links from email, notifications, or the web, and you want deep linking that never dead-ends the user. This is the pattern.

The two link types, and why universal links win

There are two ways into your app. A custom scheme like myapp:// is simple but only works when the app is installed and is easy to spoof. A universal link is a normal https URL that opens your app when installed and falls back to your website otherwise. Apple covers the setup in its universal links guide, which needs an associated domain entitlement and an apple-app-site-association file on your server. Prefer universal links for anything you send to real users.

Read the URL on both paths

A link reaches your app two ways, and you must wire both. The React Native Linking API gives you getInitialURL for a cold start and an event listener for links that arrive while the app runs. Route both through one handler. In Expo, expo-router linking maps paths to file-based routes for you, which removes most of the manual parsing, and the React Native navigation guide shows how the navigator fits in. Miss the cold-start path and a tap from quit state silently does nothing.

Map every link, including the ones that match nothing

The table below is the core of a resilient deep-link handler.

Incoming link	What it should do	Failure to avoid
Known path, valid data	Open the target screen	Slow parse that blanks the screen
Known path, missing data	Open with a loading or empty state	Crash on a nil value
Unknown or malformed path	Show the unhandled-URL fallback	Blank screen or hard crash
Expired or revoked link	Explain and route home	Pretending it worked

The unhandled-URL screen is the one most apps skip. It needs one honest sentence, that the link could not be opened, and one button that routes to a safe home. Speed matters here too: the BBC lost an extra 10% of users for every additional second its site took to load, and a deep link that hangs feels the same way. Build the fallback as a real screen, the same care a bolt and Expo routing fix brings to navigation, and reuse your standard layout, like the Reanimated bottom sheet template, so it feels native.

A worked example: a password reset link

Picture a password reset. The user taps a link in your email, a universal link to https://yourapp.com/reset with a token. If the app is installed, iOS opens it, your handler reads the /reset path and the token, validates the token with your server, and shows the reset screen. If the token has expired, you do not blank out: you show the unhandled-URL fallback explaining the link is no longer valid, with a button to request a fresh one. If the app is not installed, the same URL opens your website, which offers the App Store link. One link, every case covered, no dead ends. That difference, between a link that always lands somewhere sensible and one that sometimes shows a white screen, is what separates a deep-link feature that delights from one that fills your support inbox.

Common mistakes and fixes

• Only wiring the event listener. Read getInitialURL for cold starts too.
• No fallback screen. Treat the unhandled URL as a first-class route.
• Trusting link data. Validate the path and parameters before you navigate.
• Using only a custom scheme. Add universal links so a missing app still works.
• Blocking the UI while parsing. Show a loading state, never a blank view.

If your target screen is SwiftUI rather than React Native, the same fallback discipline applies, as in this language learning app in SwiftUI.

Key takeaways

• Prefer universal links over custom schemes for real-world links.
• Handle both getInitialURL and the listener so cold starts work.
• Make the unhandled URL a real fallback screen, never a blank view.
• Validate link data before routing, and start from a free VP0 design.

Frequently asked questions

The FAQ above covers handling deep links in React Native and Expo, what an unhandled URL is, schemes versus universal links, and why cold starts behave differently.