Ever opened a Flutter project and felt an immediate sense of dread?
Screens imported everywhere.Navigator.pushcalls scattered across widgets.
Routes defined in three different files—none of them agreeing with each other.
At first, it doesn’t feel like a problem. Navigation works. But as the app grows, the codebase starts to push back. Adding a new screen means touching half a dozen files. Deep links break silently. Authentication logic sneaks into UI code where it doesn’t belong. What should be a simple act—moving from one screen to another—turns into a maintenance burden.
This is not a Flutter problem. It’s a routing problem.
In this tutorial, you’ll learn how to bring structure back to navigation in Flutter using GoRouter—not as a patch, but as a clean, declarative system designed for apps that are meant to scale.
What is GoRouter?
GoRouter is Flutter’s declarative routing solution designed to solve the structural problems that emerge as applications grow. Instead of scattering navigation logic across widgets, GoRouter centralizes routing into a single, predictable configuration—turning navigation from an ad-hoc implementation detail into a first-class part of your app’s architecture.
At its core, GoRouter shifts Flutter navigation from an imperative model (“push this screen now”) to a declarative one (“this URL represents this screen”). Your UI becomes a function of the current route, not the other way around. This approach aligns naturally with how modern applications are built—especially when targeting mobile and web from the same codebase.
With GoRouter, routes are defined as a tree, mirroring how users actually move through an app. Each route has a path, optional parameters, and a screen it resolves to. Navigation becomes explicit, readable, and easy to reason about. More importantly, it becomes predictable.
GoRouter is officially maintained by the Flutter team and is built on top of Navigator 2.0—without exposing you to its complexity. Features like deep linking, browser URL synchronization, nested navigation, and redirection logic (such as authentication guards) are supported out of the box, rather than being bolted on later.
If your app is more than a few screens—or you expect it to be—GoRouter is not an optional enhancement. It is the foundation that keeps navigation clean, testable, and maintainable as your Flutter application evolves.
Add the Dependency
From the root of your Flutter project, run:
flutter pub add go_routerOnce the command completes, verify the installation by importing GoRouter in any Dart file:
import 'package:go_router/go_router.dart';Understanding Core Concepts
Before writing any routing code, it is important to understand how GoRouter thinks about navigation. Most confusion around routing does not come from syntax—it comes from carrying the old Navigator.push mindset into a declarative system.
GoRouter introduces a small set of concepts. Once these are clear, everything else becomes straightforward.
1. Routes Are the Source of Truth
In GoRouter, routes define the app, not the widgets.
Instead of saying “from this screen, go to that screen”, you declare:
“When the app is at this path, show this screen.”
final router = GoRouter(
routes: [
GoRoute(
path: '/',
builder: (context, state) => const HomePage(),
),
GoRoute(
path: '/login',
builder: (context, state) => const LoginPage(),
),
],
);
There is no navigation logic inside HomePage or LoginPage. Your UI becomes a reflection of the current route state. This makes navigation predictable and easy to reason about.
2. Paths (URLs)
Every route is identified by a path, similar to a web URL:
'/' // Home
'/login' // Login
'/profile/42' // Profile with id = 42Example route configuration:
GoRoute(
path: '/profile/:id',
builder: (context, state) {
final userId = state.pathParameters['id']!;
return ProfilePage(userId: userId);
},
);Even in a mobile-only app, GoRouter treats navigation as URL-based. This is what enables:
Deep linking
Browser back/forward support
Direct navigation to specific screens
You are no longer navigating between widgets—you are navigating between paths.
3. GoRouter: The Router Configuration
GoRouter is the central configuration object. It:
Holds all routes
Handles navigation state
Resolves paths to screens
Applies redirects (auth, onboarding, etc.)
final router = GoRouter(
initialLocation: '/',
routes: [...],
);You typically create one GoRouter instance and pass it to your app:
MaterialApp.router(
routerConfig: router,
);Think of it as the navigation brain of your app. There should usually be one GoRouter instance for the entire application.
4. GoRoute: A Single Route Definition
Each screen is represented by a GoRoute.
A GoRoute defines:
The path (
/profile/:id)How to build the screen
Optional child routes
GoRoute(
path: '/settings',
builder: (context, state) => const SettingsPage(),
);Routes can be nested, forming a tree:
GoRoute(
path: '/dashboard',
builder: (context, state) => const DashboardPage(),
routes: [
GoRoute(
path: 'profile',
builder: (context, state) => const ProfilePage(),
),
],
);This results in:
/dashboard
/dashboard/profileThe route tree mirrors your app’s structure.
5. Navigation Methods: go vs push
GoRouter provides two primary navigation APIs:
context.go('/path')
Replaces the current route. Resets the navigation history.
Use this when changing app state (login, logout, tab switch).context.push('/path')
Pushes a new route onto the stack.
Use this for drill-down navigation (details screens).
Choosing the correct method is critical for maintaining a clean back stack.
6. Parameters: Dynamic Routes
Path Parameters (Required)
GoRoute(
path: '/user/:id',
builder: (context, state) {
final id = state.pathParameters['id']!;
return UserPage(userId: id);
},
);
Navigation:
context.push('/user/10');
Path parameters are: Required, Positional, Part of the URL structure
Query Parameters (Optional)
GoRoute(
path: '/search',
builder: (context, state) {
final query = state.uri.queryParameters['q'];
return SearchPage(query: query);
},
);
Navigation:
context.push('/search?q=flutter');
Query parameters are: Optional, Flexible, Ideal for filters and search
7. Redirects: Navigation with Rules
Redirects allow you to control access before a screen builds.
Example: Authentication guard.
final router = GoRouter(
redirect: (context, state) {
final isLoggedIn = authService.isLoggedIn;
if (!isLoggedIn && state.matchedLocation != '/login') {
return '/login';
}
return null;
},
routes: [...],
);
This ensures: Unauthenticated users cannot access protected routes, logic stays out of UI code
Redirects are ideal for: Authentication, Onboarding flows, Feature flags etc.