skills/flutter/references/features-router.md

name	description
features-router	Flutter Router API - declarative routing, RouterDelegate, and route configuration

Router API

Flutter's Router API provides declarative routing for navigation.

Router Widget

Use Router widget for declarative routing.

MaterialApp.router(
  routerConfig: _router,
  title: 'My App',
)

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

GoRouter (go_router package)

Popular declarative routing package.

import 'package:go_router/go_router.dart';

final router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
    ),
    GoRoute(
      path: '/detail/:id',
      builder: (context, state) {
        final id = state.pathParameters['id']!;
        return DetailScreen(id: int.parse(id));
      },
    ),
    GoRoute(
      path: '/settings',
      builder: (context, state) => const SettingsScreen(),
      routes: [
        GoRoute(
          path: 'profile',
          builder: (context, state) => const ProfileScreen(),
        ),
      ],
    ),
  ],
  errorBuilder: (context, state) => const NotFoundScreen(),
);

// Usage
MaterialApp.router(
  routerConfig: router,
)

Navigation with GoRouter

// Navigate
context.go('/detail/123');

// Push (add to stack)
context.push('/detail/123');

// Pop
context.pop();

// Replace
context.go('/home', extra: {'data': 'value'});

// Access parameters
final id = GoRouterState.of(context).pathParameters['id'];
final query = GoRouterState.of(context).uri.queryParameters['search'];

Route Guards

Implement route guards with GoRouter.

final router = GoRouter(
  redirect: (context, state) {
    final isLoggedIn = authService.isAuthenticated;
    final isLoginRoute = state.matchedLocation == '/login';
    
    if (!isLoggedIn && !isLoginRoute) {
      return '/login';
    }
    
    if (isLoggedIn && isLoginRoute) {
      return '/';
    }
    
    return null; // No redirect
  },
  routes: [...],
);

Route Configuration

GoRoute(
  path: '/detail/:id',
  name: 'detail', // Named route
  builder: (context, state) {
    final id = state.pathParameters['id']!;
    return DetailScreen(id: id);
  },
  redirect: (context, state) {
    // Redirect logic
    return null;
  },
)

Key Points

• Use Router widget for declarative routing
• Use GoRouter package for easier route management
• Define routes declaratively
• Use path parameters for dynamic routes
• Use query parameters for optional data
• Implement route guards with redirect
• Use context.go() for navigation
• Use context.push() to add to navigation stack