{"id":896,"date":"2026-04-24T13:00:00","date_gmt":"2026-04-24T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=896"},"modified":"2026-03-07T03:48:33","modified_gmt":"2026-03-07T08:48:33","slug":"flutter-go-router-deep-links","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/flutter-go-router-deep-links\/","title":{"rendered":"Flutter go_router Deep Links: Routing Guide"},"content":{"rendered":"\n

go_router is the recommended routing package for Flutter apps. It handles deep linking natively: define your routes with URL patterns, and go_router automatically matches incoming deep links to the correct screen. This guide covers the routing patterns you need for production deep linking.<\/p>\n\n\n\n

For the platform-level configuration (Associated Domains, intent filters), see Flutter Deep Linking: Complete Setup Tutorial<\/a>. For a cross-platform overview, see Cross-Platform Deep Linking Guide<\/a>.<\/p>\n\n\n\n

Basic Route Setup<\/h2>\n\n\n\n

Install go_router<\/h3>\n\n\n\n
# pubspec.yaml\ndependencies:\n  go_router: ^14.0.0\n<\/code><\/pre>\n\n\n\n
Define Routes<\/h3>\n\n\n\n
final GoRouter router = GoRouter(\n  routes: [\n    GoRoute(\n      path: '\/',\n      builder: (context, state) => const HomeScreen(),\n    ),\n    GoRoute(\n      path: '\/product\/:id',\n      builder: (context, state) {\n        final id = state.pathParameters['id']!;\n        return ProductScreen(id: id);\n      },\n    ),\n    GoRoute(\n      path: '\/category\/:slug',\n      builder: (context, state) {\n        final slug = state.pathParameters['slug']!;\n        return CategoryScreen(slug: slug);\n      },\n    ),\n    GoRoute(\n      path: '\/invite\/:code',\n      builder: (context, state) {\n        final code = state.pathParameters['code']!;\n        return InviteScreen(code: code);\n      },\n    ),\n  ],\n  errorBuilder: (context, state) => const NotFoundScreen(),\n);\n<\/code><\/pre>\n\n\n\n
Use with MaterialApp<\/h3>\n\n\n\n
class MyApp extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp.router(\n      routerConfig: router,\n    );\n  }\n}\n<\/code><\/pre>\n\n\n\n
When the OS delivers a deep link like https:\/\/go.yourapp.com\/product\/456<\/code>, go_router strips the scheme and host, matches \/product\/456<\/code> against your route patterns, and renders ProductScreen(id: "456")<\/code>.<\/p>\n\n\n\n
Nested Routes<\/h2>\n\n\n\n
ShellRoute for Persistent UI<\/h3>\n\n\n\n
Most apps have a bottom navigation bar that persists across screens. Use ShellRoute<\/code> to keep the scaffold while deep links navigate the inner content:<\/p>\n\n\n\n
final router = GoRouter(\n  routes: [\n    ShellRoute(\n      builder: (context, state, child) {\n        return ScaffoldWithBottomNav(child: child);\n      },\n      routes: [\n        GoRoute(\n          path: '\/',\n          builder: (context, state) => const HomeScreen(),\n          routes: [\n            GoRoute(\n              path: 'product\/:id',\n              builder: (context, state) {\n                final id = state.pathParameters['id']!;\n                return ProductScreen(id: id);\n              },\n            ),\n          ],\n        ),\n        GoRoute(\n          path: '\/search',\n          builder: (context, state) => const SearchScreen(),\n          routes: [\n            GoRoute(\n              path: 'results',\n              builder: (context, state) {\n                final query = state.uri.queryParameters['q'] ?? '';\n                return SearchResultsScreen(query: query);\n              },\n            ),\n          ],\n        ),\n        GoRoute(\n          path: '\/profile',\n          builder: (context, state) => const ProfileScreen(),\n        ),\n      ],\n    ),\n  ],\n);\n<\/code><\/pre>\n\n\n\n
Deep link to \/product\/123<\/code> shows ProductScreen inside the ScaffoldWithBottomNav, with the Home tab selected. Deep link to \/search\/results?q=shoes<\/code> shows SearchResultsScreen with the Search tab selected.<\/p>\n\n\n\n
StatefulShellRoute for Tab State Preservation<\/h3>\n\n\n\n
If you want each tab to maintain its own navigation state (so switching tabs doesn't reset the stack):<\/p>\n\n\n\n
final router = GoRouter(\n  routes: [\n    StatefulShellRoute.indexedStack(\n      builder: (context, state, navigationShell) {\n        return ScaffoldWithBottomNav(navigationShell: navigationShell);\n      },\n      branches: [\n        StatefulShellBranch(\n          routes: [\n            GoRoute(\n              path: '\/',\n              builder: (context, state) => const HomeScreen(),\n              routes: [\n                GoRoute(\n                  path: 'product\/:id',\n                  builder: (context, state) {\n                    return ProductScreen(id: state.pathParameters['id']!);\n                  },\n                ),\n              ],\n            ),\n          ],\n        ),\n        StatefulShellBranch(\n          routes: [\n            GoRoute(\n              path: '\/search',\n              builder: (context, state) => const SearchScreen(),\n            ),\n          ],\n        ),\n        StatefulShellBranch(\n          routes: [\n            GoRoute(\n              path: '\/profile',\n              builder: (context, state) => const ProfileScreen(),\n            ),\n          ],\n        ),\n      ],\n    ),\n  ],\n);\n<\/code><\/pre>\n\n\n\n
Query Parameters<\/h2>\n\n\n\n
Access query parameters through state.uri.queryParameters<\/code>:<\/p>\n\n\n\n
GoRoute(\n  path: '\/search',\n  builder: (context, state) {\n    final query = state.uri.queryParameters['q'] ?? '';\n    final sort = state.uri.queryParameters['sort'] ?? 'relevance';\n    final page = int.tryParse(state.uri.queryParameters['page'] ?? '1') ?? 1;\n    return SearchScreen(query: query, sort: sort, page: page);\n  },\n),\n<\/code><\/pre>\n\n\n\n
URL: https:\/\/go.yourapp.com\/search?q=shoes&sort=price&page=2<\/code><\/p>\n\n\n\n
Authentication Guards with Redirect<\/h2>\n\n\n\n
Deep links often target screens that require authentication. go_router's redirect<\/code> function handles this:<\/p>\n\n\n\n
final router = GoRouter(\n  redirect: (context, state) {\n    final isLoggedIn = authService.isLoggedIn;\n    final isLoginRoute = state.matchedLocation == '\/login';\n\n    \/\/ If not logged in and not already on login, redirect to login\n    if (isLoggedIn == false && isLoginRoute == false) {\n      \/\/ Save the intended destination for after login\n      return '\/login?redirect=${Uri.encodeComponent(state.uri.toString())}';\n    }\n\n    \/\/ If logged in and on login page, redirect to home\n    if (isLoggedIn && isLoginRoute) {\n      return '\/';\n    }\n\n    return null; \/\/ No redirect\n  },\n  routes: [\n    GoRoute(\n      path: '\/login',\n      builder: (context, state) {\n        final redirect = state.uri.queryParameters['redirect'];\n        return LoginScreen(redirectAfterLogin: redirect);\n      },\n    ),\n    GoRoute(\n      path: '\/',\n      builder: (context, state) => const HomeScreen(),\n    ),\n    GoRoute(\n      path: '\/product\/:id',\n      builder: (context, state) {\n        return ProductScreen(id: state.pathParameters['id']!);\n      },\n    ),\n  ],\n);\n<\/code><\/pre>\n\n\n\n
After login, navigate to the saved redirect URL:<\/p>\n\n\n\n
class LoginScreen extends StatelessWidget {\n  final String? redirectAfterLogin;\n\n  const LoginScreen({this.redirectAfterLogin});\n\n  void onLoginSuccess(BuildContext context) {\n    if (redirectAfterLogin != null) {\n      context.go(Uri.decodeComponent(redirectAfterLogin!));\n    } else {\n      context.go('\/');\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
This way, https:\/\/go.yourapp.com\/product\/123<\/code> for an unauthenticated user shows the login screen, and after login, automatically navigates to the product.<\/p>\n\n\n\n
Route-Level Redirects<\/h3>\n\n\n\n
For redirects that apply to specific routes (not globally):<\/p>\n\n\n\n
GoRoute(\n  path: '\/admin',\n  redirect: (context, state) {\n    if (authService.isAdmin == false) {\n      return '\/'; \/\/ Non-admins redirected to home\n    }\n    return null;\n  },\n  builder: (context, state) => const AdminScreen(),\n),\n<\/code><\/pre>\n\n\n\n
Handling Legacy URLs<\/h2>\n\n\n\n
If you're migrating from another platform, your old links may use different URL patterns. Handle legacy paths with redirects:<\/p>\n\n\n\n
final router = GoRouter(\n  redirect: (context, state) {\n    final path = state.matchedLocation;\n\n    \/\/ Legacy: \/item\/123 \u2192 \/product\/123\n    if (path.startsWith('\/item\/')) {\n      return path.replaceFirst('\/item\/', '\/product\/');\n    }\n\n    \/\/ Legacy: \/p?id=123 \u2192 \/product\/123\n    if (path == '\/p') {\n      final id = state.uri.queryParameters['id'];\n      if (id != null) return '\/product\/$id';\n    }\n\n    return null;\n  },\n  routes: [\n    \/\/ Current routes...\n  ],\n);\n<\/code><\/pre>\n\n\n\n
TypeSafe Routes with Extra Data<\/h2>\n\n\n\n
go_router supports passing typed data alongside URL parameters:<\/p>\n\n\n\n
GoRoute(\n  path: '\/product\/:id',\n  builder: (context, state) {\n    \/\/ URL parameter (always a string)\n    final id = state.pathParameters['id']!;\n\n    \/\/ Extra data passed programmatically (not from URL)\n    final product = state.extra as Product?;\n\n    return ProductScreen(id: id, preloadedProduct: product);\n  },\n),\n<\/code><\/pre>\n\n\n\n
When navigating in-app, you can pass the full object:<\/p>\n\n\n\n
context.go('\/product\/123', extra: product);\n<\/code><\/pre>\n\n\n\n
When arriving via deep link, state.extra<\/code> is null, and the screen fetches the product using the ID from the URL. This pattern lets you optimize in-app navigation (no re-fetch) while still handling deep links correctly.<\/p>\n\n\n\n
Error Handling<\/h2>\n\n\n\n
Custom Error Screen<\/h3>\n\n\n\n
final router = GoRouter(\n  errorBuilder: (context, state) {\n    return ErrorScreen(\n      message: 'Page not found: ${state.uri.path}',\n    );\n  },\n  routes: [\n    \/\/ ...\n  ],\n);\n<\/code><\/pre>\n\n\n\n
Handling Invalid Parameters<\/h3>\n\n\n\n
Validate parameters in your route builders:<\/p>\n\n\n\n
GoRoute(\n  path: '\/product\/:id',\n  builder: (context, state) {\n    final idStr = state.pathParameters['id'];\n    final id = int.tryParse(idStr ?? '');\n\n    if (id == null) {\n      return const NotFoundScreen();\n    }\n\n    return ProductScreen(id: id);\n  },\n),\n<\/code><\/pre>\n\n\n\n
Debugging<\/h2>\n\n\n\n
Enable diagnostic logging:<\/p>\n\n\n\n
final router = GoRouter(\n  debugLogDiagnostics: true,\n  routes: [\n    \/\/ ...\n  ],\n);\n<\/code><\/pre>\n\n\n\n
This prints to the console:<\/p>\n\n\n\n
GoRouter: setting initial location \/\nGoRouter: Using MaterialApp configuration\nGoRouter: going to \/product\/123\nGoRouter: pushing \/product\/123\n<\/code><\/pre>\n\n\n\n
Testing Routes<\/h2>\n\n\n\n
Test your route configuration:<\/p>\n\n\n\n
import 'package:flutter_test\/flutter_test.dart';\n\nvoid main() {\n  test('product route matches \/product\/:id', () {\n    final match = router.configuration.findMatch('\/product\/123');\n    expect(match.uri.path, '\/product\/123');\n    expect(match.pathParameters['id'], '123');\n  });\n\n  testWidgets('deep link navigates to product screen', (tester) async {\n    await tester.pumpWidget(\n      MaterialApp.router(routerConfig: router),\n    );\n\n    router.go('\/product\/456');\n    await tester.pumpAndSettle();\n\n    expect(find.byType(ProductScreen), findsOneWidget);\n  });\n}\n<\/code><\/pre>\n\n\n\n
For the Tolinku SDK integration, see the Flutter SDK docs<\/a>. For routing architecture, see Deep Link Routing Guide<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Set up deep linking with Flutter go_router. Define route patterns, handle redirects, and manage authentication guards for deep link routes.<\/p>\n","protected":false},"author":2,"featured_media":895,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Flutter go_router Deep Links: Routing Guide","rank_math_description":"Set up deep linking with Flutter go_router. Define route patterns, handle redirects, and manage authentication guards for deep link routes.","rank_math_focus_keyword":"Flutter go_router deep links","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-flutter-go-router-deep-links.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-flutter-go-router-deep-links.png","footnotes":""},"categories":[15],"tags":[25,179,20,57,180,24,69,183],"class_list":["post-896","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-engineering","tag-android","tag-dart","tag-deep-linking","tag-flutter","tag-go-router","tag-ios","tag-mobile-development","tag-routing"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/896","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=896"}],"version-history":[{"count":1,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/896\/revisions"}],"predecessor-version":[{"id":897,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/896\/revisions\/897"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/895"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=896"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=896"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=896"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}