StatefulShellRoute class Configuration

A route that displays a UI shell with separate Navigators for its sub-routes.

Similar to ShellRoute, this route class places its sub-route on a different Navigator than the root Navigator. However, this route class differs in that it creates separate Navigators for each of its nested branches (i.e. parallel navigation trees), making it possible to build an app with stateful nested navigation. This is convenient when for instance implementing a UI with a BottomNavigationBar, with a persistent navigation state for each tab.

A StatefulShellRoute is created by specifying a List of StatefulShellBranch items, each representing a separate stateful branch in the route tree. StatefulShellBranch provides the root routes and the Navigator key (GlobalKey) for the branch, as well as an optional initial location.

Like ShellRoute, either a builder or a pageBuilder must be provided when creating a StatefulShellRoute. However, these builders differ slightly in that they accept a StatefulNavigationShell parameter instead of a child Widget. The StatefulNavigationShell can be used to access information about the state of the route, as well as to switch the active branch (i.e. restoring the navigation stack of another branch). The latter is accomplished by using the method StatefulNavigationShell.goBranch, for example:

void _onItemTapped(int index) {
  navigationShell.goBranch(index: index);
}

The StatefulNavigationShell is also responsible for managing and maintaining the state of the branch Navigators. Typically, a shell is built around this Widget, for example by using it as the body of Scaffold with a BottomNavigationBar.

When creating a StatefulShellRoute, a navigatorContainerBuilder function must be provided. This function is responsible for building the actual container for the Widgets representing the branch Navigators. Typically, the Widget returned by this function handles the layout (including Offstage handling etc) of the branch Navigators and any animations needed when switching active branch.

For a default implementation of navigatorContainerBuilder that is appropriate for most use cases, consider using the constructor StatefulShellRoute.indexedStack.

With StatefulShellRoute (and any route below it), animated transitions between routes in the same navigation stack works the same way as with other route classes, and can be customized using pageBuilder. However, since StatefulShellRoute maintains a set of parallel navigation stacks, any transitions when switching between branches is the responsibility of the branch Navigator container (i.e. navigatorContainerBuilder). The default IndexedStack implementation (StatefulShellRoute.indexedStack) does not use animated transitions, but an example is provided on how to accomplish this (see link to custom StatefulShellRoute example below).

See also:

Inheritance

Constructors

StatefulShellRoute({required List<StatefulShellBranch> branches, GoRouterRedirect? redirect, StatefulShellRouteBuilder? builder, StatefulShellRoutePageBuilder? pageBuilder, required ShellNavigationContainerBuilder navigatorContainerBuilder, GlobalKey<NavigatorState>? parentNavigatorKey, String? restorationScopeId, GlobalKey<StatefulNavigationShellState>? key})
Constructs a StatefulShellRoute from a list of StatefulShellBranches, each representing a separate nested navigation tree (branch).
StatefulShellRoute.indexedStack({required List<StatefulShellBranch> branches, GoRouterRedirect? redirect, StatefulShellRouteBuilder? builder, GlobalKey<NavigatorState>? parentNavigatorKey, StatefulShellRoutePageBuilder? pageBuilder, String? restorationScopeId, GlobalKey<StatefulNavigationShellState>? key})
Constructs a StatefulShellRoute that uses an IndexedStack for its nested Navigators.

Properties

branches → List<StatefulShellBranch>
Representations of the different stateful route branches that this shell route will manage.
final
builder → StatefulShellRouteBuilder?
The widget builder for a stateful shell route.
final
hashCode → int
The hash code for this object.
no setterinherited
The builder for the branch Navigator container.
final
pageBuilder → StatefulShellRoutePageBuilder?
The page builder for a stateful shell route.
final
parentNavigatorKey → GlobalKey<NavigatorState>?
An optional key specifying which Navigator to display this route's screen onto.
finalinherited
redirect → GoRouterRedirect?
An optional redirect function for this route.
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