Routing with go_router

Why a router?

Navigator.push works well inside small apps. Larger apps need more: a URL for every screen (so the web version's address bar and browser back button work), deep links (opening a specific product from a notification or a shared link), and central rules such as "if not logged in, go to /login". A router package handles these. go_router is a popular choice maintained by the Flutter team (publisher flutter.dev).

flutter pub add go_router

Defining routes

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

final router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'product/:id',                       // full path: /product/42
          builder: (context, state) {
            final id = int.parse(state.pathParameters['id']!);
            return ProductScreen(productId: id);
          },
        ),
      ],
    ),
    GoRoute(path: '/cart', builder: (context, state) => const CartScreen()),
    GoRoute(path: '/login', builder: (context, state) => const LoginScreen()),
  ],
);

void main() => runApp(MaterialApp.router(routerConfig: router));

Routes can be nested: the product route above is a child of /, so its full path is /product/42, and opening it directly (from a deep link) builds Home underneath it, so the back button leads somewhere sensible. Keep the route list in one file so the whole app's map is easy to read.

Pass ids in the path (/product/42) rather than whole objects. A path survives a browser refresh, can be shared as a link, and lets the screen load fresh data. go_router also has a state.extra field for passing objects, but it is lost when the web page reloads.

Moving around

Redirects for login

final router = GoRouter(
  redirect: (context, state) {
    final loggedIn = authService.isLoggedIn;            // your own auth state
    final goingToLogin = state.matchedLocation == '/login';
    if (!loggedIn && !goingToLogin) return '/login';
    if (loggedIn && goingToLogin) return '/';
    return null;                                        // no redirect
  },
  routes: [ /* ... */ ],
);

ShellRoute for a shared bottom bar

Many apps keep a bottom navigation bar visible while switching tabs. ShellRoute (and StatefulShellRoute, which keeps each tab's own stack) wraps several routes in a shared layout, so the bar stays on screen while the content changes. Check the go_router documentation for the current API, as it evolves.

Common mistakes

• Using MaterialApp(home: ...) instead of MaterialApp.router(routerConfig: router): the router is ignored.
• Mixing context.go and context.push without understanding them: go rebuilds the stack, push adds on top.
• Using int.parse on a path parameter without handling bad input from a deep link; show a "not found" screen instead of crashing.
• Putting large objects in state.extra and expecting them to survive a web refresh: they do not. Pass ids in the path.