ShellRoute class Configuration

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

When a ShellRoute is added to the list of routes on GoRouter or GoRoute, a new Navigator is used to display any matching sub-routes instead of placing them on the root Navigator.

To display a child route on a different Navigator, provide it with a parentNavigatorKey that matches the key provided to either the GoRouter or ShellRoute constructor. In this example, the _rootNavigator key is passed to the /b/details route so that it displays on the root Navigator instead of the ShellRoute's Navigator:

final GlobalKey<NavigatorState> _rootNavigatorKey =
    GlobalKey<NavigatorState>();

  final GoRouter _router = GoRouter(
    navigatorKey: _rootNavigatorKey,
    initialLocation: '/a',
    routes: [
      ShellRoute(
        navigatorKey: _shellNavigatorKey,
        builder: (context, state, child) {
          return ScaffoldWithNavBar(child: child);
        },
        routes: [
          // This screen is displayed on the ShellRoute's Navigator.
          GoRoute(
            path: '/a',
            builder: (context, state) {
              return const ScreenA();
            },
            routes: <RouteBase>[
              // This screen is displayed on the ShellRoute's Navigator.
              GoRoute(
                path: 'details',
                builder: (BuildContext context, GoRouterState state) {
                  return const DetailsScreen(label: 'A');
                },
              ),
            ],
          ),
          // Displayed ShellRoute's Navigator.
          GoRoute(
            path: '/b',
            builder: (BuildContext context, GoRouterState state) {
              return const ScreenB();
            },
            routes: <RouteBase>[
              // Displayed on the root Navigator by specifying the
              // [parentNavigatorKey].
              GoRoute(
                path: 'details',
                parentNavigatorKey: _rootNavigatorKey,
                builder: (BuildContext context, GoRouterState state) {
                  return const DetailsScreen(label: 'B');
                },
              ),
            ],
          ),
        ],
      ),
    ],
  );

The widget built by the matching sub-route becomes the child parameter of the builder.

For example:

ShellRoute(
  builder: (BuildContext context, GoRouterState state, Widget child) {
    return Scaffold(
      appBar: AppBar(
        title: Text('App Shell')
      ),
      body: Center(
        child: child,
      ),
    );
  },
  routes: [
    GoRoute(
      path: 'a'
      builder: (BuildContext context, GoRouterState state) {
        return Text('Child Route "/a"');
      }
    ),
  ],
),
Inheritance

Constructors

ShellRoute({ShellRouteBuilder? builder, ShellRoutePageBuilder? pageBuilder, List<NavigatorObserver>? observers, required List<RouteBase> routes, GlobalKey<NavigatorState>? parentNavigatorKey, GlobalKey<NavigatorState>? navigatorKey, String? restorationScopeId})
Constructs a ShellRoute.

Properties

builder → ShellRouteBuilder?
The widget builder for a shell route.
final
hashCode → int
The hash code for this object.
no setterinherited
The GlobalKey to be used by the Navigator built for this route. All ShellRoutes build a Navigator by default. Child GoRoutes are placed onto this Navigator instead of the root Navigator.
final
observers → List<NavigatorObserver>?
The observers for a shell route.
final
pageBuilder → ShellRoutePageBuilder?
The page builder for a shell route.
final
parentNavigatorKey → GlobalKey<NavigatorState>?
An optional key specifying which Navigator to display this route's screen onto.
finalinherited
restorationScopeId → String?
Restoration ID to save and restore the state of the navigator, including its history.
final
routes → List<RouteBase>
The list of child routes associated with this route.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

buildPage(BuildContext context, GoRouterState state, ShellRouteContext shellRouteContext) → Page?
Attempts to build the Page representing this shell route.
override
buildWidget(BuildContext context, GoRouterState state, ShellRouteContext shellRouteContext) → Widget?
Attempts to build the Widget representing this shell route.
override
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
override
Returns the key for the Navigator that is to be used for the specified immediate sub-route of this shell route.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringShort() → String
A brief description of this object, usually just the runtimeType and the hashCode.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited