playx_navigation 3.0.0
playx_navigation: ^3.0.0 copied to clipboard
Playx Navigation is a Flutter package that enhances app navigation with advanced features like route lifecycle management, custom transitions, and flexible configuration.
Playx Navigation #
Playx Navigation is a navigation package for Flutter built on go_router.
It keeps everything go_router gives you and adds what larger apps keep rebuilding by hand: a reliable
page lifecycle, page-scoped state, web-friendly navigation, and navigation without a BuildContext.
📖 Read the documentation ·
API reference ·
Changelog ·
llms.txt
Features #
- Page lifecycle:
onEnter,onHidden,onReEnter,onExitper page, correct with shell routes, stacked pages, deep links, replace and the browser's back button. - App initialization:
onInitAppregisters app-level dependencies at boot;PlayxNavigation.ensureInitializedgates startup logic. - Page scopes and route controllers: a controller per page that stacked pages can't overwrite, created and disposed for you (
PlayxRoute<T>(controller: ...)), with aGetView-likePlayxView<T>and optional GetX interop. - Guards, redirects and error handling:
PlayxGuard, bindingredirect,errorBuilder/enterTimeoutwith retry. - Loading without blank frames: shell builder, init-aware builder, non-blocking init, cross-fade, global
PlayxPageConfig. - Web:
back()to the parent when nothing can be popped,popUntil,PlayxBackButton, safeextraAs/intPathParam, breadcrumbs and browser tab titles. - Navigate from anywhere:
PlayxNavigation.to,toNamed,offAll,offAndTo,popUntil, ... noBuildContextneeded. - Custom page transitions and a binding registry (
PlayxNavigation.findBinding<T>()).
Installation #
dependencies:
playx_navigation: ^3.0.0
flutter pub get
playx_navigation re-exports go_router, so one import is enough:
import 'package:playx_navigation/playx_navigation.dart';
Requires Flutter >=3.27.0 and Dart >=3.6.0. Upgrading from 2.x? See the
migration guide.
Quick start #
1. Routes. Use PlayxRoute (a GoRoute) and give it a controller, a binding, or both:
final router = GoRouter(
initialLocation: '/jobs',
routes: [
PlayxRoute<JobsController>(
path: '/jobs',
breadcrumb: (context, state) => 'Jobs',
controller: (context, state) => JobsController(),
disposeController: (controller) => controller.onClose(),
builder: (context, state) => const JobsView(),
routes: [
PlayxRoute<JobDetailsController>(
path: ':id',
breadcrumb: (context, state) => 'Job #${state.pathParameters['id']}',
controller: (context, state) =>
JobDetailsController(id: state.intPathParam('id')!, job: state.extraAs<Job>()),
builder: (context, state) => const JobDetailsView(),
),
],
),
],
);
2. Views. PlayxView<T> gives the page's controller, like GetView<T>. Child widgets in other files work too:
class JobsView extends PlayxView<JobsController> {
const JobsView({super.key});
@override
Widget buildView(BuildContext context, JobsController controller) => Scaffold(
body: const BuildJobsList(),
floatingActionButton: FloatingActionButton(onPressed: controller.refresh),
);
}
3. App. Wrap your app in PlayxNavigationBuilder. It boots navigation and runs every binding's onInitApp:
PlayxNavigationBuilder(
router: router,
config: const PlayxPageConfig(loadingWidget: Center(child: CircularProgressIndicator())),
builder: (context) => MaterialApp.router(routerConfig: router),
)
4. Navigate from anywhere.
PlayxNavigation.toNamed('jobDetails', pathParameters: {'id': '5'}, extra: job);
PlayxNavigation.back(); // pops, or goes to the parent page on web
PlayxNavigation.popUntil('/jobs', orGo: true);
Prefer explicit lifecycle methods? Use a binding:
class JobsBinding extends PlayxBinding {
@override
Future<void> onInitApp() async => JobsRepository.register(); // once, at boot
@override
Future<void> onEnter(BuildContext context, GoRouterState state) async {
PlayxScope.of(context).put(JobsController(), dispose: (c) => c.onClose());
}
@override
Future<void> onReEnter(BuildContext context, GoRouterState? state, bool popped) async {
// The page is visible again (popped: a child page was removed, otherwise a tab switch).
}
}
Choosing an approach #
| Binding | Binding + scope | Route controller | |
|---|---|---|---|
| You write | a PlayxBinding |
a PlayxBinding |
a controller: factory |
| Safe when the same route is stacked | only if keyed by hand | yes | yes |
| Best for | app-level setup, redirects | async setup, several resources | one controller per page |
The three can be mixed in one app. Compare them in detail.
Documentation #
| Topic | |
|---|---|
| Installation and setup | Step-by-step setup |
| Routes and transitions | PlayxRoute, shell branches, transitions |
| Bindings and lifecycle | Callbacks, guarantees, a table of scenarios |
| Page configuration | Loading widget, shell builder, init builder |
| Guards and redirects | Protect routes, validate parameters |
| Error handling | errorBuilder, enterTimeout, retry |
| Scopes and route controllers and views | Page-scoped state, PlayxView |
| GetX and other registries | Interop hooks |
| PlayxNavigation API | Every navigation method |
| Web and breadcrumbs and page titles | Refresh, deep links, back, tab titles |
| Testing your app | Testing bindings, controllers, guards |
| Troubleshooting | Common problems |
For AI assistants: llms.txt and
llms-full.txt.
Example #
The example app shows shell routes with tabs, parent and child pages, route controllers
with PlayxView, bindings, breadcrumbs and the page lifecycle.
Contributing #
Issues and pull requests are welcome. Before opening a PR run:
dart format .
flutter analyze lib test
flutter test --coverage
The documentation lives in docs (MkDocs). To preview it locally:
pip install -r tool/requirements-docs.txt
python tool/build_llms_full.py
mkdocs serve
Support #
For questions, issues or feature requests, visit the GitHub repository.
See also #
- Playx: ecosystem for redundant features, less code, more productivity, better organizing.
- Playx_core: core of the Playx ecosystem, helping with app theming and localization.
- Playx_localization: localization and internationalization for Flutter apps from the Playx ecosystem.
License #
This project is licensed under the MIT License - see the LICENSE file for details.