1# GoRouter Navigation
2 
3## Basic Setup
4 
5```dart
6import 'package:go_router/go_router.dart';
7 
8final goRouter = GoRouter(
9  initialLocation: '/',
10  redirect: (context, state) {
11    final isLoggedIn = /* check auth */;
12    if (!isLoggedIn && !state.matchedLocation.startsWith('/auth')) {
13      return '/auth/login';
14    }
15    return null;
16  },
17  routes: [
18    GoRoute(
19      path: '/',
20      builder: (context, state) => const HomeScreen(),
21      routes: [
22        GoRoute(
23          path: 'details/:id',
24          builder: (context, state) {
25            final id = state.pathParameters['id']!;
26            return DetailsScreen(id: id);
27          },
28        ),
29      ],
30    ),
31    GoRoute(
32      path: '/auth/login',
33      builder: (context, state) => const LoginScreen(),
34    ),
35  ],
36);
37 
38// In app.dart
39class MyApp extends StatelessWidget {
40  const MyApp({super.key});
41 
42  @override
43  Widget build(BuildContext context) {
44    return MaterialApp.router(
45      routerConfig: goRouter,
46      theme: AppTheme.light,
47      darkTheme: AppTheme.dark,
48    );
49  }
50}
51```
52 
53## Navigation Methods
54 
55```dart
56// Navigate and replace history
57context.go('/details/123');
58 
59// Navigate and add to stack
60context.push('/details/123');
61 
62// Go back
63context.pop();
64 
65// Replace current route
66context.pushReplacement('/home');
67 
68// Navigate with extra data
69context.push('/details/123', extra: {'title': 'Item'});
70 
71// Access extra in destination
72final extra = GoRouterState.of(context).extra as Map<String, dynamic>?;
73```
74 
75## Shell Routes (Persistent UI)
76 
77```dart
78final goRouter = GoRouter(
79  routes: [
80    ShellRoute(
81      builder: (context, state, child) {
82        return ScaffoldWithNavBar(child: child);
83      },
84      routes: [
85        GoRoute(path: '/home', builder: (_, __) => const HomeScreen()),
86        GoRoute(path: '/profile', builder: (_, __) => const ProfileScreen()),
87        GoRoute(path: '/settings', builder: (_, __) => const SettingsScreen()),
88      ],
89    ),
90  ],
91);
92```
93 
94## Query Parameters
95 
96```dart
97GoRoute(
98  path: '/search',
99  builder: (context, state) {
100    final query = state.uri.queryParameters['q'] ?? '';
101    final page = int.tryParse(state.uri.queryParameters['page'] ?? '1') ?? 1;
102    return SearchScreen(query: query, page: page);
103  },
104),
105 
106// Navigate with query params
107context.go('/search?q=flutter&page=2');
108```
109 
110## Quick Reference
111 
112| Method | Behavior |
113|--------|----------|
114| `context.go()` | Navigate, replace stack |
115| `context.push()` | Navigate, add to stack |
116| `context.pop()` | Go back |
117| `context.pushReplacement()` | Replace current |
118| `:param` | Path parameter |
119| `?key=value` | Query parameter |
120