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'),
],
),
);
}
/catalog/books/1opens in the Catalog tab, over/catalog; back returns to the catalog.shell.select(1)switches to a branch as it was left.- A screen outside every branch (
/checkout) opens over the shell. - The heroes of a branch fly as the app's design has them: along Material's arc in an app of type
material, as in aCupertinoAppin one of typecupertino(the design starter gives the hero controller), straight in an app without a design library, as those of the root navigator.
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).