Navigator basics

Screens as a stack

In Flutter, a screen is called a route. The Navigator keeps routes in a stack: opening a screen pushes a route on top; going back pops it off and shows the one below. The system back button and the AppBar's back arrow both pop the top route.

Start:           [ Products ]
Tap a product:   [ Products, Details(42) ]
Tap "Buy":       [ Products, Details(42), Checkout ]
Back:            [ Products, Details(42) ]

Each route is usually a full screen: a widget with its own Scaffold. Scaffold's AppBar automatically shows a back arrow when there is a route below it to return to, so you rarely need to write a back button yourself.

Push and pop

// From the products screen:
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => ProductDetails(productId: 42)),
);

// Inside ProductDetails, to go back:
Navigator.pop(context);

Passing data forward

The simplest and safest way to send data to a new screen is through its constructor, like any widget. Pass small things such as an id; the new screen can load the full details itself.

class ProductDetails extends StatelessWidget {
  const ProductDetails({super.key, required this.productId});
  final int productId;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Product $productId')),
      body: Center(
        child: FilledButton(
          onPressed: () => Navigator.pop(context, 'added'),   // return a result
          child: const Text('Add to cart'),
        ),
      ),
    );
  }
}

Getting a result back

Future<void> openDetails(BuildContext context) async {
  final result = await Navigator.push<String>(
    context,
    MaterialPageRoute(builder: (_) => const ProductDetails(productId: 42)),
  );
  if (!context.mounted) return;               // the screen may be gone after the await
  if (result == 'added') {
    ScaffoldMessenger.of(context).showSnackBar(const SnackBar(content: Text('Added to cart')));
  }
}

Replacing and clearing

Controlling the back button

Sometimes Back should ask first, for example on a half-filled form. Current Flutter versions use the PopScope widget (which replaced the older WillPopScope): set canPop to false while there are unsaved changes, and react in its callback by showing a "Discard changes?" dialog. Check the current API in the docs, as its callback name has changed between versions.

Common mistakes

• Using the context of a screen after an await without checking context.mounted.
• Leaving the login screen in the stack, so Back after login returns to it. Use pushReplacement.
• Passing big objects or global variables instead of constructor arguments or ids.
• Calling Navigator.pop on the first screen, which closes the app on Android.