Configuration topic

Create a GoRouter configuration by calling the GoRouter constructor and providing list of GoRoute objects:

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

GoRoute

To configure a GoRoute, a path template and builder must be provided. Specify a path template to handle by providing a path parameter, and a builder by providing either the builder or pageBuilder parameter:

GoRoute(
  path: '/users/:userId',
  builder: (context, state) => const UserScreen(),
),

To navigate to this route, use go(). To learn more about how navigation works, visit the Navigation topic.

Parameters

To specify a path parameter, prefix a path segment with a : character, followed by a unique name, for example, :userId. You can access the value of the parameter by accessing it through the GoRouterState object provided to the builder callback:

GoRoute(
  path: '/users/:userId',
  builder: (context, state) => const UserScreen(id: state.pathParameters['userId']),
),

Similarly, to access a query string parameter (the part of URL after the ?), use GoRouterState. For example, a URL path such as /users?filter=admins can read the filter parameter:

GoRoute(
  path: '/users',
  builder: (context, state) => const UsersScreen(filter: state.uri.queryParameters['filter']),
),

Child routes

A matched route can result in more than one screen being displayed on a Navigator. This is equivalent to calling push(), where a new screen is displayed above the previous screen with a transition animation, and with an in-app back button in the AppBar widget, if it is used.

To display a screen on top of another, add a child route by adding it to the parent route's routes list:

GoRoute(
  path: '/',
  builder: (context, state) {
    return HomeScreen();
  },
  routes: [
    GoRoute(
      path: 'details',
      builder: (context, state) {
        return DetailsScreen();
      },
    ),
  ],
)

Nested navigation

Some apps display destinations in a subsection of the screen, for example, an app using a BottomNavigationBar that stays on-screen when navigating between destinations.

To add an additional Navigator, use ShellRoute and provide a builder that returns a widget:

ShellRoute(
  builder:
      (BuildContext context, GoRouterState state, Widget child) {
    return Scaffold(
      body: child,
      /* ... */
      bottomNavigationBar: BottomNavigationBar(
      /* ... */
      ),
    );
  },
  routes: <RouteBase>[
    GoRoute(
      path: 'details',
      builder: (BuildContext context, GoRouterState state) {
        return const DetailsScreen();
      },
    ),
  ],
),

The child widget is a Navigator configured to display the matching sub-routes.

For more details, see the ShellRoute API documentation. For a complete example, see the ShellRoute sample in the example/ directory.

Initial location

The initial location is shown when the app first opens and there is no deep link provided by the platform. To specify the initial location, provide the initialLocation parameter to the GoRouter constructor:

GoRouter(
  initialLocation: '/details',
  /* ... */
);

Logging

To enable log output, enable the debugLogDiagnostics parameter:

final _router = GoRouter(
  routes: [/* ... */],
  debugLogDiagnostics: true,
);

Classes

GoRoute

A route that is displayed visually above the matching parent route using the Navigator.

GoRouter

The route configuration for the app.

ShellRoute

A route that displays a UI shell around the matching child route.