Flutter GoRouter Tutorial: Stop Fighting Navigation and Start Using URLs (2026)

You built a Flutter app. It navigates. Then a user taps a notification, the app opens to the wrong screen. Someone sends a product link, the app just opens the home page. Your back button pops two screens instead of one. You add a bottom navigation bar and suddenly each tab forgets where it was.

All of these are the same problem: Navigator.push() has no concept of URLs. Every screen is a disposable widget on a stack with no address, no identity, and no way for the outside world to reach it. The moment your app gets even slightly complex — deep links, auth flows, web URLs, persistent tabs — it falls apart.

GoRouter fixes all of this. It gives every screen in your Flutter app a real URL path. Navigation becomes declaring where you want to go, not manually stacking and popping widgets. Deep links just work. Auth guards live in one place. The back button behaves. And Flutter’s own team officially recommends it for any app that needs reliable navigation.

This flutter gorouter tutorial starts from zero and builds up to a complete app with named routes, parameter passing, auth guards, a persistent bottom navigation bar, and deep linking — all explained the way a beginner actually needs it.

1. Why GoRouter? The Real Reason to Switch

Plain Navigator.push() works well for simple apps. Here’s exactly where it breaks down — and why each failure points to the same root cause:

The reason Navigator has all these problems is that it is an imperative widget stack — screens have no names, no URLs, no addresses. GoRouter is declarative and URL-based. Every route is a path. That single change fixes all of the above at once.

2. Setup and Installation

# pubspec.yaml
dependencies:
  go_router: ^14.0.0   # published by flutter.dev — check pub.dev for latest

flutter pub get

import 'package:go_router/go_router.dart';

The key setup change: replace MaterialApp with MaterialApp.router. This is the most important conceptual shift when coming from Navigator.push():

// ── BEFORE (plain Navigator) ──────────────────────────────────────────────
MaterialApp(
  home: const HomeScreen(),
  routes: {
    '/profile': (_) => const ProfileScreen(),
    '/settings': (_) => const SettingsScreen(),
  },
)

// ── AFTER (GoRouter) ──────────────────────────────────────────────────────
MaterialApp.router(
  routerConfig: _router, // ← all route definitions live here
)

3. Your First GoRouter: Define Routes and Navigate

Define the router as a top-level final variable — never inside a widget’s build() method. Creating a new router on every rebuild wipes navigation state entirely:

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

void main() {
  runApp(const MyApp());
}

// ── Define the router at the top level (outside any widget) ───────────────
// Never define GoRouter inside build() — it would recreate on every rebuild
final GoRouter _router = GoRouter(
  initialLocation: '/',         // which route to show first
  debugLogDiagnostics: true,    // prints route activity in debug console — very useful!
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/profile',
      builder: (context, state) => const ProfileScreen(),
    ),
    GoRoute(
      path: '/settings',
      builder: (context, state) => const SettingsScreen(),
    ),
  ],
);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      title: 'GoRouter Demo',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo),
        useMaterial3: true,
      ),
      routerConfig: _router, // ← wire up the router
    );
  }
}

// ── Navigation in any widget ──────────────────────────────────────────────
class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Center(
            child: Column(
              children: [
                FilledButton(
                  onPressed: () => context.go('/profile'), // ← GoRouter navigation
                  child: const Text('Go to Profile'),
                ),
                const SizedBox(height: 12),
                OutlinedButton(
                  onPressed: () => context.push('/settings'), // ← push navigation
                  child: const Text('Open Settings'),
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

4. Named Routes — Navigate Without String Literals

Assigning a name to each route lets you navigate by name instead of path string. This eliminates typos, is refactor-safe (rename the path without touching call sites), and enables passing typed parameters:

final GoRouter _router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      name: 'home',          // ← assign a name
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/profile',
      name: 'profile',
      builder: (context, state) => const ProfileScreen(),
    ),
    GoRoute(
      path: '/product/:id',
      name: 'product',       // ← named route with path parameter
      builder: (context, state) {
        final id = state.pathParameters['id']!;
        return ProductScreen(productId: id);
      },
    ),
  ],
);

// ── Navigation with names ─────────────────────────────────────────────────

// By path string (works but fragile — typos are runtime errors)
context.go('/profile');
context.go('/product/42');

// By name (preferred — typos are compile errors with proper constants)
context.goNamed('profile');
context.goNamed('product', pathParameters: {'id': '42'});
context.pushNamed('settings');

// ── Define route name constants to get compile-time safety ─────────────────
class Routes {
  Routes._();
  static const home     = 'home';
  static const profile  = 'profile';
  static const product  = 'product';
  static const settings = 'settings';
}

// Usage — typos in Routes.xxx are caught at compile time:
context.goNamed(Routes.profile);
context.goNamed(Routes.product, pathParameters: {'id': productId});

5. go() vs push() vs pop() — The Complete Breakdown

This is the most misunderstood part of GoRouter. Getting it wrong means your back button vanishes or your navigation history behaves unexpectedly:

// ── go() — replaces the stack ─────────────────────────────────────────────
// Scenario: user taps "Home" in the bottom navigation bar

// Before: stack = [HomeScreen, SettingsScreen]
context.go('/home');
// After:  stack = [HomeScreen]   ← settings is gone, no back button

// go() is like typing a new URL in the browser — full navigation replace.
// User cannot go back to what they were on before.

// ─────────────────────────────────────────────────────────────────────────

// ── push() — adds to the stack ────────────────────────────────────────────
// Scenario: user taps a product in a list to see details

// Before: stack = [HomeScreen, ProductListScreen]
context.push('/product/42');
// After:  stack = [HomeScreen, ProductListScreen, ProductDetailScreen]
//                                                 ↑ back button shows here

// push() is like opening a new tab — user can go back.

// ─────────────────────────────────────────────────────────────────────────

// ── replace() — swaps current screen ─────────────────────────────────────
// Scenario: user completes login, navigate to home WITHOUT allowing back to login

// Before: stack = [SplashScreen, LoginScreen]
context.replace('/home');
// After:  stack = [SplashScreen, HomeScreen]
//                                ↑ LoginScreen is gone, back goes to Splash

// ─────────────────────────────────────────────────────────────────────────

// ── pop() with canPop() safety check ──────────────────────────────────────
void _handleBackButton(BuildContext context) {
  if (context.canPop()) {
    context.pop(); // ← safe: something is behind us
  } else {
    context.go('/home'); // ← nothing to pop: go to home instead
  }
}

// ─────────────────────────────────────────────────────────────────────────

// ── The rule of thumb ─────────────────────────────────────────────────────
// go()     → switching between main app sections (tabs, top-level screens)
// push()   → drilling into a detail (list → detail, settings → sub-setting)
// replace()→ after auth flows where back-to-login makes no sense

6. Passing Parameters: Path, Query, and Extra

GoRouter has three ways to pass data between routes. Each has different trade-offs — especially around deep linking:

Method 1: Path Parameters (embedded in the URL)

// ── Define the route with :paramName placeholders ─────────────────────────
GoRoute(
  path: '/product/:productId',
  name: 'product',
  builder: (context, state) {
    // pathParameters is always non-null when the path matched
    final productId = state.pathParameters['productId']!;
    return ProductScreen(productId: productId);
  },
),

// Multiple path params:
GoRoute(
  path: '/team/:teamId/member/:memberId',
  builder: (context, state) {
    final teamId   = state.pathParameters['teamId']!;
    final memberId = state.pathParameters['memberId']!;
    return MemberScreen(teamId: teamId, memberId: memberId);
  },
),

// ── Navigate with path params ─────────────────────────────────────────────
context.go('/product/42');
context.go('/team/flutter/member/alice');

// Named + typed:
context.goNamed('product', pathParameters: {'productId': '42'});
context.goNamed('member', pathParameters: {'teamId': 'flutter', 'memberId': 'alice'});

Method 2: Query Parameters (after the ? in the URL)

// ── No declaration needed in the path — just access state.uri ────────────
GoRoute(
  path: '/products',
  name: 'products',
  builder: (context, state) {
    // queryParameters are nullable — key may not be present
    final category = state.uri.queryParameters['category'];       // String?
    final sort     = state.uri.queryParameters['sort'] ?? 'asc';  // default
    final page     = int.tryParse(
      state.uri.queryParameters['page'] ?? '1',
    ) ?? 1;

    return ProductsScreen(category: category, sort: sort, page: page);
  },
),

// ── Navigate with query params ────────────────────────────────────────────
context.go('/products?category=shoes&sort=price&page=2');

// Named + typed:
context.goNamed('products', queryParameters: {
  'category': 'shoes',
  'sort':     'price',
  'page':     '2',
});

Method 3: extra (Dart objects — not URL-safe)

// ── Pass any Dart object via extra ────────────────────────────────────────
// Useful for passing objects you already have in memory — avoids a second API call

// Navigate
context.push('/product-detail', extra: product); // passes a Product object

// Receive
GoRoute(
  path: '/product-detail',
  builder: (context, state) {
    final product = state.extra as Product; // cast to your type
    return ProductDetailScreen(product: product);
  },
),

// ── CRITICAL WARNING: extra doesn't survive deep links ────────────────────
// If a user opens your app via a deep link like:
//   yourapp://product-detail
// state.extra will be NULL — the URL has no way to encode a Dart object.
//
// Rule: use extra ONLY for in-app navigation where you already have the object.
// For any screen that must support deep linking → use path or query params.

// ── Combining all three ────────────────────────────────────────────────────
context.go(
  '/products/42?referrer=home',  // path param + query param
  extra: {'scrollPosition': 120.0}, // extra for in-memory state
);

7. Nested (Sub) Routes

// Child routes are defined inside the parent's 'routes' list.
// Child paths are RELATIVE — no leading slash — they append to the parent path.

final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: '/products',                              // → /products
      name: 'products',
      builder: (context, state) => const ProductListScreen(),
      routes: [
        GoRoute(
          path: ':id',                                // → /products/:id
          name: 'product-detail',
          builder: (context, state) {
            final id = state.pathParameters['id']!;
            return ProductDetailScreen(productId: id);
          },
          routes: [
            GoRoute(
              path: 'reviews',                        // → /products/:id/reviews
              name: 'product-reviews',
              builder: (context, state) {
                final id = state.pathParameters['id']!;
                return ProductReviewsScreen(productId: id);
              },
            ),
          ],
        ),
      ],
    ),
  ],
);

// Navigate to nested routes:
context.go('/products');            // product list
context.go('/products/42');         // product 42 detail
context.go('/products/42/reviews'); // product 42 reviews

// ❌ Common mistake: child path starts with /
routes: [
  GoRoute(path: '/id', ...),  // ← throws RouteException
]

// ✅ Correct: no leading slash on child paths
routes: [
  GoRoute(path: ':id', ...),  // ← relative path, becomes /products/:id
]

8. Redirects and Auth Guards

Redirects are GoRouter’s most powerful feature for production apps. Instead of checking auth in every screen’s initState, you define one redirect function that runs before every navigation event:

Global redirect (app-wide auth guard)

final GoRouter _router = GoRouter(
  initialLocation: '/',
  redirect: (BuildContext context, GoRouterState state) {
    final isLoggedIn = AuthService.instance.isLoggedIn;
    final isOnLoginPage = state.matchedLocation == '/login';
    final isOnSplash    = state.matchedLocation == '/splash';

    // Not logged in and not already on login or splash:
    if (!isLoggedIn && !isOnLoginPage && !isOnSplash) {
      return '/login'; // ← redirect to login
    }

    // Already logged in but navigating to login (e.g., user typed the URL manually):
    if (isLoggedIn && isOnLoginPage) {
      return '/';      // ← redirect away from login
    }

    return null; // ← null means "proceed normally, no redirect"
  },
  routes: [
    GoRoute(path: '/splash',  builder: (_, __) => const SplashScreen()),
    GoRoute(path: '/login',   builder: (_, __) => const LoginScreen()),
    GoRoute(path: '/',        builder: (_, __) => const HomeScreen()),
    GoRoute(path: '/profile', builder: (_, __) => const ProfileScreen()),
    GoRoute(path: '/settings',builder: (_, __) => const SettingsScreen()),
  ],
);

Per-route redirect (role-based access)

GoRoute(
  path: '/admin',
  // This redirect only fires when navigating to /admin
  redirect: (context, state) {
    if (!AuthService.instance.isAdmin) {
      return '/home'; // non-admins are redirected to home
    }
    return null; // admins proceed normally
  },
  builder: (context, state) => const AdminDashboard(),
),

// GoRouter evaluates redirects in this order:
// 1. Global redirect (fires for every navigation)
// 2. Per-route redirect (fires only for this specific route)

Reactive redirect with refreshListenable (the right way to handle logout)

// Problem: the redirect callback only fires when navigation happens.
// If the user's session expires while they're on a screen — no navigation
// occurs, so redirect never re-evaluates, user stays on a protected screen.

// Solution: refreshListenable
// GoRouter re-runs the redirect whenever the listenable notifies.

class AuthNotifier extends ChangeNotifier {
  bool _isLoggedIn = false;
  bool get isLoggedIn => _isLoggedIn;

  void login() {
    _isLoggedIn = true;
    notifyListeners(); // ← triggers redirect re-evaluation
  }

  void logout() {
    _isLoggedIn = false;
    notifyListeners(); // ← triggers redirect re-evaluation → user sent to /login
  }
}

final authNotifier = AuthNotifier();

final GoRouter _router = GoRouter(
  refreshListenable: authNotifier, // ← watches this for changes
  redirect: (context, state) {
    if (!authNotifier.isLoggedIn && state.matchedLocation != '/login') {
      return '/login';
    }
    if (authNotifier.isLoggedIn && state.matchedLocation == '/login') {
      return '/';
    }
    return null;
  },
  routes: [...],
);

// Now when authNotifier.logout() is called anywhere in the app:
// → notifyListeners() fires
// → GoRouter re-evaluates the redirect
// → User is automatically sent to /login
// No manual context.go('/login') needed anywhere

9. Error Handling — Custom 404 Page

final GoRouter _router = GoRouter(
  // errorBuilder fires when a route path doesn't match any GoRoute
  // Critical for web apps where users can type arbitrary URLs
  errorBuilder: (context, state) {
    return Scaffold(
      appBar: AppBar(title: const Text('Page Not Found')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Icon(Icons.link_off, size: 72, color: Colors.grey),
            const SizedBox(height: 20),
            const Text(
              '404 — Page Not Found',
              style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 12),
            Text(
              'Could not find: ${state.uri}',  // shows what URL was attempted
              style: TextStyle(color: Colors.grey.shade600),
              textAlign: TextAlign.center,
            ),
            if (state.error != null) ...[
              const SizedBox(height: 8),
              Text(
                '${state.error}',
                style: const TextStyle(color: Colors.red, fontSize: 12),
                textAlign: TextAlign.center,
              ),
            ],
            const SizedBox(height: 28),
            FilledButton.icon(
              onPressed: () => context.go('/'),
              icon: const Icon(Icons.home),
              label: const Text('Go Home'),
            ),
          ],
        ),
      ),
    );
  },
  routes: [...],
);

10. StatefulShellRoute: Persistent Bottom Navigation Bar

StatefulShellRoute.indexedStack is how GoRouter handles a bottom navigation bar where each tab keeps its state (scroll position, sub-navigation stack) when you switch between them. Without it, switching tabs destroys and recreates the previous tab completely.

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

// ── Each branch needs its own GlobalKey — critical, never share ───────────
final _rootNavigatorKey    = GlobalKey<NavigatorState>();
final _homeNavigatorKey    = GlobalKey<NavigatorState>(debugLabel: 'home');
final _searchNavigatorKey  = GlobalKey<NavigatorState>(debugLabel: 'search');
final _profileNavigatorKey = GlobalKey<NavigatorState>(debugLabel: 'profile');

final GoRouter _router = GoRouter(
  navigatorKey: _rootNavigatorKey,
  initialLocation: '/home',
  routes: [
    StatefulShellRoute.indexedStack(
      // The builder wraps ALL tabs in a persistent scaffold
      builder: (context, state, navigationShell) {
        return ScaffoldWithNavBar(navigationShell: navigationShell);
      },
      branches: [
        // ── Branch 1: Home ─────────────────────────────────────────────
        StatefulShellBranch(
          navigatorKey: _homeNavigatorKey,
          routes: [
            GoRoute(
              path: '/home',
              name: 'home',
              builder: (context, state) => const HomeScreen(),
              routes: [
                GoRoute(
                  path: 'article/:id',       // → /home/article/:id
                  name: 'article',
                  builder: (context, state) {
                    final id = state.pathParameters['id']!;
                    return ArticleScreen(articleId: id);
                    // ↑ navigating here shows back button, tab bar stays visible
                  },
                ),
              ],
            ),
          ],
        ),

        // ── Branch 2: Search ────────────────────────────────────────────
        StatefulShellBranch(
          navigatorKey: _searchNavigatorKey,
          routes: [
            GoRoute(
              path: '/search',
              name: 'search',
              builder: (context, state) => const SearchScreen(),
            ),
          ],
        ),

        // ── Branch 3: Profile ───────────────────────────────────────────
        StatefulShellBranch(
          navigatorKey: _profileNavigatorKey,
          routes: [
            GoRoute(
              path: '/profile',
              name: 'profile',
              builder: (context, state) => const ProfileScreen(),
              routes: [
                GoRoute(
                  path: 'settings',          // → /profile/settings
                  name: 'profile-settings',
                  builder: (context, state) => const ProfileSettingsScreen(),
                ),
              ],
            ),
          ],
        ),
      ],
    ),
  ],
);

// ── The persistent shell scaffold ─────────────────────────────────────────
class ScaffoldWithNavBar extends StatelessWidget {
  const ScaffoldWithNavBar({required this.navigationShell, super.key});

  final StatefulNavigationShell navigationShell;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      // navigationShell IS the body — it renders the active branch
      body: navigationShell,
      bottomNavigationBar: NavigationBar(
        selectedIndex: navigationShell.currentIndex,
        onDestinationSelected: (index) {
          navigationShell.goBranch(
            index,
            // When tapping the currently active tab's icon:
            // initialLocation = true → pops back to the tab's root screen
            // initialLocation = false → stays on the current sub-screen
            initialLocation: index == navigationShell.currentIndex,
          );
        },
        destinations: const [
          NavigationDestination(
            icon: Icon(Icons.home_outlined),
            selectedIcon: Icon(Icons.home),
            label: 'Home',
          ),
          NavigationDestination(
            icon: Icon(Icons.search_outlined),
            selectedIcon: Icon(Icons.search),
            label: 'Search',
          ),
          NavigationDestination(
            icon: Icon(Icons.person_outline),
            selectedIcon: Icon(Icons.person),
            label: 'Profile',
          ),
        ],
      ),
    );
  }
}

11. Deep Linking Setup (Android and iOS)

GoRouter is URL-based by design — every route already has a path. To open those paths from outside the app (notifications, web links, emails), you need two things: platform-level config to intercept the URL, and GoRouter automatically maps it to the right screen.

Android (AndroidManifest.xml)

<!-- android/app/src/main/AndroidManifest.xml -->
<activity
  android:name=".MainActivity"
  android:exported="true"
  android:launchMode="singleTop">

  <!-- Required: tell Flutter that deep linking is enabled -->
  <meta-data
    android:name="flutter_deeplinking_enabled"
    android:value="true" />

  <!-- HTTPS deep links (Android App Links — verified, no browser prompt) -->
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="https"
      android:host="yourapp.com" />
    <!-- Opens https://yourapp.com/products/42 → GoRoute path: /products/:id -->
  </intent-filter>

  <!-- Custom URL scheme (simpler — no domain verification needed) -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="myapp"
      android:host="open" />
    <!-- Opens myapp://open/products/42 → GoRoute path: /products/:id -->
  </intent-filter>

</activity>

iOS (Info.plist)

<!-- ios/Runner/Info.plist -->

<!-- Required: enable Flutter deep linking -->
<key>FlutterDeepLinkingEnabled</key>
<true/>

<!-- Custom URL scheme (myapp://open/products/42) -->
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

<!-- For HTTPS Universal Links (yourapp.com/products/42):
     Also add Associated Domains capability in Xcode:
     applinks:yourapp.com -->

After platform setup, GoRouter handles the rest automatically. An incoming URL like https://yourapp.com/products/42 is parsed, matched against your route tree, and the correct screen opens with productId = '42' — zero extra Flutter code needed.

12. Common Mistakes

13. Interview Q&A

14. Related Posts