Current field guide · 2026
Choose your next destination
Start with a URL contract, then work through matching, navigation, nested stacks, and resilient links.
Your first route
Connect a URL to a screen, then prove that the same destination works after a reload.
02Think in destinations
A route configuration describes which screens belong to a location; navigation changes that location.
03go, push, and the way back
Use go for a destination described by your route tree; use push when you deliberately want another page on the current stack.
04Make the URL carry the right state
Read required identifiers from pathParameters and optional filters from state.uri.queryParameters.
05Build a meaningful route tree
A nested route declares a child destination and can create a matching parent-and-child page stack.
06Redirect without losing the destination
Return a replacement location when a routing condition requires it; return null when navigation may proceed.
07Name a destination once
A named route lets callers refer to a destination without repeating its path template.
08Leave a form deliberately
Protect unsaved work with a clear exit decision, and test every way a user can leave.
09Make a deep link survive reload
Clean paths require both Flutter URL configuration and a host that serves the app entry point for valid application routes.
10Trace the route, not the symptom
Inspect the requested URI, matched hierarchy, redirect decisions, and selected Navigator before changing your configuration.
11Animate the relationship between screens
Use a custom page transition to communicate navigation, and respect users who request less motion.
12Load a resource after matching its URL
Use the URL to identify data, then give loading, missing, error, and ready states explicit UI.
13Give every tab its own journey
Use StatefulShellRoute when parallel destinations need independent navigation histories and retained branch state.
14From navigatorBuilder to shells
The old navigatorBuilder article is preserved, while new route layouts should use the supported shell APIs.
15Choose which Navigator owns a page
A root Navigator and a shell Navigator serve different purposes; use keys when a destination must appear above the shell.
16Make Back feel inevitable
Test browser history as part of your navigation contract rather than assuming it mirrors a mobile stack.
17Move route mistakes into analysis
Generated route types can replace repeated string construction with typed route objects.
18One destination, several entry points
A working web route and a verified Android or iOS app link are separate parts of the same user journey.
19Retain a journey across interruptions
Separate state retained in a live tab from state restored after the application process is recreated.
20Test journeys, not only matches
Verify the requested URI, the visible screen, the navigation frame, and the way back.
Sources & version context
GoRouter.dev documentation edition. Examples illustrate the APIs described in the linked primary documentation. Adapt application-owned widgets and services to your project. They are not an executed Flutter session in this browser.