Flutter Navigation Manager

A comprehensive and extensible navigation management package for Flutter. It provides a robust, testable, and unified API for managing navigation, route state, and advanced navigation patterns. The package is backend-agnostic and can be extended to support different navigation solutions.

Features

• Unified navigation API for pushing, replacing, and popping named routes
• Route stack management (pop until, clear stack, check if route exists)
• State passing via path/query parameters and extra data
• Support for shell and nested navigation patterns
• Easily integrates with state management and dependency injection
• Extensible: implement your own NavigationManager for any navigation backend

Installation

Add to your pubspec.yaml:

dependencies:
  flutter_navigation_manager: <latest_version>

Then run:

flutter pub get

Getting Started

1. Implement or use a NavigationManager

The package provides an abstract NavigationManager interface. You can use an existing implementation (such as for go_router) or create your own for your preferred navigation backend.

// Example: Using a GoRouter-based implementation (if available)
final navigationManager = GoNavigationManager(router);

2. Provide the navigation manager

Wrap your app with a provider for the navigation manager:

runApp(
  NavigationManagerProvider(
    navigationManager: navigationManager,
    child: MyApp(),
  ),
);

3. Use the navigation manager in your widgets

final navigationManager = NavigationManagerProvider.of(context);

// Push a named route
navigationManager.pushNamed('details', state: const NavigationState(queryParams: {'from': 'home'}));

// Replace current route
navigationManager.replaceNamed('details');

// Pop the current route
navigationManager.pop();

// Pop until a specific route, optionally push if not found
navigationManager.popUntil('home', pushIfNotFound: true);

// Check if a route exists in the stack
navigationManager.hasRouteInStack('details');

// Get the current navigation state
final NavigationState state = navigationManager.currentState;

4. Advanced: Shell and Nested Navigation

The package supports advanced navigation patterns such as shell and nested navigation, depending on your backend implementation.

API

• pushNamed, replaceNamed, pushNamedAndClearStack
• pop, popUntil, canPop
• hasRouteInStack, isCurrent
• refresh, dispose
• NavigationState for passing path/query params and extra data

Example

See the example for a complete app using all features.

To run:

cd example
flutter run

Requirements

• Flutter 3.8.1 or later

Contributing

Contributions are welcome! Please open issues and submit pull requests for new features, bug fixes, or documentation improvements.

License

This project is licensed under the MIT License. See the LICENSE file for details.