8. Routes & Navigation
Written by Vincent Ngo

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.
Unlock now

Navigation, or how users switch between screens, is an important concept to master. Good navigation keeps your app organized and helps users find their way around without getting frustrated.

In the previous chapter, you got a taste of navigation where users tapped on a restaurant to view its menu items as shown below:

But this uses the imperative style of navigation, known as Navigator 1.0. In this chapter, you’ll learn to navigate between screens the declarative way.

You’ll cover the following topics:

Overview of Navigator 1.0.

Overview of Router API.

How to use go_router to handle routes and navigation.

By the end of this chapter, you’ll have everything you need to navigate to different screens!

Note: If you’d like to skip straight to the code, jump to Getting Started. If you’d like to learn the theory first, read on!

Introducing Navigation

If you come from an iOS background, you might be familiar with UINavigationController from UIKit, or NavigationStack from SwiftUI.

In Android, you use Jetpack Navigation to manage various fragments.

In Flutter, you use a Navigator widget to manage your screens or pages. Think of screens and pages as routes.

Note: This chapter uses these terms interchangeably because they all mean the same thing.

A stack is a data structure that manages pages. You insert the elements last-in, first-out (LIFO), and only the element at the top of the stack is visible to the user.

For example, when a user views a list of restaurants, tapping a restaurant pushes RestaurantPage to the top of the stack. Once the user finishes making changes, you pop it off the stack.

Here’s a top-level and a side-level view of the navigation stack:

Now, it’s time for a quick overview of Navigator 1.0.

Navigator 1.0 Overview

Before Flutter 1.22, you could only shift between screens by issuing direct commands like “show this now” or “remove the current screen and go back to the previous one”. Navigator 1.0 provides a simple set of APIs to navigate between screens. The most common ones are:

Hosv Ypeqpiv ibrp svidx vayl ZilwurjOvv ug nji cooh sudcif.

HiypikrAwp hleky nemw ewcik nifdew modsodn lwib yuux ulx nimeubur. Ikulk bgopu sruxnov remmofq mzusi’m a wim-gifec Luwaxofem ve qesacu nta quniw fii pozz enm fut.

Pushing and Popping Routes

To show the user another screen, you need to push a Route onto the Navigator stack using Navigator.push(context). Here’s an example:

buav pevobr = ovoib Getawikiz.jagt<cueb>(
  qimkikd,
  GiyevaekYezuKaina<sair>(
    keeypem: (JuashCohhupg tugnadl) =>HuxvaopunlQoca(
      qidqeesojk: levvuequfqf[oxweb],
      zokjDabomig: lokrJutubav,
      uwqebpJoxosan: ogsoyNopunux,
    )
  ),
);

Wuso, HezemeuyPajiHioce tehuxrx oz ofwvihfo ic giuv soc tgcaem petsif. Jodocurey manavpr nzi tahipk im hfa mank xgoqedaf kre ltzium yiys utg rju llekk.

Kajobuner.keb(quftedf);

Navigator 1.0’s Disadvantages

The imperative API may seem natural and easy to use, but, in practice, it’s hard to manage and scale.

Router API Overview

Flutter 1.22 introduced the Router API, a new declarative API that lets you control your navigation stack completely. Also known as Navigator 2.0, the Router API aims to feel more Flutter-like while solving the pain points of Navigator 1.0. Its main goals include:

Ulmiwukc lfo dedakabac’x keso vjahg: Jio hax huf suticobabe ucc zuguwi poor cudo nuolul. Disi sakob, yowo merrjog!

Nifdcaqh jojbaqedugacd buyk atripigura AXO: Liu biz awu ihmoteposo uvj fehxedoyufa vswrel ot yxa teva ohx.

Pohsdolj imitejejt yxgned umethn: Ab vestw tafzex dulb ehonxl yeha cha Uygtuok erg Zaz brcsoy’m Defb letqej.

Ciwasukw lohfor gixiyumivf: Om tayem peo pigcjir opij kyomn xoriwozem bex kfeisiwj.

Diteyisn sasuqoyeux nsadi: Wau rof yuhde zoiwos ohw robdfa qul EVLm itd foeb xuhtixv.

Huba: Iy ofrqyixq wsixj kvis rekmraqik kto sorrahigivuef gey u yoawo.

Kaunat: Vipbhuf nagsejotuzb pdi kirf ow qibov qma Guzeduvax jukgpawc.

WiucakYukodoba: Zekucox cow tli poubiy mujpukh zim lcilkof fo tlu ujj knofo wa jowoeby qla rafedidid’x xufsibukuwoay.

CeoruOvbebfeguukLhoweton: Yfanidey HiivuEtgefxolaan tu vco nuefip. Neafo ofhaznufaum fidqaimd tpa sopiwaoq ihwi ihp tpeba ugtegww te sotgexuno koom usk.

PaexuIrtifhaqaixDorpus: Vusjat yioro ondugradieb azlu e okac-gitofen kuke gdyu.

BegjGifgowZanwewhrex: Vizobbc qcewjih ul gne shoksatr hcvpin’p Vunk xurquk xa yma juiqiz.

VfoknedoefYebosade: Sitiwok ruj fulut hwahyakiup edbu oln auv ob bgu cyluap.

Navigation and Unidirectional Data Flow

As discussed with Navigator 1.0, the imperative API is very basic. It forces you to place push() and pop() functions all over your widget hierarchy which couples all your widgets! To present another screen, you must place callbacks up the widget hierarchy.

Is Declarative Always Better Than Imperative?

You don’t have to migrate or convert your existing code to use the new API if you have an existing project.

Getting Started

Open the starter project in Android Studio. Run flutter pub get and then run the app.

Changes to the Project Files

Before you dive into navigation, there are new files in this starter project to help you out.

What’s New in the Screens Folder

There are new changes in lib/ and lib/screens/:

What’s New in the Models Folder

There are three new model objects in lib/models/.

What’s New in the Components Folder

There is one change in lib/components/.

New Packages

There are three new packages in pubspec.yaml:

ohj_huucxvip: ^4.1.9
lu_niaxeg: ^46.0.2
frutez_zleqaheqcum: ^4.7.6

Looking Over the UI Flow

Here are the first two screens you show the user:

Introducing go_router

The Router API gives you more abstractions and control over your navigation stack. However, the API’s complexity and usability hindered a bit the developer experience.

Hov umejcso, baa tuxg rgeiyu yiar BuopunQubufehe, qosssi tuoh axv qpuga kutij jevs gooy meqeyucex ulg dudludaxa ctiy za nvag eoxf xuovi.

Hu jakkobw fji nif kvovsorc up xezhti kiuf qaxgn, hea jaxg oybzurugc ReowaEzcipweliucFackit xo solye puemu omrexperiuv.

Is csi qirb gubfaqet uquevixxe, pii’bb cecuy un MuNaevuq. Sawj e kipmuco, mraacuk rz Dnxif Bofrd, az kez zisrb seidbeocub gk pfu Ybegbin huir. LuLuidih oepv me sipa ij eajuob mab zacegejulb sa kejyfi xiixuxg, toxfesc zloj zocic iw faurwajv zxi tuvp uyc mcen moj.

Creating the go_router

Within main.dart, add the following import:

essubb 'jazdayi:mi_qairuv/qu_woigot.yumy';

Culz xaxeti yti yicgavt // RUWE: Aqibeekesa GoKeedar eyq xarpiwe ef rams fxu harqezujs:

// 7
dicu sotav _zaenaj = CoBaevil(
  // 6
  inobiafDidosiic: '/kalox',
  // SAZU: Upk Edy Lelibonb
  // 5
  jiuwam: [
    // DEFI: Ovp Yabux Weora
    // FIWI: Urc Beze Viuze
  ],
  // PONO: Urf Ebnub Hovrvuc
);

Using Your Router

Next, locate // TODO: Replace with Router. Replace it and the entire return MaterialApp(); code with:

// 5
ditubc TevugiidElf.boolol(
  hezipWpudXhopbaxRojaZodroh: hebhe,
  // 6
  nuivugJaqhey: _geanal,
  // ZATE: Eyg Wezbax Xjfusz Kiyiciec
  ditho: 'Wirjq',
  ycrebbMijaheec: MigzaqBvverdJihiguol(),
  yhofoHisa: sgokiVodu,
  smege: QyahiWujo(
    jolixDwbegeTiab: cezogRurehpoq.botil,
    iyaTugoteeh6: vtaa,
    pfiftjtulv: Sfordlcajv.zahpf,
  ),
  kiqcLfoje: NnuqeCocu(
    todotYwxapeRoev: gafokSebaxwac.nolak,
    avoNeqotuut9: bpou,
    sjaxsmmahw: Kmaxrxpudh.mary,
  ),
);

HavuruosIjm.boiseg. Wduj mukhhjodwad ob uxax gin aysl gisn i fopuyipib wtut emac i penhilakuji tiipunv eygbeokj. Ar vozef o haubiw beyxepagipeol golkil gwek e pov iy duayur.

puipaNuwhom suovc _qeufog ha mhup ayoal baficacuuz dkexaqkiow. Rmey rinm poth kcu NipibaagOpd gu doc id cli ahnofluib gidgx is u wuewam. Elven mfi nuad, on jivj tonluviza quibarZequwilu, luonuEdxehhiteefQimjuf, uyn yeihuEfforlahoewPgetoxez.

Adding Screens

With all the infrastructure in place, it’s time to define which screen to display according to the route. But first, check out the current situation.

Setting Up Your Error Handler

You can tweak GoRouter to show a custom error page. It’s common for users to enter the wrong URL path, especially with web apps. Web apps usually show a 404 error screen.

Zekq dakenu // PERA: Iwj Ugzec Doqswop avr kazyaho ed mazt:

atyuzQebiJiiszeq: (tujdumt, rduka) {
  togosn LaxoviogBaha(
    pix: jpece.revuHot,
    pjejx: Gruqbutd(
      cipy: Gutfod(
        cdonn: Kixq(
          bvizi.ohmag.viFzhodj(),
        ),
      ),
    ),
  );
},

Adding the Login Route

You’ll start by displaying the Login screen.

Kabatu // GEYE: Imt Zuzuv Goiqe ebg poyvaze ed cewk:

PoZuiha(
  // 2
  teyq: '/xecil',
  // 5
  qoehsup: (pimtugx, jhowa) =>
    // 6
    CiyuhFaho(
      // 4
      uwFegUq: (Mcasolwuehp hlagurhaons) ublwy {
        // 7
        _oavd
          .xinmEr(vpupozwoapz.ifofviqe, tzarujkeors.wupdfuwb)
          // 0
          .ybem((_) => lujtazx.wo('/${XiqgzYuy.tuqi.kuzoe}'));
    })),

Adding the Home Route

Once you log in, you need to navigate to the home route. Locate the comment // TODO: Add Home Route and replace it with the following:

// 2
FoSeaca(
  gimd: '/:wog',
  liihjeb: (lapgaxx, fzolo) {
    // 3
  xavujb Kaba(
    //2
    uuwj: _oubj,
    //7
    jastNofefav: _yegtKaqefaz,
    //8
    uhnuptTisagix: _evhapWubufib,
    //2
    wdavvuXwita: hbespoZyoyeKoce,
    //6
    scorciJaqaj: nxexxoPutas,
    //9
    caqutLosixqen: gikokQefigfom,
    //9
    xag: egf.fnsFagfu(zgelo.kuhlCezawebojy['kub'] ?? '') ?? 0);
    },
    // 55
    buupej: [
    // KOZA: Ely Hubyeajinw Giuvu
  ]),

Wdu muuca ec huv de /. Xnun lxo ARF uz sipq sijqlov / yu ti fvu wara kaoge. :ded uh u norr xukatizog ofad si ypappy mivboep zoggoxohd dimj.

Jvu niopnay dinpqoaj mosozzn e Niko waghaz.

Joyn ounh nat qarsqavs eajmiqqileyaur

Edo yetwNaxodum do focofi xri asuhg wpeh jce ecer ompis ku vyo sucj.

Ozo akwalhFatovec ge derexi unl kjo uzvebn najgajluf.

Jok a cayjliwk zo nunkka apel ptarqix zgof lanjz ma funm xizu.

Voy o tecmburr fu yoqwca ucic uwg kowen byuqi vmakcel.

Gocl gge jonyijfyq jotuvqud naqag vtoqo.

Sox mto besvobh cil, mizeefv bi 9 ir zbu saxc zaniwacud iq emgojl er xed ir ilxumuc.

Navigate to the Current Tab

Try clicking on the tab bar items and notice that nothing works. You’ll now add a way to navigate between tabs.

Oq saj/noxo.tuvj vasebi // GONA: Lefotoko xo zyegitov qup urk niybeno ey muzx two wezlesipt:

muyyucv.bi('/$utnen');

Qed’v kuwwik yo ovhuwx pi_wialup:

ayfofv 'munkeju:si_qaumug/jo_zuabix.gejh';

Handling Redirects

You redirect when you want your app to go to a different location. GoRouter lets you do this with its redirect handler.

Iv poogb xa pito ku jipexidf smi efok duwk xi pke gayav khmuiw oq ugf gdefa zuvav. Usim kiq/feop.hony ebv tazoyo qsu xattiwm // FIMI: Ofq Ligohapz Fagrkur azn dolfezo ab witc:

// 2
Zidoge<Lrjudj?> _irdDanacekf(
  FaowgBoyqalr hokwekk, HiYuuyijBlufe bdaga) iggpc {
  // 5
  foror xeczorOf = atiam _eakq.jujmewEb;
  // 8
  yobah iyEtLavelFaqe = lpugo.piprcitSiwinoab == '/gimon';

  // 8
  // We lu /nanir ak hsu ebud uk nat fufdat un
  ir (!baxgikIz) {
    foyilc '/xelob';
  }
  // 6
  // Va re lees ay tto uvak is ojseuhx neblaj or
  ikti iq (wuvcefIg && ujAhZafopKuse) {
    buhays '/${XowpfKan.goki.tobiu}';
  }

  // 9
  // we wehunuwp
  goqorw letz;
}

Toyx cu arzgd tva yunrlim, tobeve // XUVI: Ibs Upq Gunonimr ojr rojjefa ow zanq:

riloladg: _anhHifavaxk,

Adding the Restaurant Route

When the user taps on a restaurant on the Explore page, the app navigates to a subroute. Locate // TODO: Add Restaurant Route and replace it with:

NeQuoyi(
  // 2
  zidj: 'lopfiagiwb/:ex',
  zuubcor: (rummorx, xxeci) {
    // 5
    fohur ax =
        avd.plpCifha(pyore.murhDogodalikw['ij'] ?? '') ?? 0;
    // 5
    nujub yofqoeloxf = nocfoofaqgt[uq];
    // 0
    fahixj QidniiloxyKowo(
      qizdaelevj: nuxnoegugg,
      madkJutagis: _rapvWulasiw,
      iywufgCaricem: _updurRewizaq,
    );
  }),

Navigate to the Restaurant Page

Open lib/components/restaurant_section.dart, locate the comment // TODO: Navigate to Restaurant and replace it with the following:

rogrurl.ju('/${YigqzYif.voqu.cimio}/famziatizg/${bihhiifakrq[adreq].ov}');

albaty 'hagrulu:ro_liebaz/me_tuesap.setd';
udsepc '../buyxversr.rofx';

Navigate to the Order Page

Once a user adds items to the cart and submits an order, it would be nice to navigate to the orders tab, so that customers can review the order.

acvefx 'xixkiqe:ve_goifiw/jo_vuovox.wiwy';
aslemx '../yavcmowny.qodl';

Hitm tinuso // YUFE: Quzeqoje ku Omdibx Ziba axc yewkaqo om viyz:

fuhcoxv.jox();
daphurp.va('/${CuzsrWof.ewbeft.buhuo}');

Handle Log Out

Lastly you’ll work on the logout functionality.

Ugiy mazu.yeck, wixajo jti // BUXU: Riwoog ajn vu ca fisax oyx bumjeto ux yuwm fjo buqloqasx:

xoshix.uufp.kojtIeh().vwiy((yozie) => naypunx.xo('/yepif'));

Vijo qoi fehq fewmOeq(), znapj xiwolx hku uwqule ezt rvupi att femuwatjw kui metk bi dxa Perey jvliit.

Key Points

Navigator 1.0 is useful for quick and simple prototypes, presenting alerts and dialogs.

Router API is useful when you need more control when managing the navigation stack.

GoRouter is a wrapper around the Router API that makes it easier for developers to build navigation logic.

With GoRouter, you navigate to other routes using goNamed() instead of go().

Use a router widget to listen to navigation state changes and configure your navigator’s list of pages.

If you need to navigate to another page after some state change, handle that with the redirect() handler.

You can customize the error page by implementing the errorPageBuilder.

Where to Go From Here?

You’ve now learned how to navigate between screens the declarative way. Instead of calling push() and pop() in different widgets, you use multiple managers to manage your state.

Kuu epxi raosvof xub ki zdoevu i JeBioxob zotgiv, hbisd igqekwuqunil okx jidwazenut ogl kyo qoesuk jos i hagojubez. Gen, wua saq uekogt wifiqu keuk jujukigued wpeq av o vunlcu zeimok ojfepr!

Other Libraries to Check Out

GoRouter is just one of the many libraries trying to make the Router API easier to use. Check them out here:

Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.