Shells and tabs

A shell is the part of the app that stays while the screens of its branches change: tabs at the bottom, a side menu, a header. Each branch keeps its own stack, and a screen whose path starts with a branch opens in it, with the screens of its path below.

Why

Tabs with their own history are the hardest part of navigation to write by hand: each tab needs its own Navigator, the back button must close the right screen, and a deep link into a tab must build the stack under it. A shell declares the branches by their paths, and the router does the rest.

Example

@RouteShell(branches: ['/catalog', '/profile'])
class MainTabs extends StatelessWidget {
  const MainTabs(this.shell, {super.key});

  final ShellState shell;

  @override
  Widget build(BuildContext context) => Scaffold(
    body: shell.child,
    bottomNavigationBar: NavigationBar(
      selectedIndex: shell.index,
      onDestinationSelected: shell.select,
      destinations: const [
        NavigationDestination(icon: Icon(Icons.book), label: 'Catalog'),
        NavigationDestination(icon: Icon(Icons.person), label: 'Profile'),
      ],
    ),
  );
}

Scaffold and NavigationBar are Material widgets: an app that uses them is of type material, with spring_boot_starter_flutter_material and material_ui in its dependencies (see Setup).

ShellState

Member Meaning
child The screens of the current branch; put it where the content goes. The other branches stay built (offstage) once visited, so each keeps its stack and state
index The index of the current branch in branches
branches The paths that start the branches
branch The path of the current branch
select(index) Switches to a branch as it was left, or to its first screen when it was never visited; selecting the current branch again goes back to its first screen

A screen in another branch

A screen can live in a branch its path is not under, so addresses stay flat: @ScreenRoute('/motion', branch: '/more') opens in the /more tab, over the tab's first screen (/more), and back returns to it.

@RouteShell(branches: ['/catalog', '/more'])
class MainTabs extends StatelessWidget { ... }

@ScreenRoute('/motion', branch: '/more')
class MotionSettingsPage extends StatelessWidget { ... }

In Dart configuration, a screen declared in a branch but outside its path does the same, or pass branch: '/more' to screen(...). A branch no shell has stops the start.

Beans per branch

A bean with @Scope(NavigationScopes.branch) lives while its branch lives, until the shell closes (see Beans per screen or branch).

See also