Navigator

Hosts a stack of screens: pages pushed on top of each other, and dialogs presented over them. FleuryApp(home: ...) creates one at the app root; nest another inside any layout slot to navigate within that region.

Learn more: Navigation & dialogs

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// FleuryApp(home: ...) creates the root navigator. Nest another Navigator
// to keep a flow inside one pane:
Navigator(home: const SetupStep())

// From any screen below a navigator:
final result = await context.push<String>(const DetailsScreen());
final confirmed = await context.present<bool>(const ConfirmDialog());
context.pop('done'); // completes the push that opened this screen

Details

NavigatorState.push adds a page and NavigatorState.present shows a dialog over the current screen, which stays visible behind it. Both return a future that completes with the result passed to NavigatorState.pop. context.push, context.present, and context.pop do the same on the nearest navigator. Screens below the top stay mounted and keep their state, and popping back restores focus to where it was on the revealed screen.

An Escape that the screen doesn’t handle itself pops the top page, and pops a dialog unless it was presented with barrierDismissible: false. At the root, where there’s nothing to pop, Escape passes on to key bindings outside the navigator. A PopScope in the top route can veto an Escape pop. Clicking outside a dialog doesn’t dismiss it.

While a dialog is on top, focus stays inside it, keys it doesn’t handle stop at the dialog instead of reaching bindings outside it, and clicks on the screen behind it do nothing.

NavigatorState.pop ignores PopScope. For a Back button that should respect it, call Navigator.of(context).maybePop(), which pops only when Escape would.

Routes animate in and out with transition, a cross-fade by default; each push or present can pass its own.

Constructors

`Navigator()`

Parameter	Type	Default	Description
`home:`	`Widget`	required	The initial (root) screen. More
`transition:`	`RouteTransition?`	—	The transition for pushes and presents that don’t pass their own; null means `RouteTransition.fade`. Use `RouteTransition.none` to switch routes instantly.

home: Updating this widget reconciles the original root route in place, keeping its state, focus memory, and any pushed routes. Once replacement or a stack clear removes that original route, later home updates do not recreate it.

Source

Navigator is defined in packages/fleury/lib/src/widgets/navigator.dart.

Category: Navigation & overlays · All widgets

Example · editable

Widget example() =>
Navigator(transition: RouteTransition.none, home: const _HomeScreen());

class _HomeScreenState extends State<_HomeScreen> {
  String _result = 'none';

  Future<void> _openDetails() async {
    final result = await context.push<String>(const _DetailsScreen());
    if (!mounted || result == null) return;
    setState(() => _result = result);
  }

  @override
  Widget build(BuildContext context) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      const Text('HOME · STACK DEPTH 1', style: CellStyle(bold: true)),
      const SizedBox(height: 1),
      Button(text: 'Push details', autofocus: true, onPressed: _openDetails),
      const Spacer(),
      Text('result: $_result'),
    ],
  );
}

class _DetailsScreenState extends State<_DetailsScreen> {
  String _dialogResult = 'not shown';

  Future<void> _presentDialog() async {
    final confirmed = await context.present<bool>(const _ConfirmDialog());
    if (!mounted) return;
    setState(() => _dialogResult = confirmed == true ? 'confirmed' : 'closed');
  }

  @override
  Widget build(BuildContext context) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      const Text('DETAILS · STACK DEPTH 2', style: CellStyle(bold: true)),
      Text('dialog: $_dialogResult'),
      const SizedBox(height: 1),
      Button(
        text: 'Present dialog',
        autofocus: true,
        onPressed: _presentDialog,
      ),
      Button(text: 'Pop with result', onPressed: () => context.pop('done')),
      Button(text: 'Pop without result', onPressed: context.pop),
    ],
  );
}

class _ConfirmDialog extends StatelessWidget {
  const _ConfirmDialog();

  @override
  Widget build(BuildContext context) => SizedBox(
    width: 34,
    height: 7,
    child: Panel(
      title: 'PRESENTED DIALOG',
      focused: true,
      child: Center(
        child: Button(
          text: 'Confirm and pop',
          autofocus: true,
          onPressed: () => context.pop(true),
        ),
      ),
    ),
  );
}

Live preview

Live · interactive

click & type to interact ⓘ how this demo runs