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.