Declarative Navigation in Flutter with go_router

The declarative navigation is to describe which route should be active.

So far we’ve used Imperative Navigation (Navigator.push). That is, we manually “give orders”: “Put this screen on top”, “Remove this screen”.

This works wonderfully for simple apps. But what if you’re building a Web version of your App? If the user types myapp.com/products/15 in the browser’s address bar, with Navigator.push you don’t have an easy way to know you need to go directly to that screen.

To solve that problem we use Declarative Navigation. In Flutter, one of the most common tools for this is GoRouter.

Named Routes

Flutter includes a native named routes system, although its documentation recommends other solutions for most applications with advanced navigation requirements.

It consists of defining a “map” of routes in the MaterialApp:

// Valid approach, though with limitations
MaterialApp(
  routes: {
    '/': (context) => HomeScreen(),
    '/details': (context) => DetailScreen(),
  },
);

And then navigate using names:

Navigator.pushNamed(context, '/details');

The go_router Package

To solve these scenarios, the official Flutter ecosystem offers the go_router package.

GoRouter uses URL-based navigation, even on mobile.

• If you want to go to the home -> /
• If you want to go to settings -> /settings
• If you want to view user 42 -> /users/42

How does it work conceptually?

Instead of manually stacking screens, you define a route tree. When the URL changes (either because you tapped a button or typed in the browser), GoRouter decides which screens should be on the stack to match that URL.

It is Declarative: “I want to be in this state”, instead of “Do this, then this”.

A Look at the Configuration

To use it, you need to add go_router to your pubspec.yaml.

import 'package:go_router/go_router.dart';

// 1. Define the configuration
final _router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => HomeScreen(),
      routes: [
        // Nested route: /details
        GoRoute(
          path: 'details',
          builder: (context, state) => DetailsScreen(),
        ),
      ],
    ),
  ],
);

void main() {
  runApp(MaterialApp.router(
    // 2. Connect GoRouter to the App
    routerConfig: _router,
  ));
}

Navigating with GoRouter

The great thing is that moving around and passing parameters is very clean:

// Go to a page (Replaces the stack if necessary)
context.go('/details');

// Pass parameters in the URL (e.g., /users/123)
context.go('/users/$userId');

Features of go_router

Here are some of the features that make it useful for applications with complex navigation:

1. Deep Linking: If someone sends you a WhatsApp link myapp://offer/50, GoRouter opens your App and navigates exactly to that screen automatically.
2. Redirects (Guards): You can configure security logic. “If the user tries to go to /profile but isn’t logged in, automatically redirect them to /login”.
3. Web Support: The browser’s address bar changes as you navigate through the App.
4. Route Parameters: Extracting the id from /product/:id is trivial (state.pathParameters['id']).