
# 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

```dart
@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/1` opens 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 a `CupertinoApp` in one of type `cupertino` (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](index.md#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.

```dart
@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](scopes.md)).

## See also

- [Screens and routes](screens.md)
- [Routes in Dart configuration](dart-configuration.md)
- [Transitions](transitions.md)
