fespalier-layouts
Layouts and shells in fespalier — layout.dart (a ShellRoute around a folder and everything below it), (group) layouts, tab layouts on a StatefulNavigationShell with tabs, tabOptions and a custom conta
SKILL.mdskills/fespalier-layouts/SKILL.md
GitHubfespalier-layouts
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
layout.dart
A layout.dart wraps its folder and everything below it: it becomes a go_router
ShellRoute and mounts the pages as child.
// lib/app/layout.dart
import 'package:flutter/material.dart';
class AppLayout extends StatelessWidget {
const AppLayout({super.key, required this.child});
final Widget child;
@override
Widget build(BuildContext context) => Scaffold(body: SafeArea(child: child));
}
- It asks for
Widget child(a shell), or for aStatefulNavigationShell(navigationShellorshell: a tab layout). Both is an error. It may also ask for the segments at or above its folder, query parameters, the section data it wraps or sits inside (fespalier-data), and a nullableextra. A view function form exists too (Widget layout({required Widget child})). - A
(group)folder's layout applies only to the routes inside it, without touching their URLs:(shop)/cartand(account)/profilecan have different shells and still be/cartand/profile. Layouts nest, outermost first;RouteInfo.layoutslists them for a route (''is the app folder's own). not_found.dartrenders without any layout, and so does every route outside the layout's folder: they bring their ownScaffold.- A page-less folder with a
layout.dartand adata.dartis a section: the layout waits for the data (fespalier-data). - A layout is never deferred (since 0.7.0,
const deferred = true;in aroute.dartdeferspage.dartonly): it wraps aNavigator(aStatefulNavigationShellfor tabs), and a placeholder in its place would unmount them and their state. A tab layout's own page is deferred like any page, inside its branch (seeconst deferredin theroute.dartreference offespalier-routing). - A group's routes stay together in one
ShellRoute, so a group holding a dynamic route cannot be sorted around a dynamic sibling outside it: that is the usual "unreachable" error (fespalier-routing).
The ListTile ink assertion
Pages render below their layout's Scaffold, so during page transitions the
layout's Scaffold is not their nearest Material: a ListTile (or InkWell)
trips ListTile background color or ink splashes may be invisible ... wrapped in a ColoredBox. Give the page a surface of its own:
Material(type: MaterialType.transparency, child: ListView(children: [...]))
This is a documented gotcha of the project (docs/troubleshooting.md, "Things to know"); the
wrapper is what examples/shop's products/page.dart uses.
Tabs
A tab layout keeps each tab's own navigation stack and state. tabs orders
them, tabOptions sets preload and initialLocation per tab, and an exported
container function arranges the tabs' navigators (cross-fade, slide). Nested tab
layouts work. The rules go_router imposes (a tab's first route cannot have a
:segment, a root-navigator route cannot be a direct child of the shell) and every
error message are in references/tab-layouts.md.
const tabs = ['.', 'search', 'profile']; // '.' is the layout folder's own page.dart
const tabOptions = {'search': TabOptions(preload: true)};
onDestinationSelected: (i) => navigationShell.goBranch(
i,
initialLocation: i == navigationShell.currentIndex, // tapping the current tab pops to its root
),
Transitions, dialogs, restoration
transition.dart is Page<void> transition(LocalKey key, Widget child) (plus
optional GoRouterState state and bool shell); it covers its folder and below,
nearest wins, layout shells included since 0.3.0 (the shell's key is
ValueKey<String>('layout:<folder>/'), so only entering or leaving the shell
animates it). Transitions has fade, slide, none, material, cupertino,
sharedAxis, fadeThrough (since 0.19.0), dialog, sheet and fullscreenDialog. A dialog or sheet route must sit below
a page or it opens over an empty screen. Restoration needs
restorationScopeId on both MaterialApp and AppRoutes.router(...); a Page you
build yourself must pass restorationId: Transitions.restorationIdOf(key) (since 0.19.0). Since 0.8.1 a shared element is
Route(...).hero('name', child: ...) on each side (a RouteHero, which stays out of
flights in a hidden tab), and heroes: const Heroes(onBackGesture: true) on a Transitions.*
call sets how they fly; nothing flies into a dialog or sheet. Transitions.sharedAxis and Transitions.fadeThrough (since 0.19.0) are Material 3's motion over widgets alone, with a fill: or a MotionFill behind the pages. Since 0.19.0 every page and RouteHero honours the system's reduced motion by default (slide cross-fades, dialog and sheet open unanimated, heroes stop flying; custom's builder is yours to guard; no opt-out). A hero that holds a network image uses
route.imageHero(...) (since 0.9.0, fespalier_image: fespalier-images). All in
references/transitions-and-restoration.md.
Menus and breadcrumbs (nav.dart, since 0.8.1)
A nav.dart (const nav = Nav(label: 'Products', order: 1); and an optional
String label(BuildContext context, {...segments})) in a folder makes it a menu entry, and fsp gen
writes AppMenu in app.g.dart: AppMenu.watch(ref, under: '(tabs)') for drawers and tab bars
(each item has tab), AppMenu.breadcrumbs(ref) for the path to the page. Entries follow the guards
that would run for them: a sync answer is in the first frame, a Future shows the entry pending, a
Ref guard is followed. Call them in a layout or a page, never above the router. Rules, guards, traps
and the app-without-nav.dart guarantee are in
references/menus-and-breadcrumbs.md.
Scroll restoration (since 0.8.1): scroll_restoration: true in the pubspec's fespalier: section
wraps each page in RouteScrollMemory; the browser's back and forward then give a scrollable its
offset back, only if it has a PageStorageKey, and a go starts at the top. Same page.
Adaptive (fespalier_adaptive, since 0.9.0)
The core has no adaptive API; the package fespalier_adaptive (a repository dependency at fespalier's tag,
no third-party dependency, generated code unchanged) draws AppMenu.watch(ref, under: '(tabs)') as a
NavigationBar under 600 logical pixels, a NavigationRail from 600 and a permanent NavigationDrawer from
1200, around the same body, so a tab keeps its state when the window is resized:
AdaptiveNavScaffold(
shell: navigationShell, // or child: child, for a plain layout
menu: (ref) => AppMenu.watch(ref, under: '(tabs)'), // under: gives each entry its tab
breakpoints: const NavBreakpoints(rail: 840), // optional; null means never
)
- A phone's bar is hidden on a page no menu entry covers: a
NavigationBarcannot show "nothing selected". A debug build saysfespalier_adaptive: no menu entry is the current tab (3) of the tab layout, so the navigation bar is hidden. ...once; give the tab's folder anav.dart, or render the menu withAdaptiveNavBuilder. A rail and a drawer show none selected. - A tab folder with no
page.dart(a heading) is a bar destination because it is a tab; in the drawer it is a section title over its children. Guards hide an entry or, withNavRefused.disable, turn it off. package:fespalier_adaptive/fespalier_adaptive.dartis the model (AdaptiveNav,NavBreakpoints,AdaptiveNavBuilder) with no Material import, for Cupertino ormaterial_ui;material.dartis the scaffold. In a test, Flutter's default 800 x 600 window is a rail with the default breakpoints.
All of it, with compiled samples, is in references/adaptive-layouts.md.
Without the package, or on 0.8.x, references/adaptive-by-hand.md has a
bar-versus-rail tab layout whose tab state survives a resize, and a drawer-versus-side-list plain layout
that highlights the current route through AppManifest.of(GoRouterState.of(context)).
Examples
examples/tabs: the tab layout ((tabs)/layout.dart, a Library tab that is a tab layout of its own), sixnav.dartfiles drawn byfespalier_adaptive, and the restoration and resize tests.examples/features: a rootlayout.dartandnav.dart, theteams/$teamIdsection layout, and the menu and scroll restoration tests.
The fespalier skill lists every example.
Quick diagnosis
| Symptom | Likely cause |
|---|---|
| Routes do not animate (go_router 18) | No root transition.dart; with Flutter's MaterialApp go_router 18 animates nothing |
| Every layout shell now animates after upgrading | 0.3.0: a transition.dart at or above a layout animates its shell too |
| A tab lost its state on switching | A custom container that does not keep every child in the tree (use Offstage/Stack) |
tabs error on a (group) or $folder tab |
The tab's first route has a :segment; add tabOptions initialLocation or restructure |
| A full-screen page shows the tab bar | It is inside the layout's folder without navigator.dart (or outside it, to avoid tabs) |
| Dialog opens over a blank screen on a deep link | The dialog route has no parent page above it in the tree |
| A menu entry is missing | Its folder needs segments the location lacks, inMenu: false, or a guard refuses it |
| No bottom bar on a phone, a rail in a test | No menu entry is the current tab, or the test window is 800 wide (0.9.0, fespalier_adaptive) |
| Restored app forgets a page's local state | Custom Page without restorationId: Transitions.restorationIdOf(key), or renamed folders |
| A list starts at the top after the browser's back | scroll_restoration is off, or the scrollable has no PageStorageKey (since 0.8.1) |
For an fsp error message, see
fespalier-troubleshooting.