Skip to content

Installation and setup

Install

dependencies:
  playx_navigation: ^3.0.0
flutter pub get

playx_navigation re-exports go_router, so a single import gives you both:

import 'package:playx_navigation/playx_navigation.dart';

1. Define route names and paths (optional)

abstract class Routes {
  static const home = 'home';
  static const products = 'products';
  static const productDetails = 'productDetails';
}

abstract class Paths {
  static const home = '/home';
  static const products = '/products';
  static const productDetails = ':id'; // relative: /products/:id
}

2. Create bindings

A binding attaches logic to a route's lifecycle. onEnter is the only method you must implement; the rest are optional. See Bindings and lifecycle for the full contract.

class ProductsBinding extends PlayxBinding {
  @override
  Future<void> onInitApp() async {
    // Once, at boot, before any page is entered: register repositories, services...
  }

  @override
  Future<void> onEnter(BuildContext context, GoRouterState state) async {
    // The page is about to be shown for the first time: load data, create controllers.
  }

  @override
  Future<void> onExit(BuildContext context) async {
    // The page was removed: release resources.
  }
}

No binding needed?

For a page that only needs one controller you can skip the binding entirely and use a route controller. See Choosing an approach.

3. Build the router with PlayxRoute

PlayxRoute extends go_router's GoRoute, so it works anywhere a GoRoute does (including inside StatefulShellRoute and ShellRoute).

final router = GoRouter(
  initialLocation: Paths.home,
  routes: [
    PlayxRoute(
      path: Paths.home,
      name: Routes.home,
      builder: (context, state) => const HomePage(),
      binding: HomeBinding(),
    ),
    PlayxRoute(
      path: Paths.products,
      name: Routes.products,
      builder: (context, state) => const ProductsPage(),
      binding: ProductsBinding(),
      routes: [
        PlayxRoute(
          path: Paths.productDetails,
          name: Routes.productDetails,
          builder: (context, state) =>
              ProductDetailsPage(product: state.extraAs<Product>()),
          binding: ProductDetailsBinding(),
        ),
      ],
    ),
  ],
);

4. Wrap your app in PlayxNavigationBuilder

PlayxNavigationBuilder boots the navigation system: it finds every binding in the route tree, runs each onInitApp, and provides global configuration to the pages.

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return PlayxNavigationBuilder(
      router: router,
      config: const PlayxPageConfig(
        loadingWidget: Center(child: CircularProgressIndicator()),
      ),
      builder: (context) => MaterialApp.router(routerConfig: router),
    );
  }
}

Booting without the widget

You can call await PlayxNavigation.boot(router: router) yourself (for example before runApp) and omit router: from the builder. await PlayxNavigation.ensureInitialized completes once every onInitApp has finished.

5. Navigate from anywhere

PlayxNavigation.toNamed(Routes.productDetails,
    pathParameters: {'id': '5'}, extra: product);
PlayxNavigation.back();

No BuildContext is needed. See the PlayxNavigation API.

Web setup

Call this before runApp to use path URLs and have the browser URL reflect push:

void main() {
  PlayxNavigation.setupWeb();
  runApp(const MyApp());
}

See Web for refresh, deep links, back buttons and tab titles.