go_router 4.2.4

A declarative router for Flutter based on Navigation 2 supporting deep linking, data-driven routes and more

go_router, A Declarative Routing Package for Flutter

This package builds on top of the Flutter framework's Router API and provides convenient url-based APIs to navigate between different screens. You can define your own url patterns, navigating to different url, handle deep and dynamic linking, and a number of other navigation-related scenarios.

Getting Started

Follow the package install instructions, and you can start using go_router in your code:

class App extends StatelessWidget {
  App({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) => MaterialApp.router(
        routeInformationProvider: _router.routeInformationProvider,
        routeInformationParser: _router.routeInformationParser,
        routerDelegate: _router.routerDelegate,
        title: 'GoRouter Example',
      );

  final GoRouter _router = GoRouter(
    routes: <GoRoute>[
      GoRoute(
        path: '/',
        builder: (BuildContext context, GoRouterState state) => const Page1Screen(),
      ),
      GoRoute(
        path: '/page2',
        builder: (BuildContext context, GoRouterState state) => const Page2Screen(),
      ),
    ],
  );
}

Define Routes

go_router is governed by a set of routes which are specify as part of the GoRouter constructor:

GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const Page1Screen(),
    ),
    GoRoute(
      path: '/page2',
      builder: (context, state) => const Page2Screen(),
    ),
  ],
);

It defined two routes, / and /page2. Each route path will be matched against the location to which the user is navigating. The path will be matched in a case-insensitive way, although the case for parameters will be preserved. If there are multiple route matches, the first match in the list takes priority over the others.

In addition to the path, each route will typically have a builder function that is responsible for building the Widget that is to take up the entire screen of the app. The default transition is used between pages depending on the app at the top of its widget tree, e.g. the use of MaterialApp will cause go_router to use the MaterialPage transitions. Consider using pageBuilder for custom Page class.

Initalization

Once a GoRouter object is created, it can be used to initialize MaterialApp or CupertinoApp.

final GoRouter _router = GoRouter(..);

MaterialApp.router(
  routeInformationProvider: _router.routeInformationProvider,
  routeInformationParser: _router.routeInformationParser,
  routerDelegate: _router.routerDelegate,
);

Error handling

By default, go_router comes with default error screens for both MaterialApp and CupertinoApp as well as a default error screen in the case that none is used. Once can also replace the default error screen by using the errorBuilder:

GoRouter(
  ...
  errorBuilder: (context, state) => ErrorScreen(state.error),
);

Navigation

To navigate between routes, use the GoRouter.go method:

onTap: () => GoRouter.of(context).go('/page2')

go_router also provides a simplified means of navigation using Dart extension methods:

onTap: () => context.go('/page2')

Still not sure how to proceed? See examples for complete runnable examples or visit API documentation

Migration guides

Migrating to 2.0
Migrating to 2.5
Migrating to 3.0
Migrating to 4.0

Changelog

See the Changelog for a list of new features and breaking changes.