AutoRoute Documentation

Nested navigation allows you to build an inner router inside a page of another router.

1. Define nested routes

In your AppRouter configuration, use the children property of an AutoRoute to define sub-routes.

2. Render the nested routes

To display the child routes, you must include an AutoRouter widget in the parent page's build method. This widget acts as an outlet where the child pages will be rendered.

3. Initial/Default child routes

To show a specific child route when the parent route is first accessed (e.g., at /dashboard), you can:

• Give the child an empty path: path: ''.
• Use a RedirectRoute to redirect the empty path to a specific child.

4. Shell Routes

A "Shell Route" is a page that contains an AutoRouter widget to render nested content. You can create one by:

• Extending AutoRouter directly.
• Using the EmptyShellRoute helper for routes that don't require code generation.

// 1. Configuration
@AutoRouterConfig(replaceInRouteName: 'Page,Route')
class AppRouter extends RootStackRouter {
  @override
  List<AutoRoute> get routes => [
    AutoRoute(
      path: '/dashboard',
      page: DashboardRoute.page,
      children: [
        AutoRoute(path: '', page: UsersRoute.page), // Initial child
        AutoRoute(path: 'posts', page: PostsRoute.page),
      ],
    ),
  ];
}

// 2. The Parent Page (Shell)
class DashboardPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        // ... navigation links ...
        Expanded(
          child: AutoRouter(), // The outlet for nested routes
        ),
      ],
    );
  }
}

// 3. Creating a Shell Route via extension
@RoutePage()
class MyShellPage extends AutoRouter {
   const MyShellPage({Key? key}) : super(key: key);
}

// 4. Creating a Shell Route without code generation
const BooksTab = EmptyShellRoute('BooksTab');
context.push(BooksTab());

If a user's authentication state changes while they are already on a private page, you need the router to re-evaluate the stack. This is achieved using the reevaluateListenable property in router.config.

1. Create a Listenable (e.g., a ChangeNotifier) that notifies when the state changes.
2. Pass it to router.config(reevaluateListenable: yourListenable).
3. When the listenable notifies, AutoRouteGuard.onNavigation() will be re-called for all guards.

Note on Re-evaluation: When the stack is re-evaluated, the entire hierarchy is re-pushed. To prevent continuous re-pushing after a successful login/action, use resolver.resolveNext(bool, reevaluateNext: false) instead of resolver.next().

// 1. Define a listenable
class AuthProvider extends ChangeNotifier {
  bool _isLoggedIn = false;
  void login() { _isLoggedIn = true; notifyListeners(); }
}

// 2. Pass to router config
MaterialApp.router(
  routerConfig: _appRouter.config(
    reevaluateListenable: authProvider,
  ),
);

// 3. Use resolveNext to stop re-evaluation loop
@override
void onNavigation(NavigationResolver resolver, StackRouter router) async {
  if (authProvider.isAuthenticated) {
    resolver.next();
  } else {
    resolver.redirectUntil(
      WebLoginRoute(onResult: (didLogin) {
        resolver.resolveNext(didLogin, reevaluateNext: false);
      }),
    );
  }
}

For mobile applications requiring tabbed navigation, use AutoTabsRouter. Unlike a standard AutoRouter (which is a shortcut for AutoStackRouter and manages a stack of pages), AutoTabsRouter preserves the state of offstage routes and allows for custom transition animations.

By default, tab routes are lazily loaded, though this can be disabled. You can use the builder property to access the TabsRouter controller via AutoTabsRouter.of(context) to manage the active index.

class DashboardPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AutoTabsRouter(
      // list of your tab routes
      // routes used here must be declared as children
      routes: const [
        UsersRoute(),
        PostsRoute(),
        SettingsRoute(),
      ],
      transitionBuilder: (context,child,animation) => FadeTransition(
            opacity: animation,
            child: child,
          ),
      builder: (context, child) {
        final tabsRouter = AutoTabsRouter.of(context);
        return Scaffold(
          body: child,
          bottomNavigationBar: BottomNavigationBar(
            currentIndex: tabsRouter.activeIndex,
            onTap: (index) {
              tabsRouter.setActiveIndex(index);
            },
            items: [
              BottomNavigationBarItem(label: 'Users', ...),
              BottomNavigationBarItem(label: 'Posts', ...),
              BottomNavigationBarItem(label: 'Settings', ...),
            ],
          ),
        );
      },
    );
  }
}

You can use specialized constructors for AutoTabsRouter to integrate with Flutter's PageView or TabBar widgets:

• AutoTabsRouter.pageView: Provides a controller in the builder to sync with a PageView.
• AutoTabsRouter.tabBar: Provides a controller in the builder to sync with a TabBar.

// Using PageView
AutoTabsRouter.pageView(
  routes: [
    BooksTab(),
    ProfileTab(),
    SettingsTab(),
  ],
  builder: (context, child, _) {
    final tabsRouter = AutoTabsRouter.of(context);
    return Scaffold(
      body: child,
      bottomNavigationBar: BottomNavigationBar(
        currentIndex: tabsRouter.activeIndex,
        onTap: tabsRouter.setActiveIndex,
        items: [...],
      ),
    );
  },
);

// Using TabBar
AutoTabsRouter.tabBar(
  routes: [
    BooksTab(),
    ProfileTab(),
    SettingsTab(),
  ],
  builder: (context, child, controller) {
    final tabsRouter = AutoTabsRouter.of(context);
    return Scaffold(
      appBar: AppBar(
        bottom: TabBar(
          controller: controller,
          tabs: const [
            Tab(text: '1', icon: Icon(Icons.abc)),
            Tab(text: '2', icon: Icon(Icons.abc)),
            Tab(text: '3', icon: Icon(Icons.abc)),
          ],
        ),
      ),
      body: child,
    );
  },
);

You can use AutoRoute without code generation by using NamedRouteDef. This allows you to provide an inline page builder function instead of a generated page. You must provide a name for the route to enable navigation by name or path.

Declaring Named Routes

You can use NamedRouteDef or the shorthand .named() extension on the routes list.

Navigating to Named Routes

Navigate using the NamedRoute class to match by name, or use pushPath, replacePath, or navigatePath to match by path string.

// Declaring routes
routes: [
  .named('HomeRoute', (ctx, data) => HomePage()),
  NamedRouteDef(
    name: 'BookDetailsRoute',
    path: '/books/:id',
    builder: (context, data) {
      return BookDetailsPage(id: data.params.getInt('id'));
    },
  ),
];

// Navigating by name
router.push(NamedRoute('BookDetailsRoute', params: {'id': 1}));
router.push(.named('BookDetailsRoute', params: {'id': 1}));

// Navigating by path
router.pushPath('/books/1');