unrouter

• Declarative routes via Unrouter(routes: ...)
• Widget-scoped routes via the Routes widget
• Hybrid routing (declarative first, widget-scoped fallback)
• Nested routes + layouts (Outlet for declarative routes, Routes for widget-scoped)
• URL patterns: static, params (:id), optionals (?), wildcard (*)
• Browser-style navigation: push/replace/back/forward/go
• Async navigation results via Navigation (awaitable)
• Navigation guards with allow/cancel/redirect
• Route blockers for back/pop confirmation
• Navigator 1.0 compatibility for overlays and imperative APIs (enableNavigator1, default true)
• Web URL strategies: UrlStrategy.browser and UrlStrategy.hash
• Relative navigation with dot segment normalization (./, ../)

Add to pubspec.yaml:

dependencies:
  unrouter: ^0.3.0

Declarative routing setup:

import 'package:flutter/material.dart';
import 'package:unrouter/unrouter.dart';

final router = Unrouter(
  strategy: .browser,
  routes: const [
    Inlet(factory: HomePage.new),
    Inlet(path: 'about', factory: AboutPage.new),
    Inlet(
      factory: AuthLayout.new,
      children: [
        Inlet(path: 'login', factory: LoginPage.new),
        Inlet(path: 'register', factory: RegisterPage.new),
      ],
    ),
    Inlet(
      path: 'users',
      factory: UsersLayout.new,
      children: [
        Inlet(factory: UsersIndexPage.new),
        Inlet(path: ':id', factory: UserDetailPage.new),
      ],
    ),
    Inlet(path: '*', factory: NotFoundPage.new),
  ],
);

void main() => runApp(MaterialApp.router(routerConfig: router));

Use Unrouter directly as an entry widget (no MaterialApp required):

void main() => runApp(router);

Declarative routing (central config)

Unrouter(routes: [
  Inlet(factory: HomePage.new),
  Inlet(path: 'about', factory: AboutPage.new),
])

Widget-scoped routing (component-level)

Unrouter(child: Routes([
  Inlet(factory: HomePage.new),
  Inlet(path: 'about', factory: AboutPage.new),
]))

Hybrid routing (declarative first, widget-scoped fallback)

Unrouter(
  routes: [Inlet(path: 'admin', factory: AdminPage.new)],
  child: Routes([Inlet(factory: HomePage.new)]),
)

Hybrid routing also enables partial matches where a declarative route handles the prefix and a nested Routes widget handles the rest.

Declarative layouts use Outlet

Layout and nested routes defined in Unrouter.routes must render an Outlet to show matched children. Layout routes (path == '' with children) do not consume a path segment.

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

  @override
  Widget build(BuildContext context) {
    return const Scaffold(body: Outlet());
  }
}

Widget-scoped nesting uses Routes

class ProductsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Products')),
      body: Routes([
        Inlet(factory: ProductsList.new),
        Inlet(path: ':id', factory: ProductDetail.new),
        Inlet(path: 'new', factory: NewProduct.new),
      ]),
    );
  }
}

State preservation

unrouter keeps matched pages in an IndexedStack. Leaf routes are keyed by history index, while layout/nested routes are cached by route identity to keep their state when switching between children. Prefer const routes to maximize reuse.

Pattern syntax

• Static: about, users/profile
• Params: users/:id, :userId
• Optional: :lang?/about, users/:id/edit?
• Wildcard: files/*, *

Route kinds

• Index: path == '' and children.isEmpty
• Layout: path == '' and children.isNotEmpty (does not consume segments)
• Leaf: path != '' and children.isEmpty
• Nested: path != '' and children.isNotEmpty

Partial matching

Routes performs greedy matching and allows partial matches so nested component routes can continue to match the remaining path.

Imperative navigation (shared router instance)

router.navigate(.parse('/about'));
router.navigate(.parse('/login'), replace: true);
router.navigate.back();
router.navigate.forward();
router.navigate.go(-1);

Navigation results

All navigation methods return Future<Navigation>. You can ignore the result or await it when you need to know what happened.

final result = await router.navigate(.parse('/about'));
if (result case NavigationRedirected()) {
  // handle redirects
}

Navigation from any widget

context.navigate(.parse('/users/123'));
context.navigate(.parse('edit'));        // /users/123/edit
context.navigate(.parse('./edit'));      // /users/123/edit
context.navigate(.parse('../settings')); // /users/123/settings

Context extensions

context.navigate(.parse('/about'));
final router = context.router;

Relative navigation

Relative paths append to the current location and normalize dot segments. Query and fragment come from the provided URI and do not inherit.

Building paths

unrouter uses Uri as the first-class navigation input. You can build paths directly with templates or Uri helpers:

final id = '123';
final uri = Uri.parse('/users/$id');
final withQuery = Uri(path: '/users/$id', queryParameters: {'tab': 'profile'});
context.navigate(withQuery);

Guards let you intercept navigation and decide whether to allow, cancel, or redirect.

final router = Unrouter(
  routes: const [Inlet(factory: HomePage.new)],
  guards: [
    (context) {
      if (!auth.isSignedIn) {
        return GuardResult.redirect(Uri.parse('/login'));
      }
      return GuardResult.allow;
    },
  ],
);

You can also attach guards to specific declarative routes:

final routes = [
  Inlet(
    path: 'admin',
    guards: [
      (context) => GuardResult.redirect(Uri.parse('/login')),
    ],
    factory: AdminPage.new,
  ),
];

Guards run in order: global guards first, then matched route guards from root to leaf. The first non-allow result (cancel/redirect) short-circuits.

Guards receive a GuardContext:

• to: target RouteInformation
• from: previous RouteInformation
• replace: whether the navigation is a replace
• redirectCount: number of redirects so far

You can return a Future<GuardResult> for async checks, and configure maxRedirects to prevent redirect loops.

Route blockers intercept back/pop navigation (history go(-1) / back) and let you confirm before leaving the current route. They run from child to parent.

class SettingsPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return RouteBlocker(
      onWillPop: (ctx) async {
        final result = await showDialog<bool>(
          context: context,
          builder: (context) => AlertDialog(
            title: const Text('Discard changes?'),
            actions: [
              TextButton(
                onPressed: () => Navigator.of(context).pop(false),
                child: const Text('Cancel'),
              ),
              TextButton(
                onPressed: () => Navigator.of(context).pop(true),
                child: const Text('Discard'),
              ),
            ],
          ),
        );
        return result == true;
      },
      onBlocked: (ctx) {
        // Optional: record analytics or show a toast.
      },
      child: const SettingsForm(),
    );
  }
}

Notes:

• Blockers only apply to history back/pop (navigate.back() / navigate.go(-1)).
• navigate.go(0) also triggers blockers.
• forward does not trigger blockers.
• Navigator.pop is still handled by Flutter's WillPopScope/PopScope.

unrouter provides a per-route AnimationController you can use to animate incoming/outgoing pages without relying on Navigator 1.0.

class ProfilePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final animation = context.routeAnimation(
      duration: const Duration(milliseconds: 300),
    );
    return FadeTransition(
      opacity: animation,
      child: const Text('Profile'),
    );
  }
}

The controller runs forward on push/replace and reverse on pop. Pages that don't call routeAnimation behave as they do today. The default duration is 300ms unless you provide one.

By default, Unrouter embeds a Navigator so APIs like showDialog, showModalBottomSheet, showGeneralDialog, showMenu, and Navigator.push/pop/popUntil work as expected.

final router = Unrouter(
  enableNavigator1: true, // default
  routes: const [Inlet(factory: HomePage.new)],
);

Set enableNavigator1: false to keep the Navigator 2.0-only behavior.

final state = context.routeState;
final uri = state.location.uri;
final params = state.params;        // merged params up to this level
final extra = state.location.state; // history entry state (if any)

You can also read fine-grained fields (with narrower rebuild scopes):

final location = context.location;
final matched = context.matchedRoutes;
final params = context.params;
final level = context.routeLevel;
final index = context.historyIndex;
final action = context.historyAction;

RouteState.action tells you whether the current navigation was a push, replace, or pop, and historyIndex can be used to reason about stacked pages.

Basic link:

Link(
  to: Uri.parse('/about'),
  child: const Text('About'),
)

Custom link with builder:

Link(
  to: Uri.parse('/products/1'),
  state: {'source': 'home'},
  builder: (context, location, navigate) {
    return GestureDetector(
      onTap: () => navigate(),
      onLongPress: () => navigate(replace: true),
      child: Text('Product 1'),
    );
  },
)

• strategy: .browser uses path URLs like /about (requires server rewrites).
• strategy: .hash uses hash URLs like /#/about (no rewrites required).

UrlStrategy only applies to Flutter web. On native platforms (Android/iOS/macOS/Windows/Linux), Unrouter uses MemoryHistory by default. If you pass a custom history, strategy is ignored.

MemoryHistory makes routing tests easy:

final router = Unrouter(
  routes: const [
    Inlet(factory: HomePage.new),
    Inlet(path: 'about', factory: AboutPage.new),
  ],
  history: MemoryHistory(
    initialEntries: [RouteInformation(uri: Uri.parse('/about'))],
  ),
);

Run tests:

flutter test

• Unrouter: widget + RouterConfig<RouteInformation> (use directly or pass to MaterialApp.router)
• Inlet: route definition (index/layout/leaf/nested)
• Outlet: renders the next matched child route (declarative routes)
• Routes: widget-scoped route matcher
• Navigate: navigation interface (context.navigate)
• Navigation: async result returned by navigation methods
• Guard / GuardResult: navigation interception and redirects
• RouteState: current route state (read via context.routeState)
• History / MemoryHistory: injectable history (great for tests)
• Link: declarative navigation widget

See example/ for a complete Flutter app showcasing routing patterns and Navigator 1.0 APIs.

cd example
flutter run

• context.navigate throws: ensure your widget is under an Unrouter router (either MaterialApp.router(routerConfig: Unrouter(...)) or runApp(Unrouter(...))).
• Routes renders nothing: it must be a descendant of Unrouter.
• showDialog not working: keep enableNavigator1: true (default).
• Web 404 on refresh: use strategy: .hash or configure server rewrites.

• Format: dart format .
• Tests: flutter test
• Open a PR with a clear description and a focused diff

MIT - see LICENSE.