How to Use go_router in Flutter for Simple Navigation

Use go_router in Flutter by defining a GoRouter object with routes and passing it to MaterialApp.router. This package simplifies navigation and supports deep linking with declarative routes.

Syntax

The main parts of using go_router are:

• GoRouter: The router object that holds route definitions.
• GoRoute: Defines a single route with a path and a builder function.
• MaterialApp.router: Connects the router to your app.

Routes are declared as a list of GoRoute objects with paths and widgets to show.

dart

final GoRouter router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => HomePage(),
    ),
    GoRoute(
      path: '/details',
      builder: (context, state) => DetailsPage(),
    ),
  ],
);

MaterialApp.router(
  routerConfig: router,
);

Example

This example shows a simple app with two pages: Home and Details. You can navigate between them using context.go().

dart

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

void main() {
  final router = GoRouter(
    routes: [
      GoRoute(
        path: '/',
        builder: (context, state) => HomePage(),
      ),
      GoRoute(
        path: '/details',
        builder: (context, state) => DetailsPage(),
      ),
    ],
  );

  runApp(MyApp(router: router));
}

class MyApp extends StatelessWidget {
  final GoRouter router;
  const MyApp({required this.router, super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: router,
      title: 'GoRouter Demo',
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.go('/details'),
          child: const Text('Go to Details'),
        ),
      ),
    );
  }
}

class DetailsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Details')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.go('/'),
          child: const Text('Back to Home'),
        ),
      ),
    );
  }
}

Output

App starts on Home page with a button labeled 'Go to Details'. Tapping it navigates to Details page with a button labeled 'Back to Home'. Tapping that returns to Home page.

Common Pitfalls

Common mistakes when using go_router include:

• Not passing routerConfig to MaterialApp.router, which breaks navigation.
• Using MaterialApp instead of MaterialApp.router.
• Forgetting to define all routes needed in the GoRouter routes list.
• Using Navigator.push instead of context.go() or context.push() for navigation.

Example of wrong and right usage:

dart

/* Wrong: Using MaterialApp without routerConfig */
MaterialApp(
  home: HomePage(),
);

/* Right: Using MaterialApp.router with routerConfig */
MaterialApp.router(
  routerConfig: router,
);

Quick Reference

Here is a quick summary of key go_router usage:

Concept	Description
GoRouter	Main router object holding all routes
GoRoute	Defines a route with path and widget builder
MaterialApp.router	Connects router to the app
context.go(path)	Navigate to a route, replacing current
context.push(path)	Navigate to a route, stacking on top
routerConfig	Property to pass GoRouter to MaterialApp.router

Key Takeaways

Always use MaterialApp.router with routerConfig set to your GoRouter instance.

Define all your app routes inside GoRouter using GoRoute objects.

Use context.go() or context.push() for navigation instead of Navigator.push.

Make sure your route paths match exactly what you use in navigation calls.

go_router supports deep linking and declarative routing for simpler navigation.