StatefulShellRoute class

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:

• StatefulShellRoute.indexedStack which provides a default StatefulShellRoute implementation suitable for most use cases.
• Stateful Nested Navigation example for a complete runnable example using StatefulShellRoute.
• Custom StatefulShellRoute example which demonstrates how to customize the container for the branch Navigators and how to implement animated transitions when switching branches.