Navigation and Routing

Navigator 1.0 (Imperative)

The classic approach uses a stack-based Navigator:

// Push a new screen
Navigator.push(
  context,
  MaterialPageRoute(builder: (_) => DetailScreen(productId: '42')),
);

// Pop back
Navigator.pop(context);

// Pop and return data
Navigator.pop(context, 'selected_value');

// Receive returned data
var result = await Navigator.push<String>(
  context,
  MaterialPageRoute(builder: (_) => SelectionScreen()),
);
if (result != null) print('Selected: $result');

Named Routes

Define routes in MaterialApp and navigate by name:

MaterialApp(
  initialRoute: '/',
  routes: {
    '/': (context) => const HomeScreen(),
    '/products': (context) => const ProductListScreen(),
    '/settings': (context) => const SettingsScreen(),
  },
)

// Navigate by name
Navigator.pushNamed(context, '/products');

Passing Arguments

Use onGenerateRoute to handle complex route arguments:

class AppRouter {
  static Route<dynamic> generateRoute(RouteSettings settings) {
    switch (settings.name) {
      case '/product-detail':
        final args = settings.arguments as ProductArgs;
        return MaterialPageRoute(
          builder: (_) => ProductDetailScreen(product: args.product),
        );
      case '/settings':
        return MaterialPageRoute(builder: (_) => const SettingsScreen());
      default:
        return MaterialPageRoute(builder: (_) => const HomeScreen());
    }
  }
}

// Navigate with arguments
Navigator.pushNamed(context, '/product-detail',
  arguments: ProductArgs(product: selectedProduct),
);

Why Navigator 2.0 Exists

Navigator 1.0 works fine for simple apps, but breaks down when you need:

• Deep linking: URLs that map directly to specific screens
• Web-style navigation: Browser back/forward buttons
• Dynamic routing: Routes that change based on authentication state
• Nested navigation: Independent navigation within tabs

go_router: The Practical Solution

Most production apps use go_router, which provides a declarative API built on Navigator 2.0:

final router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/product/:id',
      builder: (context, state) {
        final id = state.pathParameters['id']!;
        return ProductScreen(id: id);
      },
    ),
  ],
  redirect: (context, state) {
    final isLoggedIn = /* check auth */;
    if (!isLoggedIn && state.matchedLocation != '/login') {
      return '/login';
    }
    return null;
  },
);

Navigator 2.0 (Declarative)

Navigator 2.0 uses the Router API for a declarative approach, ideal for deep linking:

class AppRouter extends RouterDelegate<AppRoutePath>
    with ChangeNotifier {
  AppRoutePath _currentPath = AppRoutePath.home();

  @override
  AppRoutePath get currentConfiguration => _currentPath;

  @override
  Widget build(BuildContext context) {
    return Navigator(
      pages: [
        if (_currentPath.isHome)
          MaterialPage(child: HomeScreen(onSelect: _selectProduct)),
        if (_currentPath.isDetail)
          MaterialPage(child: ProductDetailScreen(id: _currentPath.productId!)),
      ],
      onPopPage: (route, result) {
        _currentPath = AppRoutePath.home();
        notifyListeners();
        return route.didPop(result);
      },
    );
  }

  void _selectProduct(String id) {
    _currentPath = AppRoutePath.detail(id);
    notifyListeners();
  }
}

Real-World Example: Product List → Detail

// Product List Screen
class ProductListScreen extends StatelessWidget {
  const ProductListScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Products')),
      body: ListView.builder(
        itemCount: 20,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text('Product ${index + 1}'),
            subtitle: Text('\$${(index + 1) * 9.99}'),
            trailing: const Icon(Icons.chevron_right),
            onTap: () => Navigator.pushNamed(
              context, '/product-detail',
              arguments: ProductArgs(
                product: Product('p_${index}', 'Product ${index + 1}', (index + 1) * 9.99),
              ),
            ),
          );
        },
      ),
    );
  }
}

// Product Detail Screen
class ProductDetailScreen extends StatelessWidget {
  final Product product;
  const ProductDetailScreen({super.key, required this.product});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(product.name)),
      body: Column(children: [
        Text(product.name, style: Theme.of(context).textTheme.headlineMedium),
        Text('\$${product.price.toStringAsFixed(2)}',
          style: const TextStyle(fontSize: 24, fontWeight: FontWeight.bold)),
        ElevatedButton(
          onPressed: () => Navigator.pop(context),
          child: const Text('← Back to Products'),
        ),
      ]),
    );
  }
}

Summary

• Navigator.push/pop for imperative navigation
• Named routes for cleaner route definitions
• onGenerateRoute for complex argument passing
• Navigator 2.0 for deep linking and declarative routing