Module 10: Navigation and Routing

The Navigator Is a Stack of Plates

Here is the single most important mental model for Flutter navigation: it is a stack. The Navigator widget manages this stack for you, and you interact with it using two primary methods.

Navigator.push -- Adding a Screen

When a user taps something and you want to show a new screen, you push it onto the stack:

Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => DetailScreen()),
);

That MaterialPageRoute is how you tell Flutter what to put on top. The builder function returns the widget that becomes the new screen. Flutter handles the slide-in animation automatically.

Navigator.pop -- Going Back

When the user is done with the current screen, you pop it off:

Navigator.pop(context);

That is it. One line. The screen slides away, and whatever was underneath reappears. The back button in the AppBar and the device back button both call Navigator.pop under the hood.

Passing Data Forward: Constructor Arguments

Let's say you have a product list, and when the user taps a product, you want the detail screen to know about it. First, set up the detail screen to accept data:

class ProductDetailScreen extends StatelessWidget {
  final String productName;
  final double price;

  const ProductDetailScreen({
    super.key,
    required this.productName,
    required this.price,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(productName)),
      body: Center(
        child: Text('Price: \$${price.toStringAsFixed(2)}'),
      ),
    );
  }
}

Then, when you push, just fill in those constructor parameters:

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => ProductDetailScreen(
      productName: 'Wireless Headphones',
      price: 79.99,
    ),
  ),
);

That's the whole pattern. The data travels forward through the constructor.

Returning Data: The await/pop Pattern

Here is something that trips people up the first time: Navigator.push returns a Future. That means you can await it. And when the pushed screen pops, it can send data back.

Think of it like sending someone to the store. You wait for them to come back, and they hand you a bag of groceries. The "waiting" is the await, and the "bag of groceries" is the value passed to Navigator.pop.

The Calling Screen (the one that waits)

void _openSelectionScreen() async {
  final result = await Navigator.push<String>(
    context,
    MaterialPageRoute(builder: (context) => SelectionScreen()),
  );

  if (result != null) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('You selected: $result')),
    );
  }
}

Notice the <String> generic on Navigator.push. That tells Dart what type of data to expect back.

The Pushed Screen (the one that returns data)

// User made a choice -- pop with data
Navigator.pop(context, 'Added to cart');

// User hit back without choosing -- pop with nothing
Navigator.pop(context);

When pop is called with a second argument, that value becomes the result of the await on the calling screen. If no value is passed, result is null.

Named Routes: Navigation by String

So far, you have been creating routes inline with MaterialPageRoute. That works great, but as your app grows, you might want a central registry of all your screens. That is what named routes give you.

Setting Up Named Routes

Define your routes in MaterialApp:

MaterialApp(
  initialRoute: '/',
  routes: {
    '/': (context) => HomeScreen(),
    '/details': (context) => DetailScreen(),
    '/settings': (context) => SettingsScreen(),
    '/profile': (context) => ProfileScreen(),
  },
)

Navigating with Named Routes

Navigator.pushNamed(context, '/details');

Clean and simple. No MaterialPageRoute boilerplate.

Passing Arguments with Named Routes

Named routes can carry arguments too, but the mechanism is slightly different. You pass a generic arguments object:

// Push with arguments
Navigator.pushNamed(
  context,
  '/details',
  arguments: {'id': 42, 'title': 'Wireless Headphones'},
);

On the receiving screen, you extract them from the route settings:

@override
Widget build(BuildContext context) {
  final args = ModalRoute.of(context)!.settings.arguments
      as Map<String, dynamic>;

  return Scaffold(
    appBar: AppBar(title: Text(args['title'])),
    body: Center(child: Text('Item ID: ${args['id']}')),
  );
}

onGenerateRoute for More Control

If you need to parse route names dynamically or handle unknown routes gracefully, use onGenerateRoute:

MaterialApp(
  onGenerateRoute: (settings) {
    if (settings.name == '/product') {
      final args = settings.arguments as Map<String, dynamic>;
      return MaterialPageRoute(
        builder: (context) => ProductDetailScreen(
          productName: args['name'],
          price: args['price'],
        ),
      );
    }

    // Fallback for unknown routes
    return MaterialPageRoute(
      builder: (context) => NotFoundScreen(),
    );
  },
)

This gives you the clean URL-style navigation of named routes plus the ability to unpack arguments into constructors.

WillPopScope: Intercepting the Back Button

WillPopScope wraps a widget and provides an onWillPop callback that returns a Future<bool>. Return true to allow the pop, false to block it.

WillPopScope(
  onWillPop: () async {
    final shouldLeave = await showDialog<bool>(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('Unsaved Changes'),
        content: Text('You have unsaved changes. Leave anyway?'),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context, false),
            child: Text('Stay'),
          ),
          TextButton(
            onPressed: () => Navigator.pop(context, true),
            child: Text('Leave'),
          ),
        ],
      ),
    );
    return shouldLeave ?? false;
  },
  child: Scaffold(
    appBar: AppBar(title: Text('Edit Settings')),
    body: TextField(
      decoration: InputDecoration(labelText: 'Setting value'),
    ),
  ),
)

Notice something interesting: the showDialog itself uses Navigator.pop to close the dialog and return a boolean. That is pop returning data, exactly like the pattern you learned earlier. Navigation patterns compose beautifully.

There Are No Dumb Questions

Q: What is the difference between Navigator.push and Navigator.pushNamed?

A: They do the same thing -- add a screen to the stack. push takes a Route object (usually MaterialPageRoute) that you build inline. pushNamed takes a string name and looks it up in the route table you defined in MaterialApp. Named routes are more organized for large apps; inline push is more flexible for passing constructor arguments directly.

Q: Can I use Navigator.push and Navigator.pushNamed in the same app?

A: Absolutely. Many apps use named routes for their main navigation structure and inline push for one-off screens like dialogs or selection screens.

Q: What happens if I pop when there is only one screen on the stack?

A: On Android, it exits the app. On iOS, nothing visible happens (the OS handles the home gesture). In general, do not pop your root screen.

Q: Is WillPopScope deprecated?

A: In Flutter 3.16+, WillPopScope was replaced by PopScope with a slightly different API. If you are on an older version, WillPopScope works fine. The concept is identical -- intercept the pop and decide whether to allow it.

Q: Why store the Future in initState instead of calling it in build?

A: This applies to FutureBuilder but the principle matters here too. If you call an async function inside build, it gets called every time the widget rebuilds. For navigation, each push/pop triggers rebuilds, so you want to be careful about triggering side effects in build.

Sharpen Your Pencil: Multi-Screen Product Browser

Build a product browsing app with two screens that pass data in both directions.

ProductListScreen

1. Create a StatefulWidget called ProductListScreen.
2. Define a list of at least 8 products. Each product is a Map<String, dynamic> with keys: id (int), name (String), price (double), description (String), and inStock (bool).
3. Display them in a ListView.builder with Card and ListTile:
4. leading: a CircleAvatar with the product's first letter.
5. title: the product name.
6. subtitle: the price formatted as "\$XX.XX".
7. trailing: Icons.check_circle (green) if in stock, Icons.cancel (red) if not.
8. On tap, push ProductDetailScreen with the product map. Await the result -- if it is "added_to_cart", show a SnackBar saying "[name] added to cart!".

ProductDetailScreen

1. Create a StatelessWidget that accepts a product map via constructor.
2. Display all fields: name (large bold), price, description, stock status (colored text).
3. An "Add to Cart" ElevatedButton that is disabled when out of stock. When pressed, pop with "added_to_cart".
4. A "Back" TextButton that pops without a result.

Sharpen Your Pencil: Named Routes App

Build an app using named routes with argument passing and back-button interception.

Setup

1. Create a MaterialApp with initialRoute: '/' and routes for '/', '/profile', and '/settings'.

HomeScreen

• Two buttons: "View Profile" (navigates to /profile with {'name': 'Alex', 'role': 'Developer'}) and "Settings" (navigates to /settings).

ProfileScreen

• Extracts arguments from ModalRoute.of(context)!.settings.arguments.
• Displays the name and role.
• Has a back button.

SettingsScreen

• A StatefulWidget with a TextField.
• Wrapped in WillPopScope -- when back is pressed, show a confirmation dialog asking "Discard changes?".
• Only pop if the user confirms.

📝 Module Quiz

Test what you learned. 45 seconds per question. Passing score is set per module. Your best attempt is saved in your browser so you can track progress -- nothing is sent to a server.

Putting It All Together