Skip to main content

playx_navigation 3.0.0 copy "playx_navigation: ^3.0.0" to clipboard
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 #

pub package Build codecov Docs

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, onExit per page, correct with shell routes, stacked pages, deep links, replace and the browser's back button.
  • App initialization: onInitApp registers app-level dependencies at boot; PlayxNavigation.ensureInitialized gates 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 a GetView-like PlayxView<T> and optional GetX interop.
  • Guards, redirects and error handling: PlayxGuard, binding redirect, errorBuilder / enterTimeout with 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, safe extraAs / intPathParam, breadcrumbs and browser tab titles.
  • Navigate from anywhere: PlayxNavigation.to, toNamed, offAll, offAndTo, popUntil, ... no BuildContext needed.
  • 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.

1
likes
150
points
779
downloads

Documentation

Documentation
API reference

Publisher

verified publisherplayx.sourcya.io

Weekly Downloads

Playx Navigation is a Flutter package that enhances app navigation with advanced features like route lifecycle management, custom transitions, and flexible configuration.

Homepage
Repository (GitHub)
View/report issues

Topics

#playx #navigation #deep-linking #go-router #route-management

License

MIT (license)

Dependencies

flutter, flutter_web_plugins, go_router

More

Packages that depend on playx_navigation