name: flutter-navigation
description: Comprehensive guide for Flutter navigation and routing including Navigator API, go_router, deep linking, passing/returning data, and web-specific navigation. Use when implementing screen transitions, configuring routing systems, setting up deep links, handling browser history, or managing navigation state in Flutter applications.

Flutter Navigation

Overview

Implement navigation and routing in Flutter applications across mobile and web platforms. Choose the right navigation approach, configure deep linking, manage data flow between screens, and handle browser history integration.

Choosing an Approach

Use Navigator API (Imperative) When:

• Simple apps without deep linking requirements
• Single-screen to multi-screen transitions
• Basic navigation stacks
• Quick prototyping

Example: assets/navigator_basic.dart

Use go_router (Declarative) When:

• Apps requiring deep linking (iOS, Android, Web)
• Web applications with browser history support
• Complex navigation patterns with multiple Navigator widgets
• URL-based navigation needed
• Production applications with scalable architecture

Example: assets/go_router_basic.dart

Avoid Named Routes

Flutter team does NOT recommend named routes. They have limitations:
- Cannot customize deep link behavior
- No browser forward button support
- Always pushes new routes regardless of current state

Common Tasks

Pass Data Between Screens

With Navigator:

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

With go_router:

context.push('/details?id=123');
// Extract: final id = state.uri.queryParameters['id'];

Example: assets/passing_data.dart

Return Data From Screens

final result = await Navigator.push(
  context,
  MaterialPageRoute<String>(builder: (context) => SelectionScreen()),
);
if (!context.mounted) return;

Example: assets/returning_data.dart

Configure Deep Linking

Android: Configure AndroidManifest.xml intent filters
iOS: Configure Info.plist for Universal Links
Web: Automatic with go_router, choose URL strategy

For detailed setup: references/deep-linking.md

Web URL Strategy

Hash (default): example.com/#/path - no server config needed
Path: example.com/path - cleaner URLs, requires server config

For server setup: references/web-navigation.md

Navigation Methods

go_router Navigation

• context.go('/path') - replace current route
• context.push('/path') - add to stack
• context.pop() - go back

Navigator Navigation

• Navigator.push() - add route to stack
• Navigator.pop() - remove route from stack

Advanced Topics

Route Guards: Implement authentication redirects
Nested Routes: Create shell routes with shared UI
Error Handling: Handle 404 and navigation errors
Multiple Navigators: Manage independent navigation stacks

For advanced patterns: references/go_router-guide.md

Decision Guide

Use navigation-patterns.md for:
- Complete comparison of navigation approaches
- Deep linking behavior by platform
- Web-specific considerations
- Common patterns and anti-patterns