flutter-core:flutter-navigation-routing

What this skill does

# Flutter Navigation and Routing

Expert guidance on implementing navigation and routing in Flutter applications, covering declarative routing patterns, GoRouter integration, deep linking, and complex navigation flows.

## When to Use This Skill

Use this skill when working with:

- Setting up navigation architecture in new Flutter applications
- Migrating from Navigator 1.0 to declarative routing approaches
- Implementing GoRouter for type-safe, declarative navigation
- Configuring deep linking for Android App Links and iOS Universal Links
- Building authenticated routing flows with route guards
- Creating nested navigation with bottom navigation bars or drawer menus
- Handling route state management and navigation preservation
- Implementing web-compatible navigation with URL-based routing

## Navigation Approaches in Flutter

Flutter provides multiple navigation paradigms, each suited to different application requirements and complexity levels.

### Navigator 1.0 (Imperative Navigation)

The traditional Navigator API uses an imperative approach where screens are managed as a stack with platform-appropriate transitions. This approach is straightforward for simple applications:

```dart
// Push a new route
Navigator.of(context).push(
  MaterialPageRoute<void>(
    builder: (context) => const DetailScreen(),
  ),
);

// Return to previous route
Navigator.of(context).pop();
```

Navigator 1.0 is suitable for applications with simple linear navigation flows without deep linking requirements. It offers low complexity, direct control over the navigation stack, and simple data passing between screens.

**When to use Navigator 1.0:**
- Prototypes and simple applications
- Linear navigation flows
- No web deployment or deep linking requirements
- Quick implementation needs

**Limitations:**
- Limited deep linking support
- No declarative route configuration
- Difficult to synchronize with browser history on web
- Cannot easily prevent back navigation based on app state

### Named Routes (Legacy Pattern)

Named routes provide a map-based routing system where routes are registered in MaterialApp and navigated to by string identifiers:

```dart
MaterialApp(
  routes: {
    '/': (context) => const HomeScreen(),
    '/details': (context) => const DetailScreen(),
  },
  onGenerateRoute: (settings) {
    // Handle dynamic route arguments
  },
)

// Navigate using route name
Navigator.pushNamed(context, '/details');
```

**Important:** Named routes are no longer recommended by the Flutter team for most applications. They cannot customize deep link behavior, lack browser forward button support, and always push new routes regardless of the user's current location.

### Navigator 2.0 and Router API (Declarative Navigation)

Navigator 2.0 introduces a declarative routing paradigm where the displayed screens are a function of application state. This approach integrates seamlessly with deep linking and web navigation:

```dart
MaterialApp.router(
  routerConfig: router,
)
```

The Router API requires implementing several components:

**Router:** Configures the list of pages to be displayed by the Navigator based on application state and platform information.

**RouteInformationParser:** Converts route information from the platform (like URLs) into a user-defined configuration object.

**RouterDelegate:** Responds to changes in app state and route information, building the Navigator with the appropriate page stack.

**BackButtonDispatcher:** Reports back button presses to the Router.

Navigator 2.0 provides full control over navigation state, deep linking support, browser integration for web apps, and declarative route configuration. However, it requires significant boilerplate code and has a steeper learning curve.

**When to use Navigator 2.0:**
- Applications requiring custom navigation logic
- Full control over the navigation stack needed
- Learning the underlying Flutter navigation architecture

### GoRouter (Recommended Declarative Solution)

GoRouter is the official recommendation from the Flutter team for most applications requiring declarative routing. It provides a high-level API built on Navigator 2.0 that eliminates boilerplate while offering powerful features:

```dart
final router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) {
            final id = state.pathParameters['id']!;
            return DetailScreen(id: id);
          },
        ),
      ],
    ),
  ],
);

// Navigate declaratively
context.go('/details/123');
context.push('/settings');
```

GoRouter offers URL-based navigation with path and query parameters, nested and stacked routes, route-level and global redirects for authentication, deep linking support for web and mobile, type-safe route definitions, ShellRoute for persistent UI elements, and StatefulShellRoute for bottom navigation with preserved state.

**When to use GoRouter:**
- Most new Flutter applications
- Web applications requiring URL-based routing
- Apps with deep linking requirements
- Applications needing authentication flows
- Complex navigation with nested routes
- Bottom navigation with preserved tab state

## Key Navigation Concepts

### Route Stack Management

Flutter's navigation system manages screens in a stack structure. Each navigation operation modifies this stack:

**Push:** Adds a new route on top of the stack, displaying the new screen while keeping the previous one in memory.

**Pop:** Removes the top route from the stack, returning to the previous screen.

**Replace:** Replaces the current route with a new one without increasing stack depth.

**PopUntil:** Removes routes until a specified condition is met, useful for returning to a specific screen in the stack.

### Data Passing Between Routes

Different navigation approaches handle data passing differently:

**Constructor parameters** work with direct Navigator.push calls, providing type safety and compile-time checking.

**Route arguments** work with named routes and GoRouter, allowing dynamic data passing with runtime type checking.

**State management** provides app-wide state access, useful for complex data sharing across multiple screens.

**Return values** enable data flow back from popped routes using Navigator.pop with a result value.

### Deep Linking

Deep linking allows external sources to open specific screens within your application using URLs. This is essential for:

- Web applications where each screen should have a unique URL
- Marketing campaigns linking to specific app content
- Push notifications directing users to relevant screens
- Platform integration features like Spotlight search on iOS

**Android App Links:** Verified HTTPS URLs that open directly in your app without disambiguation dialogs, requiring domain verification through assetlinks.json.

**iOS Universal Links:** Verified HTTPS URLs associated with your domain, requiring apple-app-site-association file hosted on your website.

**Custom URL schemes:** App-specific URLs (myapp://) that work without domain verification but may show disambiguation if multiple apps register the same scheme.

### Route Guards and Authentication

Route guards protect routes from unauthorized access by checking authentication state before navigation:

```dart
GoRouter(
  redirect: (context, state) {
    final isAuthenticated = /* check auth state */;
    final isAuthRoute = state.matchedLocation == '/login';

    if (!isAuthenticated && !isAuthRoute) {
      return '/login';
    }
    if (isAuthenticated && isAuthRoute) {
      return '/';
    }
    return null; // No redirect needed
  },
  refreshListenable: authChangeNotifier,
)
```

Route guards enable preventing unauthorized access, redirecting to login screens, protecting sensitive routes, and handling authentication state changes during navigation.

## Choosing the Right Navigation Appro