Flutter ZERO Boilerplate Router with Auto Route – Flutter Navigation Tutorial


Navigation and routing take just too much code and effort to implement. No matter if you implement a router yourself or you use a library like fluro or sailor, there's still a lot of boilerplate. All of this changes with the auto_route package which works elegantly by code generation. This way, you can reduce repetitive and error-prone code to a minimum while still having the ability to customize the routes to your heart's content.

What we will build

The starter project contains the individual page widgets already pre-built so that we can focus purely on navigation. At the end of this tutorial, we'll have an app with three routes, custom route arguments and custom transitions.

Adding dependencies

To follow along with this tutorial, use the same versions of the packages to make sure we're on the same page.


    sdk: flutter
  auto_route: ^0.2.1

    sdk: flutter
  auto_route_generator: ^0.2.1+3

The Router class

The center point of navigation with the auto_route library is a class annotated with @autoRouter. In its simplest yet fully functional form, the router class takes only a few lines of code.


class $Router {
  InitialPage initialPage;
  SecondPage secondPage;
  ThirdPage thirdPage;
There is no part 'router.g.dart'; statement as you might be used to from other code gen packages. That's because the generated classes don't use the any members of our manually written class, hence, the generated file is not a "part" of the manually written file.

While even this simplest will work perfectly fine for basic routing, we can make the generated name of the InitialPage be a slash '/' as usual by annotating it with @initial.


class $Router {
  InitialPage initialPage;
  SecondPage secondPage;
  ThirdPage thirdPage;

After running every Flutter developer's favorite command, we'll have a generated router.gr.dart file.

?‍? terminal

flutter pub run build_runner watch --delete-conflicting-outputs

Plugging the Router into Flutter

The generated class contains three main things:

  • names of the routes as constant strings
  • onGenerateRoute method which handles navigation arguments out of the box (more on that below)
  • a navigatorKey & navigator properties used for navigating without passing around the BuildContext

Let's plug this all into the MaterialApp or CupertinoApp widget.


class MyApp extends StatelessWidget {
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Material App',
      initialRoute: Router.initialPage,
      onGenerateRoute: Router.onGenerateRoute,
      navigatorKey: Router.navigatorKey,
Notice that we're not using the $Router class which we've defined ourselves. Always use the generated class without the dollar sign.

Single-argument routes ☝

The SecondPage widget takes in a single argument into its constructor


class SecondPage extends StatelessWidget {
  final String userId;

  const SecondPage({@required this.userId});

When auto_route sees a single-parameter constructor, it will make sure that the passed-in argument present and that it is of the correct type. Since auto_route uses the default navigator API with named routes, passing arguments to a new route uses the arguments parameter of the pushNamed method. Let's add the navigation code to the "Go to SECOND" button callback inside initial_page.dart!


void navigateToSecond(BuildContext context) {
  Router.navigator.pushNamed(Router.secondPage, arguments: 'unique_user_id');

We can easily navigate without passing in the BuildContext by the virtue of the navigatorKey which we specified in main.dart. Additionally, if we pass in an argument of a wrong type or we leave it out completely, a prominent error page will be displayed.

Oh no! Argument mistype.
Should the constructor parameter not be marked @required, leaving out arguments completely wouldn't be an issue. Type checking would still occur though, which is good.

Multi-argument routes ?

The ThirdPage takes in two arguments:


class ThirdPage extends StatelessWidget {
  final String userName;
  final int points;

  const ThirdPage({
    @required this.userName,
    @required this.points,

Will we be forced to use a Map<String, dynamic> by the auto_route package? ?

Nope! ? The package will generate a ThirdPageArguments class honoring any @required annotations or default values there may be in the constructor. Now we can navigate to the third page from initial_page.dart.


void navigateToThird(BuildContext context) {
    arguments: ThirdPageArguments(points: 123, userName: 'Bob'),

ThirdPageArguments is the only type accepted by the generated Router. Passing in anything else will result in an error.

As soon as one page constructor parameter is marked @required, not passing in the generated 'PageName'Arguments object will result in an error.

Customizing routes

Our $Router class is currently pretty lean.


class $Router {
  InitialPage initialPage;
  SecondPage secondPage;
  ThirdPage thirdPage;

Navigating to any of the routes is equivalent to instantiating the simplest MaterialPageRoute without any additional configuration. Let's change that!

Passing in custom arguments, for example the fullscreenDialog boolean, is possible with @MaterialRoute or @CupertinoRoute annotations. The following will make the SecondPage appear with a cross instead of the back arrow in the AppBar.


@MaterialRoute(fullscreenDialog: true)
SecondPage secondPage;

Should you want to use neither material design nor cupertino for your routes, you can annotate the route with @CustomRoute which instantiates a PageRouteBuilder behind the scenes. Among other things, this allows you to specify custom transitions.


  transitionsBuilder: TransitionsBuilders.zoomIn,
  durationInMilliseconds: 200,
ThirdPage thirdPage;

TransitionsBuilders comes from auto_route and it has a bunch of functions pre-defined. You can also create your own transition animations by using the default functions as a template.

Learn more about custom transitions and other features of auto_route which you may not use on a daily basis, but that are still useful from the well-written official docs.

It's truly invigorating to see the whole Flutter package ecosystem become more mature. The auto_route package surely contributes a ton to developer productivity and happiness since handling routing manually is a toilsome endeavor. Be sure to show the author, Milad Akarie, some support by giving this package a like on pub.dev and a star on GitHub!

About the author 

Matt Rešetár

Matt is an app developer with a knack for teaching others. Working as a freelancer and most importantly developer educator, he is set on helping other people succeed in their Flutter app development career.

You may also like

  • It seems like CustomRoute’s usefulness is limited by its transitions builder’s signature – so this doesn’t allow for animations to the “previous route” when navigating to a new route.

    Unless I am missing something, it seems like this package doesn’t support transitions like “make OldPage exit left while NewPage enters from the right”.

  • thanks for yet another great Flutter tutorial ! are you able to add a segment showing how it could be used to maintain navigation state when using a bottom nav bar ?

  • Great tutorial, Matt! I’m playing with RouteGuard but I’m in a bit of a dilemma: in the documentation it says that the main() method is a good place to register RouteGuards but my RouteGuard class depends on an object that Provider instantiates inside MyApp widget, so when my RouteGuard object is instantiated Provider.of cannot find the dependency yet and an error is thrown. I tried to instantiate my Provider before runApp(MyApp()) but I get all sort of errors. Am I making sense?

  • currently (as of May 2020) , auto route doesn’t support generating route class parameters that are functions (callbacks functions) .

    Am i right ?

  • Can the initial page be changed? like I want to show a welcome screen as initial page for the first time only when he / she opens the app.

  • Hii,
    I am currently using flutter and trying to create a responsive web ui. I watched your tutorial on the named Routes and onGenerate I followed it and then implemented all that taught in the video for the desktop layout and it worked great but not on the same for mobile layout. But my question to you is ….can I use the same onGenerate class again for the mobile layout too if yes then how??? and what is the use of global key here.Sorry if am being rude.
    thank you

  • Hi resocoder, very nice tutorial, but it seems that auto_route library has changed a lot over time with many additional supports such as extendedNavigator, route guard and many more things. Please make a newer tutorial for that

  • Hi Matt ! I am using Firebase FireAth and Firestore, My pattern is your teach DDD, my user must have others field such firstname, lastname and others, for edit these informamtions I create an EditFormPage with constructor argument, but for naviging to this page I must provide user object who is connected. Here is my problem. Can you help me ? Please !

  • {"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}