Flutter Navigator v1 (Imperative)

Navigator v1 Navigation

Priority: P0 (CRITICAL)

Standard imperative navigation system built into Flutter using Navigator and MaterialPageRoute.

Implementation Guidelines

• Standard Push: Use Navigator.of(context).push(MaterialPageRoute(builder: (_) => Screen())).
• Named Routes: Define routes map in MaterialApp or use onGenerateRoute for dynamic routing.
• Passing Arguments:
  • For named routes: Use Navigator.pushNamed(context, '/​path', arguments: data).
  • For onGenerateRoute: Extract arguments using settings.arguments.
• Returning Data: final result = await Navigator.push(...) and Navigator.pop(context, data).
• Replacing Screens: Use pushReplacement or pushAndRemoveUntil for auth/​splash flows.

Code Example

// Basic Push
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => const DetailScreen()),
);

// Named Routes Configuration
MaterialApp(
  initialRoute: '/',
  onGenerateRoute: (settings) {
    if (settings.name == '/​details') {
      final args = settings.arguments as Map;
      return MaterialPageRoute(
        builder: (context) => DetailScreen(id: args['id']),
      );
    }
    return null;
  },
);

// Navigation with Arguments
Navigator.pushNamed(
  context,
  '/​details',
  arguments: {'id': 123},
);

Anti-Patterns

• Deep Nesting: Avoid anonymous routes for complex apps; use onGenerateRoute.
• Manual String Paths: Always use constants for route names.
• Context Leaks: Ensure BuildContext is valid when calling Navigator.of(context). Use ScaffoldMessenger or global keys if navigation is needed outside build.

Reference & Examples

For centralized onGenerateRoute implementation: See references/​on-generate-route.md.

Related Topics

idiomatic-flutter | widgets