Learn

URIs, deep links, and restoration

Encode typed destinations, keep old links working, rebuild parent stacks, and filter platform links before routing.

v1.1.0Intermediate
Source: doc/uri_and_platform_links.md ↗

URIs, deep links, and restoration

Feature code passes typed Destinations. URI parsing stays inside the Route Definition.

Encode path and query fields

dart
final searchCodec = CallbackNavigationUriCodec<SearchDestination>(
  pattern: '/search',
  encoder: (destination) => Uri(
    path: '/search',
    queryParameters: <String, String>{
      'q': destination.query,
      if (destination.category != null) 'category': destination.category!,
    },
  ),
  decoder: (match) => SearchDestination(
    query: match.uri.queryParameters['q'] ?? '',
    category: match.uri.queryParameters['category'],
  ),
);

Callers still use SearchDestination(query: 'keyboard'); no page receives a raw query map.

If /products/42 requires Home and Catalog below it:

dart
stackPlanBuilder: (product) => <NavigationTarget<Object?>>[
  const NavigationTarget<Object?>(destination: HomeDestination()),
  const NavigationTarget<Object?>(destination: CatalogDestination()),
  NavigationTarget<Object?>(destination: product),
],

A direct link produces [Home, Catalog, Product], so Back behaves like an in-app journey.

Keep a legacy URL without generating it

Add a NavigationUriAlias for /item/:id. The canonical codec continues to encode /products/:id, while both forms decode to the same Destination.

dart
final links = NavigationPlatformLinkConfiguration(
  domains: <NavigationLinkDomain>[
    NavigationLinkDomain(
      scheme: 'https',
      host: 'example.com',
      pathPrefixes: const <String>['/app'],
    ),
  ],
);

This is an application boundary, not a substitute for Android App Links or iOS Universal Links configuration. Configure the platform files too.

Use sessionOnly for Destinations that cannot be serialized. They can sit above a restorable route, but they are omitted after restart.