navigation

Navigation

Routing and navigation best practices for Flutter applications using GoRouter, the Flutter team's recommended routing package built on the Navigator 2.0 API.

Core Standards

Apply these standards to ALL navigation work:

• Use package:go_router for all navigation — never raw Navigator 2.0 or Navigator 1.0 push/pop
• Use @TypedGoRoute annotations for type-safe routes — never raw string paths in route definitions
• Prefer go() over push() — use push() only when expecting return data from the destination
• Never use the extra parameter — it breaks deep linking and does not work on the web
• Hierarchical sub-routes for proper back navigation — structure routes as parent-child trees, not flat lists
• Hyphens for URL word separation — never underscores or camelCase in URL paths
• Navigate by route name, not raw path strings — use named route navigation to decouple from path changes
• Use BuildContext extensions for navigation — prefer context.goNamed() over GoRouter.of(context).goNamed()

Route Organization

Structure routes hierarchically with logical parent-child relationships. Sub-routes ensure the app bar back button displays correctly and URLs remain clean.

Hierarchical Structure (Preferred)

/flutter
  /flutter/news
  /flutter/chat
  /flutter/articles
    /flutter/articles?category=all
    /flutter/article/:id
/android
  /android/news
  /android/chat

Flat Structure (Avoid)

/flutter-news
/flutter-chat
/android-news
/android-chat

Hierarchical sub-routes produce proper backward navigation automatically — when a user is on /flutter/news, the back button navigates to /flutter.

Type-Safe Routes

Use @TypedGoRoute annotations with GoRouteData classes to eliminate typos and manual parameter casting. The go_router_builder package generates type-safe route helpers at build time.

Basic Route

@TypedGoRoute<CategoriesPageRoute>(
  name: 'categories',
  path: '/categories',
)
@immutable
class CategoriesPageRoute extends GoRouteData {
  const CategoriesPageRoute({
    this.size,
    this.color,
  });

  final String? size;
  final String? color;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return CategoriesPage(size: size, color: color);
  }
}