expo-linking API

Parsing URLs, listeners, and cold-start vs warm-start handling - the expo-linking cookbook for Expo SDK 57 apps that receive links from email, SMS, QR codes, and other apps.

Recipe

Quick-reference recipe card - copy-paste ready.

import * as Linking from "expo-linking";
import { useEffect } from "react";
import { router } from "expo-router";
 
function routeFromUrl(url: string) {
  const { path, queryParams } = Linking.parse(url);
  const cleanPath = `/${(path ?? "").replace(/^\/+/, "")}`;
  router.push({ pathname: cleanPath as never, params: queryParams ?? {} });
}
 
export function useDeepLinkBootstrap() {
  useEffect(() => {
    Linking.getInitialURL().then((url) => {
      if (url) routeFromUrl(url);
    });
 
    const sub = Linking.addEventListener("url", ({ url }) => routeFromUrl(url));
    return () => sub.remove();
  }, []);
}

When to reach for this:

• Custom analytics or attribution before Expo Router navigates.
• Non–file-based routes (password reset tokens, magic links).
• OAuth return URLs handled outside Router - see auth-session.
• Opening external apps (maps://, mailto:) with openURL.
• Building share sheets and referral links with createURL.

Working Example

// src/linking/useAppLinking.ts
import * as Linking from "expo-linking";
import { router } from "expo-router";
import { useEffect, useRef } from "react";
import { z } from "zod";
 
const orderParams = z.object({
  id: z.string().min(1),
  ref: z.string().optional(),
});
 
function navigateFromUrl(url: string) {
  const parsed = Linking.parse(url);
  const segments = (parsed.path ?? "").split("/").filter(Boolean);
 
  if (segments[0] === "orders" && segments[1]) {
    const result = orderParams.safeParse({
      id: segments[1],
      ref: parsed.queryParams?.ref,
    });
 
    if (!result.success) {
      router.replace("/");
      return;
    }
 
    router.push({
      pathname: "/orders/[id]",
      params: { id: result.data.id, ref: result.data.ref ?? "" },
    });
    return;
  }
 
  router.replace("/");
}
 
type Options = {
  enabled: boolean;
};
 
export function useAppLinking({ enabled }: Options) {
  const handledInitial = useRef(false);
 
  useEffect(() => {
    if (!enabled) return;
 
    Linking.getInitialURL().then((url) => {
      if (!url || handledInitial.current) return;
      handledInitial.current = true;
      navigateFromUrl(url);
    });
 
    const subscription = Linking.addEventListener("url", ({ url }) => {
      navigateFromUrl(url);
    });
 
    return () => subscription.remove();
  }, [enabled]);
}

// app/_layout.tsx
import { Stack } from "expo-router";
import { useAppLinking } from "../src/linking/useAppLinking";
import { useAuthReady } from "../src/auth/useAuthReady";
 
export default function RootLayout() {
  const authReady = useAuthReady();
 
  useAppLinking({ enabled: authReady });
 
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="orders/[id]" options={{ title: "Order" }} />
    </Stack>
  );
}

What this demonstrates:

• Cold start via getInitialURL with a ref guard against double handling.
• Warm start via addEventListener with cleanup on unmount.
• Auth gating - links wait until authReady so protected routes do not flash.
• Zod validation at the linking boundary - malformed URLs fall back to home.
• Expo Router router.push with dynamic pathname and params.

Deep Dive

How It Works

• The OS delivers URLs to your app through custom scheme handlers or verified HTTPS intent filters.
• On launch, the native layer queues the URL; getInitialURL reads it once JavaScript starts.
• While running, new URLs arrive as events on the url channel - same shape { url: string }.
• Expo Router registers its own linking config from app/ - your listener runs in parallel for side effects.
• Linking.parse uses the WHATWG URL parser - invalid URLs return { path: null, queryParams: null }.

Cold Start vs Warm Start

Key API Surface

TypeScript Notes

import * as Linking from "expo-linking";
 
type ParsedLink = ReturnType<typeof Linking.parse>;
 
function queryParam(
  parsed: ParsedLink,
  key: string
): string | undefined {
  const value = parsed.queryParams?.[key];
  return Array.isArray(value) ? value[0] : value;
}

• queryParams values may be string | string[] - normalize before Zod parsing.
• path omits leading slash for custom schemes - normalize before concatenation.
• Use router.push typed routes when experiments.typedRoutes is enabled - invalid paths fail at compile time.

Gotchas

• Handling initial URL before auth resolves - protected screens mount, then redirect, losing deep-link context. Fix: gate useAppLinking({ enabled: authReady }) as shown above.
• Double navigation on cold start - both Expo Router and your hook push the same route. Fix: disable custom navigation when Router linking suffices, or set initialRouteName explicitly.
• Forgetting listener cleanup - Fast Refresh stacks listeners; one link triggers five navigations. Fix: return () => subscription.remove() in useEffect.
• Hardcoding myapp:// strings - breaks across flavors and Expo Go. Fix: always Linking.createURL("orders/42").
• Trusting query params for auth - ?token= in URLs lands in analytics and logs. Fix: exchange tokens server-side; use short-lived one-time codes in links.
• canOpenURL blocked on iOS without LSApplicationQueriesSchemes - always returns false for unlisted schemes. Fix: declare queried schemes in app.config.ts ios.infoPlist.

Alternatives

FAQs

const url = "maps://?q=Coffee+Shop";
if (await Linking.canOpenURL(url)) {
  await Linking.openURL(url);
}

jest.spyOn(Linking, "getInitialURL").mockResolvedValue("shopapp://orders/1");

Related

• Deep Linking Basics - schemes, hosts, and Expo config
• iOS Universal Links - HTTPS links on iOS
• Android App Links - verified Android intents
• Push Notification Deep Links - tap → navigate
• ../expo-router/expo-router-basics/expo-router-basics.md - file-based route mapping
• ../expo-rules/navigation-and-routing-rules/navigation-and-routing-rules.md - param validation rules

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).