Navigator v1 Navigation

Priority: P0 (CRITICAL)

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

See references/on-generate-route.md.

Related Topics

idiomatic-flutter | widgets