Skip to content

Routes and transitions

PlayxRoute

PlayxRoute<T> extends go_router's GoRoute. Everything GoRoute supports still works (path, name, parentNavigatorKey, redirect, onExit, nested routes); it adds lifecycle, state and web features.

PlayxRoute<JobDetailsController>(
  path: ':id',
  name: 'jobDetails',

  // Content: provide exactly one of builder / initBuilder.
  builder: (context, state) => const JobDetailsView(),

  // Lifecycle and state (all optional):
  binding: JobDetailsBinding(),
  controller: (context, state) => JobDetailsController(state.intPathParam('id')!),
  disposeController: (controller) => controller.onClose(),

  // Navigation behavior:
  transition: PlayxPageTransition.fade,
  pageConfiguration: const PlayxPageConfiguration(fullscreenDialog: true),
  guards: [const AuthGuard()],
  parentLocation: (state) => '/jobs',
  breadcrumb: (context, state) => 'Job #${state.pathParameters['id']}',

  // Loading behavior (see Page configuration):
  loadingWidget: const Center(child: CircularProgressIndicator()),
  shellBuilder: (context, state, isInitialized, child) => Scaffold(body: child),
  waitForBinding: false,
  initTransitionDuration: const Duration(milliseconds: 200),

  // Failures:
  errorBuilder: (context, state, error, stackTrace, retry) => ErrorView(onRetry: retry),
  enterTimeout: const Duration(seconds: 10),
)
Parameter Purpose Docs
builder / initBuilder Page content. initBuilder also receives isInitialized. Page configuration
binding Lifecycle callbacks, redirect, breadcrumb. Bindings
controller, disposeController One controller per page visit. Route controllers
transition, pageConfiguration How the page animates and behaves as a route. below
guards Redirect before the route is entered. Guards
parentLocation Where back() goes when nothing can be popped. Web
breadcrumb The route's breadcrumb label. Breadcrumbs
loadingWidget, shellBuilder, waitForBinding, initTransitionDuration Loading states. Page configuration
errorBuilder, enterTimeout Slow or failing page setup. Error handling

Exactly one of builder or initBuilder is required (asserted in debug mode).

Shell routes

PlayxShellBranch<T> is a StatefulShellBranch with one PlayxRoute inside. It takes the same parameters as PlayxRoute, so a tab and its child pages are easy to declare:

StatefulShellRoute.indexedStack(
  builder: (context, state, navigationShell) => AppScaffold(shell: navigationShell),
  branches: [
    PlayxShellBranch(
      path: '/jobs',
      name: 'jobs',
      breadcrumb: (context, state) => 'Jobs',
      builder: (context, state) => const JobsView(),
      binding: JobsBinding(),
      routes: [
        PlayxRoute(
          path: ':id',
          builder: (context, state) => const JobDetailsView(),
          binding: JobDetailsBinding(),
        ),
      ],
    ),
    PlayxShellBranch(
      path: '/settings',
      builder: (context, state) => const SettingsView(),
    ),
  ],
)

For a branch with several top-level routes use PlayxShellBranch.routes(routes: [...]). Branch constructor options such as navigatorKey, initialLocation, observers and preload are available too.

Switch tabs with PlayxNavigation.goToBranch(index: 1, navigationShell: shell). Pages in other branches stay alive and receive onHidden / onReEnter, never onExit (details).

Plain ShellRoute works as well: its pages are removed on navigation, so they exit normally.

Transitions

transition takes a PlayxPageTransition:

Value Effect
cupertino (default) iOS-style slide.
material Material page transition.
native Cupertino on iOS and macOS, Material elsewhere.
fade Cross-fade.
none No animation.
custom Your transitionsBuilder from PlayxPageConfiguration.customTransition.
PlayxRoute(
  path: '/details',
  transition: PlayxPageTransition.custom,
  pageConfiguration: PlayxPageConfiguration.customTransition(
    transitionsBuilder: (context, animation, secondaryAnimation, child) =>
        SlideTransition(
          position: Tween(begin: const Offset(0, 1), end: Offset.zero).animate(animation),
          child: child,
        ),
    transitionDuration: const Duration(milliseconds: 250),
    reverseTransitionDuration: const Duration(milliseconds: 200),
    opaque: true,
  ),
  builder: (context, state) => const DetailsPage(),
)

PlayxPageConfiguration

Field Meaning
key, name, arguments, restorationId Passed to the underlying Page. key defaults to the page key from go_router.
maintainState Keep the page built while it is covered (default true). If false, its widgets are disposed while covered, which ends its lifecycle (onHidden, onExit) and starts a new one (onEnter) when it is revealed again.
fullscreenDialog Present as a fullscreen dialog.
canPop, onPopInvoked Control and observe popping (PopScope-style).
transitionsBuilder, transitionDuration, reverseTransitionDuration Only for custom (and durations also for fade).
opaque, barrierDismissible, barrierColor, barrierLabel Route opacity and barrier for custom and fade.

Note

none ignores durations and barrier options. fade uses the configuration's durations.