One tree of routes,
the URL as truth.

Describe the map, don't drive it.

The old way is imperative: you call Navigator.push and manually manage a stack of screens. GoRouter flips it. You declare the entire route tree once, and the current location (a URL like /orders/42) becomes the single source of truth for what's on screen. Navigating is just changing the location; GoRouter rebuilds the stack to match.

The pieces you'll use

• GoRoute: one entry in the tree. A path, a name, and a builder that returns the screen.
• Nested routes: a routes: list under a parent builds a stack, so /orders/42 sits on top of /orders.
• StatefulShellRoute: parallel branches that each keep their own navigation stack and state, the engine behind a bottom nav bar.
• redirect: a function that can send a location somewhere else before it resolves, the hook for auth guards.

The screen owns its address.

A route is identified by two things: a name for navigating to it, and a location (path) for the URL. Both belong to the screen they point at, declared as static constants on the widget. The router and every navigation call reference those, so a path string exists in exactly one place and can never drift.

// features/auth/views/login_screen.dart
class LoginScreen extends StatelessWidget {
  const LoginScreen({super.key});

  static const String routeName = 'login';
  static const String routeLocation = '/login';

  @override
  Widget build(BuildContext context) => const Scaffold(/* ... */);
}

// the route definition references the screen's own constants
GoRoute(
  name: LoginScreen.routeName,
  path: LoginScreen.routeLocation,
  builder: (context, state) => const LoginScreen(),
),

// and so does every navigation call. no loose strings, anywhere.
context.go(LoginScreen.routeLocation);
context.goNamed(LoginScreen.routeName);

// the same routes, with paths typed out by hand wherever they're needed
GoRoute(path: '/login', builder: (c, s) => const LoginScreen()),

// elsewhere, in a dozen widgets:
context.go('/login');
context.go('/Login');     // typo: silently navigates nowhere
context.go('/log-in');    // someone guessed the path

// rename the route? now grep the codebase and pray.

Parameterized routes keep the same rule

When a screen takes a path parameter, the location const holds the template, and a small helper builds a concrete location so call sites still never assemble a path by hand:

// features/orders/views/order_detail_screen.dart
class OrderDetailScreen extends StatelessWidget {
  const OrderDetailScreen({required this.orderId, super.key});
  final String orderId;

  static const String routeName = 'orderDetail';
  static const String routeLocation = '/orders/:id';   // the template

  // build a real location with the id filled in
  static String locationFor(String id) => '/orders/$id';

  @override
  Widget build(BuildContext context) => const Scaffold(/* ... */);
}

// navigate by name with params (cleanest), or by the helper
context.goNamed(OrderDetailScreen.routeName, pathParameters: {'id': order.id});
context.go(OrderDetailScreen.locationFor(order.id));

Assemble it, feature by feature.

The router is one tree, but you don't write it as one giant file. Each feature exposes its own routes, and a central appRouter composes them. Click any node to see how it's defined.

Tabs that keep their place.

A bottom nav bar where each tab remembers its scroll position, its form input, and how deep you'd drilled, that's StatefulShellRoute.indexedStack. It gives each tab its own independent navigator, all kept alive at once in an IndexedStack. Try it: drill in, switch tabs, come back. Then flip preservation off to feel why it matters.

// core/router/app_router.dart
StatefulShellRoute.indexedStack(
  // the shell is built once; navigationShell drives the tabs
  builder: (context, state, navigationShell) =>
      ScaffoldWithNavBar(navigationShell: navigationShell),
  branches: [
    StatefulShellBranch(routes: [
      GoRoute(
        name: HomeScreen.routeName,
        path: HomeScreen.routeLocation,   // '/home'
        builder: (c, s) => const HomeScreen(),
      ),
    ]),
    StatefulShellBranch(routes: [
      GoRoute(
        name: OrdersScreen.routeName,
        path: OrdersScreen.routeLocation,  // '/orders'
        builder: (c, s) => const OrdersScreen(),
        routes: [
          GoRoute(
            name: OrderDetailScreen.routeName,
            path: ':id',                  // relative, stacks on Orders
            builder: (c, s) => OrderDetailScreen(
              orderId: s.pathParameters['id']!,
            ),
          ),
        ],
      ),
    ]),
    StatefulShellBranch(routes: [
      GoRoute(
        name: ProfileScreen.routeName,
        path: ProfileScreen.routeLocation, // '/profile'
        builder: (c, s) => const ProfileScreen(),
      ),
    ]),
  ],
),

The shell widget

The builder hands you a StatefulNavigationShell. You drop it in as the body and drive the tabs with goBranch. No selected-index state of your own; the shell holds it.

// core/router/scaffold_with_nav_bar.dart
class ScaffoldWithNavBar extends StatelessWidget {
  const ScaffoldWithNavBar({required this.navigationShell, super.key});
  final StatefulNavigationShell navigationShell;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: navigationShell,                       // the IndexedStack of branches
      bottomNavigationBar: NavigationBar(
        selectedIndex: navigationShell.currentIndex,
        onDestinationSelected: _goBranch,
        destinations: const [
          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
          NavigationDestination(icon: Icon(Icons.receipt), label: 'Orders'),
          NavigationDestination(icon: Icon(Icons.person), label: 'Profile'),
        ],
      ),
    );
  }

  void _goBranch(int index) {
    navigationShell.goBranch(
      index,
      // tap the active tab again to pop that branch back to its root
      initialLocation: index == navigationShell.currentIndex,
    );
  }
}

go, push, or goBranch.

Three verbs cover almost everything, and choosing the right one is mostly about what you want the back stack to do. All of them take the screen's static constants, never a raw string.

// move between sections: replace the stack
context.go(ProfileScreen.routeLocation);

// open a detail with a path param, by name
context.goNamed(
  OrderDetailScreen.routeName,
  pathParameters: {'id': order.id},
  queryParameters: {'tab': 'items'},
);

// push a flow you want to return from
final picked = await context.push<Address>(AddressPickerScreen.routeLocation);
if (picked != null) controller.setAddress(picked);

// read params back inside the destination's builder
builder: (context, state) {
  final id = state.pathParameters['id']!;
  final tab = state.uri.queryParameters['tab'];
  return OrderDetailScreen(orderId: id, initialTab: tab);
}

Send them where they belong.

Auth is the classic case: a signed-out user heading for a private screen should land on login instead. GoRouter's redirect runs before a location resolves and can return a different location, or null to proceed. Wire it to your Riverpod auth state so it re-evaluates the moment that state changes.

// core/router/app_router.dart  (plain Dart, no code-gen)
final routerProvider = Provider<GoRouter>((ref) {
  // a Listenable the router refreshes on, fed by auth state
  final refresh = ValueNotifier<int>(0);
  ref.listen(authControllerProvider, (_, __) => refresh.value++);
  ref.onDispose(refresh.dispose);

  return GoRouter(
    initialLocation: SplashScreen.routeLocation,
    refreshListenable: refresh,   // re-runs redirect when auth changes
    redirect: (context, state) {
      final loggedIn = ref.read(authControllerProvider).valueOrNull != null;
      final atLogin = state.matchedLocation == LoginScreen.routeLocation;

      if (!loggedIn && !atLogin) return LoginScreen.routeLocation;
      if (loggedIn && atLogin)  return HomeScreen.routeLocation;
      return null;   // no redirect, let it through
    },
    routes: [ /* the tree from Chapter 3 */ ],
  );
});

// wire it into the app
MaterialApp.router(routerConfig: ref.watch(routerProvider));

How it reads

• The redirect uses route constants for both the check (state.matchedLocation == LoginScreen.routeLocation) and the destination, so there's still no loose string.
• refreshListenable is what makes it reactive: when the user signs in or out, the notifier ticks and GoRouter re-runs the redirect, moving them automatically.
• Per-route redirects exist too: add a redirect: on an individual GoRoute to guard just that subtree.

Where routing trips people.

Most GoRouter bugs are one of these. They're easy to avoid once you've seen them named.