flutter-navigation

When to Use

• Adding a new route/screen
• Protecting routes behind authentication
• Setting up bottom navigation with shell routes
• Implementing deep links
• Passing parameters between screens

Router Setup

Full GoRouter configuration with public routes, auth redirect, and StatefulShellRoute for bottom navigation.

Example: See assets/app_router.dart

Auth Guard — Global Redirect

Redirect function that checks auth state and routes accordingly:

• Not authenticated + protected route → /login?redirect=...
• Authenticated + auth route → /home (or stored redirect)

Example: See assets/auth_guard.dart

Route Patterns

Four common patterns: simple route, path parameter, query parameter, and nested routes.

Examples: See assets/route_patterns.dart

Shell Routes — Bottom Navigation

StatefulShellRoute preserves state across tabs (each tab keeps its own navigation stack).

Example: See assets/main_shell.dart

Navigation in Widgets

Use context.go(), context.push(), and context.pop() for declarative navigation.

Example: See assets/navigation_commands.dart

Connecting Router to MaterialApp

Use MaterialApp.router with routerConfig from a Riverpod provider.

Example: See assets/app_entry.dart

Route Organization by Feature

Feature	Routes
Auth	/login, /register, /forgot-password
Home	/home
Booking	/bookings, /bookings/:id, /bookings/new
Pet	/pet/:petId, /pet/:petId/edit, /pet/:petId/medical
Caregiver	/caregivers, /caregivers/:id
Profile	/profile, /profile/edit
Chat	/chat, /chat/:chatId

Naming Conventions

Element	Pattern	Example
Route path	kebab-case	/forgot-password
Path parameter	camelCase	:petId, :chatId
Query parameter	camelCase	?serviceType=walk
Router provider	routerProvider	Single global instance

Anti-Patterns

❌ Don't	✅ Do
Navigator.push (old API)	context.go() or context.push()
Hardcode auth check in every page	Use global redirect in GoRouter
Create router outside Riverpod	Use Provider<GoRouter> for reactivity
Deep nest routes beyond 3 levels	Flatten with path parameters
Pass complex objects via route	Pass IDs, fetch data in the page via provider
Forget to handle redirect param on login	Store and restore redirect after auth

Resources

• Templates: See assets/ for router setup, guards, shell, and route patterns