Flutter Navigation

Overview

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

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

assets/go_router_basic.dart

Avoid Named Routes

• Cannot customize deep link behavior
• No browser forward button support
• Always pushes new routes regardless of current state

Common Tasks

Pass Data Between Screens

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

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

assets/passing_data.dart

Return Data From Screens

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

assets/returning_data.dart

Configure Deep Linking

AndroidManifest.xml

Info.plist

references/deep-linking.md

Web URL Strategy

example.com/#/path

example.com/path

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

references/go_router-guide.md

Decision Guide

• Complete comparison of navigation approaches
• Deep linking behavior by platform
• Web-specific considerations
• Common patterns and anti-patterns