navigator

Description:

navigator

Navigator #

An easy yet powerful navigator for simple flutter apps.
Features #

Easy to integrate & easy to use
Uses Flutter's Navigator v1.0
Supports deeplinking and routing from external components
Doesn't use magic

Getting started #
Add this package as a dependency
flutter pub add navigator
copied to clipboard
Import this package in your file
import 'package:navigator/navigator.dart';
copied to clipboard
Usage #
Setup #

Create a List<NavigationPath>

final navigationPaths = [
NamedPath(
pathName: AppLaunchScreen.routeName,
builder: (_, settings) {
final redirectionPathName = getValueIfTypeMatched<String>(
settings.arguments,
);

return AppLaunchScreen(
routePath: redirectionPathName,
reRoutePath: HomeScreen.route,
);
},
),
NamedPath(
pathName: HomeScreen.routeName,
builder: (_, __) => const HomeScreen(),
),
NavigationPath(
matcher: (route) =>
route?.name?.startsWith('${MovieDetailsScreen.route}/') ?? false,
builder: (_, settings) {
return MovieDetailsScreen();
},
),
];
copied to clipboard

Create a router configuration with a list of NavigationPath.

final navigationProvider = RouterConfiguration(
paths,
);
copied to clipboard
Install #
2.1. Add router configuration to your MaterialApp
child: MaterialApp(
// ...
navigatorKey: navigationProvider.navigatorKey,
onGenerateRoute: navigationProvider.onGenerateRoute,
onUnknownRoute: navigationProvider.onUnknownRoute,
// ...
),
copied to clipboard
More #
Provide #
You can optionally use your favorite dependency injection framework for providing List<NavigationPath> & RouterConfiguration to MaterialApp. (Riverpod is used in the below example).
final navigationProvider = Provider((ref) {
final paths = ref.read(navigationPaths);

return RouterConfiguration(
paths,
);
});

final navigationPaths = Provider<List<NavigationPath>>((ref) {
return [
NavigationPath(
matcher: (route) => route?.name == AppLaunchScreen.routeName,
builder: (_, settings) {
final pathName = getValueIfTypeMatched<String>(
settings.arguments,
);

return AppLaunchScreen(
routePath: pathName,
reRoutePath: HomeScreen.route,
);
},
),
NamedPath(
pathName: UnverifiedAppScreen.routeName,
builder: (_, __) => const UnverifiedAppScreen(),
),
NavigationPath(
matcher: (route) =>
route?.name?.startsWith('${MovieDetailsScreen.route}/') ?? false,
builder: (_, settings) {
return MovieDetailsScreen();
},
),
];
});
copied to clipboard
final _nav = ref.read(navigationProvider);

// ...
child: MaterialApp(
// ...
navigatorKey: _nav.navigatorKey,
onGenerateRoute: _nav.onGenerateRoute,
onUnknownRoute: _nav.onUnknownRoute,
// ...
),
copied to clipboard
Context-less navigation #
Use can use navigatorState from RouterConfiguration's instance for navigation without context: RouterConfiguration.navigatorState.
Function & Working #

This package heavily relies on MaterialApp.onGenerateRoute.
Upon navigation from Navigator.of(context).*, RouterConfiguration checks RouteSettings.name in RouterConfiguration.namedPathsMap first. If the result is not null, NamedPath.builder is used to create a route.
If result is null from namedPathsMap, RouterConfiguration iteratively runs NavigationPath.matcher for every NavigationPath in RouterConfiguration.paths.
Upon first match, NavigationPath.builder is used to create a route.
This also means that paths with lower index in the list RouterConfiguration.paths has higher precedence.

Default Behaviours #

By default, NoAnimationMaterialPageRoute when creating a route for web platform and MaterialPageRoute is used for route creation for all other platforms. This behaviour can be overriden by using NavigationPath.routeBuilder for providing a custom PageRoute from a builder callback.

Upcoming

Navigator v2.0 support.

Please report any issues or improvements on this project's Issues Tracker.