go_router in Flutter: Deep Linking, Nested Navigation, and Web URLs

Coding Liquids tutorial cover featuring Sagnik Bhattacharya for go_router in Flutter, with nested routes and deep-link visuals.
Coding Liquids tutorial cover featuring Sagnik Bhattacharya for go_router in Flutter, with nested routes and deep-link visuals.

go_router is Flutter's URL-based routing package, and it handles deep links, nested navigation and web URLs by mapping each URL path to a screen. A deep link opens the same screens as the matching route, and nested shells such as tab bars keep their own navigators. Routing stops being a small topic once your app needs guarded routes as well, so keep the route map readable.

The Complete Flutter Course: Build Android, iOS and Web apps

Go from scratch to building industry-standard apps with Riverpod, Firebase, animations, REST APIs, and more.

By Sagnik Bhattacharya and Paulina Knop

Buy now

The goal is not to make routing feel fancy. It is to make app navigation understandable enough that several developers can work on it without fear.

When should you use go_router in Flutter?

Use go_router when your app needs URL-aware navigation, deep links, or nested shells that should stay consistent across mobile and web. Keep the route map readable and avoid turning it into a second business-logic layer.

  • You need deep links or clean browser URLs.
  • Your app has nested navigation or tab shells.
  • You want routing decisions to stay explicit and maintainable.

Why use go_router for deep links and web URLs?

go_router suits deep links and web URLs because it gives navigation concerns a clearer structure once URL state matters. That makes Flutter web, guarded routes, and nested shells easier to reason about than ad hoc route handling.

What do teams get wrong with go_router?

Teams most often get go_router wrong by loading too much logic into the route map. Routing should describe navigation shape and light guards, not replace feature state or application services.

The Complete Flutter Course: Build Android, iOS and Web apps

Go from scratch to building industry-standard apps with Riverpod, Firebase, animations, REST APIs, and more.

By Sagnik Bhattacharya and Paulina Knop

Buy now

How do you keep go_router routes maintainable?

Keep go_router routes maintainable by grouping them by feature, keeping guards readable, and making route names or paths obvious. If route setup starts feeling magical, future maintenance usually gets worse, not better.

Worked example: a multi-tab admin app

An admin app has overview, customers, orders, and settings, each with nested detail pages. go_router helps keep deep links, browser navigation, and nested shell behaviour aligned instead of scattering route handling through the widget tree.

If you want to build routing like this inside a complete app, try The Complete Flutter Course on Coding Liquids.

Common mistakes

  • Putting business rules in the route map.
  • Letting route files grow without feature boundaries.
  • Ignoring web URL behaviour until late in the build.

When should you use something other than go_router?

Use something other than go_router when the real problem is app structure or device layout rather than navigation.

If the bigger issue is overall app structure, read Flutter architecture. If the pain is primarily layout adaptation across devices, responsive UI may help more immediately.

The Complete Flutter Course: Build Android, iOS and Web apps

Go from scratch to building industry-standard apps with Riverpod, Firebase, animations, REST APIs, and more.

By Sagnik Bhattacharya and Paulina Knop

Buy now

Frequently asked questions

Do I need go_router, or is Navigator enough in Flutter?

For a small app without complex deep linking, Navigator with push and pop is enough. Flutter's docs recommend a routing package such as go_router for a web app with a direct link to each screen or an app with several Navigators, as in a tab shell; being declarative, it always shows the same screens for a deep link. They advise against MaterialApp.routes named routes for most apps: a deep link always pushes a new route wherever the user is, and the browser forward button is not supported.

How do I redirect to the login page in go_router when the user is signed out?

Give GoRouter a top-level redirect that returns '/login' when the user is signed out and null to show the requested route; returning the requested path also counts as no redirect, so /login does not loop. Check state.matchedLocation == '/login' to send a signed-in user from the login page to home. Pass your auth ChangeNotifier as refreshListenable so signing in or out re-runs the redirect without a context.go call.

How do I keep each bottom navigation tab's back stack with go_router?

Use StatefulShellRoute.indexedStack with one StatefulShellBranch per tab. Each branch gets its own Navigator, so a tab keeps its history, such as an open customer detail page, while the user visits another tab. The shell's builder receives a StatefulNavigationShell: use it as the Scaffold body and call navigationShell.goBranch(index) from the bar. Pass initialLocation: index == navigationShell.currentIndex so tapping the active tab returns to its first screen.

What is the difference between context.go and context.push in go_router?

go replaces the stack and push adds to it. context.go('/orders/42') shows the screens configured for that location, the same ones a deep link to it opens. context.push puts a screen on top of whatever is open and can await a result returned with context.pop(value). go_router's docs warn that this imperative style can cause issues with browser history, so on the web prefer go for screens people bookmark or share.

How do I remove the # from Flutter web URLs with go_router?

Switch Flutter web from its default hash URLs, such as /#/orders, to path URLs. Add flutter_web_plugins as an SDK dependency in pubspec.yaml (you can't add it directly with pub add), then call usePathUrlStrategy() from package:flutter_web_plugins/url_strategy.dart before runApp. Path URLs use the browser History API, so your host must rewrite any path that isn't a real file to index.html; on Firebase Hosting, choose the single-page app option. The flutter run -d chrome server already does this, so test on the real host.

How do I deep link to a detail page like /customers/42 with go_router?

Nest the detail route under the list route and read the ID from state.pathParameters: inside the routes of /customers, add GoRoute(name: 'customer', path: ':id', builder: (context, state) => CustomerPage(id: state.pathParameters['id']!)). A sub-route stacks above its parent, so a link to /customers/42 opens the detail with the list beneath it, and back returns to the list. Navigate with context.goNamed('customer', pathParameters: {'id': '42'}) so screens don't hard-code paths.

Sagnik Bhattacharya, founder of Coding Liquids, has written more than 120 free Flutter tutorials for this site, including this one. To go from single topics like this one to a complete app, The Complete Flutter Course at codingliquids.com walks through state management, Firebase, animations and REST APIs inside projects you actually ship.

Related tutorials

If you want to keep going without opening dead ends, these are the most useful next reads from this site.

Official references

These official references are useful if you need the product or framework documentation alongside this guide.