Navigator, Routes and Deep Links

"Every day is a journey, and the journey itself is home." — Matsuo Bashō, The Narrow Road to the Deep North (1694)

Navigation is the first place where a Flutter app stops being a self-contained widget tree and starts having to agree with the outside world. Until now, every chapter has concerned state the app owns entirely. A route stack is different: the operating system has opinions about it, the back button belongs to the platform, and on the web the address bar is a live, user-editable view of it.

That is the real subject of this chapter. Navigator.push is easy and you already know it. What is worth understanding is the shift from navigation as a sequence of actions to navigation as a value you can name — because every hard requirement in this area, deep links included, turns out to be a demand that your navigation be the second kind.

The stack, and what stays alive

Navigator is a stack of Route objects, and pushing one is exactly what it sounds like. What is less obvious is what happens to the page underneath, and the answer matters for both correctness and performance.

Measured, with pages that log their own lifecycle, pushing B on top of A and then popping:

after push B: [B initState, B build]
after pop:    [B dispose]

Two absences carry the information.

A did not rebuild when it was covered. It is still mounted, its State intact, its scroll positions and controllers alive. The new route was placed above it in an Overlay, and Flutter did not disturb it.

A did not rebuild when B popped, either. Returning to a page does not re-run its build. If you expected a screen to refresh itself when the user comes back — a list that should show a newly-created item — nothing will happen unless you arrange it, because from A's point of view nothing occurred.

That second point is the source of a very common bug report: "the list doesn't update after I add an item". The fix is to await the push and act on the result, which the next section covers.

The default is configurable. MaterialPageRoute takes maintainState, and it governs the route it is set on — whether that route's subtree survives being covered by another. Measured, covering a middle route with a third:

MID maintainState=true,  after covering it: [TOP initState, TOP build]
MID maintainState=false, after covering it: [TOP initState, TOP build, MID dispose]

With maintainState: false, the covered route is disposed and will be rebuilt from scratch when revealed. That is worth doing for a memory-heavy screen you do not mind rebuilding, and worth avoiding for anything holding scroll position or unsaved input.

The trade is easiest to feel with something stateful on the covered page. A scroll position and a counter survive one setting and are lost under the other:

Replacing rather than stacking

Not every transition should deepen the stack. Finishing a login should not leave the login screen behind the app for the back button to reveal, and pushReplacement is the operation for that. Measured:

at root, canPop=false
after push, canPop=true
pushReplacement: [C initState, C build, B dispose]
canPop still=true

Two details worth noting. The replacement is built before the old route is disposed — C initState, C build, then B dispose — so the new page is ready before the old one goes, and a transition can run between them. And canPop remained true, because replacing the top of a three-deep stack still leaves something beneath it; pushReplacement swaps one entry, it does not flatten the stack.

canPop itself is the honest way to decide whether to draw a back affordance. At the root it is false, which is why a root page should not show one — and why Scaffold omits the automatic back arrow there without being told to.

When you do want the stack flattened — after login, or after completing a wizard — pushAndRemoveUntil takes a predicate and pops everything that fails it, so (route) => false clears the stack entirely.

A push is a Future

Navigator.push returns a Future that completes when that route is popped, carrying whatever the pop passed back. Measured:

before pop, result=null
after pop,  result=chosen value

This is the mechanism behind the "list doesn't refresh" problem above. Since the underlying page does not rebuild on return, the way to react is to await the push and do something with the answer:

final created = await Navigator.of(context).push<Item>(
  MaterialPageRoute(builder: (_) => const NewItemPage()),
);
if (!mounted) return;          // the guard from the previous chapter
if (created != null) setState(() => items.add(created));

Two details are worth naming. The result is nullable — a user who presses the system back button pops with no value, so null means "dismissed" and you must handle it. And the mounted check is the same one the forms chapter measured: awaiting means the widget may be gone by the time control returns.

Navigation as a value

Everything so far is Navigator 1.0: navigation as a sequence of imperative calls. It is genuinely good for what it does, and for a self-contained app it is often all you need.

It has one structural limitation, and deep linking is where you meet it. A push stack records what happened. A deep link asks the app to reconstruct a state it never navigated to — a user taps myapp://users/42 in an email, and the app must come up showing user 42, with a sensible back stack behind it, having performed none of the pushes that would normally have produced that screen.

You can solve this imperatively, and many apps do, by parsing the incoming link at startup and replaying a synthetic sequence of pushes. It works, and it accumulates a second source of truth: the link parser and the push sites must agree about what screens exist, and they drift.

The alternative is to make the route stack a function of a location. Given a string like /users/42?tab=posts, a pure function produces the list of pages that should be on the stack. Navigating means changing the location; the stack follows. Now a deep link is not a special case at all — it is simply a location that happened to arrive from outside rather than from a tap.

That inversion is what Navigator 2.0 and the Router API provide, and what every routing package is built on. The arithmetic is small enough to model directly:

The interesting line in that output is /users/42 producing Home > UserList > UserDetail. Nobody visited UserList. The back stack was constructed from the location, which is exactly what a user arriving from an email needs: pressing back should take them somewhere sensible, not out of the app.

go_router in practice

go_router implements that inversion with a route table. Measured, a router whose initialLocation is a deep link with both a path parameter and a query parameter:

deep-linked straight to: "user 42 tab=posts"
after go("/"):           "home"
Router in the tree?      true
Navigator in the tree?   true
unknown path shows:      [Home, Page Not Found]

Three things in that output.

The deep link needed no special handling. initialLocation and a user tap go through the same code path, which is the entire point of the inversion — there is no separate "handle incoming link" branch to drift out of sync.

It does not replace Navigator. Both Router and Navigator are in the tree. go_router is a RouterDelegate that builds a Navigator from the current location, so everything from the first half of this chapter still applies underneath: pages are routes, pushes are still a stack, results still come back through futures.

Unknown paths have a default. Rather than throwing, it renders a built-in error page, which you can replace with errorBuilder.

Common Mistakes

1. Expecting the page underneath to rebuild. Measured, a covered page neither rebuilds when covered nor when revealed. Await the push and act on its result.

2. Ignoring the null result. A system back press pops with no value, so push<T>() completes with null. That is a normal outcome, not an error case.

3. Forgetting mounted after an awaited push. The awaiting widget may be gone when control returns — the same guard the forms chapter measured.

4. Setting maintainState on the wrong route. It governs whether that route survives being covered. Setting it on the route you are pushing does nothing.

5. Using maintainState: false on a screen holding scroll position or input. It will be disposed when covered and rebuilt from scratch, losing both.

6. Treating deep links as a separate code path. A parser that replays pushes becomes a second map of the app and drifts. Make the stack a function of a location and links stop being special.

7. Assuming a router package replaces Navigator. Measured, go_router puts a Router and a Navigator in the tree; it drives the same stack declaratively.

8. Deep-linking to a screen with no back stack. Constructing a sensible stack — Home > UserList > UserDetail for /users/42 — is the point of deriving it, and it is what stops back throwing the user out of the app.

9. Scattering navigation strings across call sites. Route paths belong in one table. Forty inline pushes are forty places to update when a screen moves.

10. Reaching for Navigator 2.0 by hand. The raw RouterDelegate API is a mechanism, not an ergonomic API; that is why go_router exists and why Flutter adopted it.

Interview Corner

Hands-on

Summary

• Navigator is a stack of routes, and the page underneath a push stays mounted with its State intact.
• A covered page does not rebuild — neither when covered nor when revealed. "The list is stale after I come back" is this, not caching.
• push<T>() returns a Future<T?> completing on pop with the popped value; null means dismissed.
• Check mounted after awaiting a push before calling setState.
• maintainState governs the route it is set on — whether that route's subtree survives being covered. Measured, false disposes it.
• Imperative navigation records a sequence, which is not enough to reconstruct a destination for someone who never walked it.
• Declarative routing makes the stack a function of a location, so a deep link is just a location that arrived from outside.
• A derived back stack is constructed, not replayed — /users/42 yields Home > UserList > UserDetail, so back behaves sensibly.
• go_router does not replace Navigator — measured, both a Router and a Navigator are in the tree.
• Keep route paths in one table. Scattered inline pushes are the thing that makes deep links archaeology later.

Next: Platform Channels — the single mechanism by which every native call, every plugin and every piece of platform data crosses out of Dart and back.