Receive links in Flutter

After this page, every link that opens your Flutter app lands on its screen, including the first open after an install.

On this page 6
  1. 1. Route with go_router
  2. 2. Or route with a navigator key
  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 package 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. links.onLink replays past events to late subscribers, so you can subscribe after the first frame without missing the launch link.

1. Route with go_router

If your app uses go_router, subscribe once the router exists:

main.dart
import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'links.dart';

final router = GoRouter(routes: [
  GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
  GoRoute(path: '/product/:id', builder: (_, s) => ProductScreen(id: s.pathParameters['id']!)),
]);

Future<void> main() async {
  await startLinks();
  links.onLink.listen((e) {
    if (e.matched && e.path != null) {
      router.go(Uri(path: e.path, queryParameters: e.params).toString());
    }
  });
  runApp(MaterialApp.router(routerConfig: router));
}

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 ProductScreen with id 42.

2. Or route with a navigator key

Without a router package, use a global key so the listener can navigate from anywhere:

main.dart
final navigatorKey = GlobalKey<NavigatorState>();

void openPath(String path, Map<String, String> params) {
  final product = RegExp(r'^/product/([^/]+)$').firstMatch(path);
  if (product != null) {
    navigatorKey.currentState?.push(MaterialPageRoute(builder: (_) => ProductScreen(id: product.group(1)!)));
  }
}

Future<void> main() async {
  await startLinks();
  runApp(MaterialApp(navigatorKey: navigatorKey, home: const HomeScreen()));
  links.onLink.listen((e) { if (e.matched && e.path != null) openPath(e.path!, e.params ?? {}); });
}

You should see: the same Product screen, with the app closed and with it in the background.

3. Show a loading state (optional)

links.onLinkStart fires as soon as a link arrives, before a short link is resolved:

Dart
links.onLinkStart.listen((_) => showOpening.value = true);   // a ValueNotifier<bool> your UI watches
links.onLink.listen((_) => showOpening.value = false);

You should see: your spinner for a moment on a slow connection, then the screen.

When matched is false, reason says why: not_found, expired, password_protected, no_match, network or invalid_url. The app is already open, so stay on the home screen.

You should see: a link to a slug that doesn't exist opens the home screen with e.reason == 'not_found'.

Common errors

  • The screen opens twice. Flutter's built-in deep linking is still on. Set flutter_deeplinking_enabled to false (Install & set up, step 3).
  • Nothing happens on a cold start. Navigation ran before runApp. Subscribe after runApp, or use go_router, which queues the location.
  • The path has your domain in it. Use e.path, not e.url.

Next steps