Learning Flutter’s new navigation and routing system
Note: The sample code in this article is not null-safe and not compatible with Dart 3. For more information on the latest best-practices for navigation and routing in Flutter, go to the Navigation and routing page on docs.flutter.dev.
This article explains how Flutter’s new
Router API works. If you follow Flutter’s open design docs, you might have seen these new features referred to as the Router widget. We’ll explore how these APIs enable more fine-tuned control over the screens in your app and how you can use it to parse routes.
These new APIs are not breaking changes, they simply add a new declarative API. Before Navigator 2.0, it was difficult to push or pop multiple pages, or remove a page underneath the current one. However, if you are happy with how the
Navigator works today, you can keep using it in the same (imperative) way.
Router provides the ability to handle routes from the underlying platform and display the appropriate pages. In this article, the
Router is configured to parse the browser URL to display the appropriate page.
This article helps you choose which
Navigator pattern works best for your app, and explains how to use Navigator 2.0 to parse browser URLs and take full control over the stack of pages that are active. The exercise in this article shows how to build an app that handles incoming routes from the platform and manages the pages of your app. The following GIF shows the example app in action:
If you’re using Flutter, you’re probably using the
Navigator and are familiar with the following concepts:
Navigator— a widget that manages a stack of Route objects.
Route— an object managed by a
Navigatorthat represents a screen, typically implemented by classes like
Before Navigator 2.0,
Routes were pushed and popped onto the
Navigator’s stack with either named routes or anonymous routes. The next sections are a brief recap of these two approaches.
Most mobile apps display screens on top of each other, like a stack. In Flutter, this is easy to achieve by using the
CupertinoApp already use a
Navigator under the hood. You can access the navigator using
Navigator.of() or display a new screen using
Navigator.push(), and return to the previous screen with
push() is called, the
DetailScreen widget is placed on top of the
HomeScreen widget like this:
The previous screen (
HomeScreen) is still part of the widget tree, so any
State object associated with it stays around while
DetailScreen is visible.
Flutter also supports named routes, which are defined in the
routes parameter on
These routes must be predefined. Although you can pass arguments to a named route, you can’t parse arguments from the route itself. For example, if the app is run on the web, you can’t parse the ID from a route like
Advanced named routes with onGenerateRoute
A more flexible way to handle named routes is by using
onGenerateRoute. This API gives you the ability to handle all paths:
Here’s the complete example:
The Navigator 2.0 API adds new classes to the framework in order to make the app’s screens a function of the app state and to provide the ability to parse routes from the underlying platform (like web URLs). Here’s an overview of what’s new:
Page— an immutable object used to set the navigator’s history stack.
Router— configures the list of pages to be displayed by the Navigator. Usually this list of pages changes based on the underlying platform, or on the state of the app changing.
RouteInformationParser, which takes the
RouteInformationProviderand parses it into a user-defined data type.
RouterDelegate— defines app-specific behavior of how the
Routerlearns about changes in app state and how it responds to them. Its job is to listen to the
RouteInformationParserand the app state and build the
Navigatorwith the current list of
BackButtonDispatcher— reports back button presses to the
The following diagram shows how the
RouterDelegate interacts with the
RouteInformationParser, and the app’s state:
Here’s an example of how these pieces interact:
- When the platform emits a new route (for example, “books/2”) , the
RouteInformationParserconverts it into an abstract data type
Tthat you define in your app (for example, a class called
setNewRoutePathmethod is called with this data type, and must update the application state to reflect the change (for example, by setting the
selectedBookId) and call
notifyListenersis called, it tells the
Routerto rebuild the
RouterDelegate.build()returns a new
Navigator, whose pages now reflect the change to the app state (for example, the
Navigator 2.0 exercise
This section leads you through an exercise using the Navigator 2.0 API. We’ll end up with an app that can stay in sync with the URL bar, and handle back button presses from the app and the browser, as shown in the following GIF:
The Navigator has a new
pages argument in its constructor. If the list of
Page objects changes,
Navigator updates the stack of routes to match. To see how this works, we’ll build an app that displays a list of books.
_BooksAppState, keep two pieces of state: a list of books and the selected book:
_BooksAppState, return a
Navigator with a list of
Since this app has two screens, a list of books and a screen showing the details, add a second (detail) page if a book is selected (using
Note that the
key for the page is defined by the value of the
book object. This tells the
Navigator that this
MaterialPage object is different from another when the
Book object is different. Without a unique key, the framework can’t determine when to show a transition animation between different
Note: If you prefer, you can also extend
Page to customize the behavior. For example, this page adds a custom transition animation:
Finally, it’s an error to provide a
pages argument without also providing an
onPopPage callback. This function is called whenever
Navigator.pop() is called. It should be used to update the state (that determines the list of pages), and it must call
didPop on the route to determine if the pop succeeded:
It’s important to check whether
didPop fails before updating the app state.
setState notifies the framework to call the
build() method, which returns a list with a single page when
_selectedBook is null.
Here’s the full example:
As it stands, this app only enables us to define the stack of pages in a declarative way. We aren’t able to handle the platform’s back button, and the browser’s URL doesn’t change as we navigate.
So far, the app can show different pages, but it can’t handle routes from the underlying platform, for example if the user updates the URL in the browser.
This section shows how to implement the
RouterDelegate, and update the app state. Once set up, the app stays in sync with the browser’s URL.
RouteInformationParser parses the route information into a user-defined data type, so we’ll define that first:
In this app, all of the routes in the app can be represented using a single class. Instead, you might choose to use different classes that implement a superclass, or manage the route information in another way.
Next, add a class that extends
The generic type defined on
BookRoutePath, which contains all the state needed to decide which pages to show.
We’ll need to move some logic from
BookRouterDelegate, and create a
GlobalKey. In this example, the app state is stored directly on the
RouterDelegate, but could also be separated into another class.
In order to show the correct path in the URL, we need to return a
BookRoutePath based on the current state of the app:
build method in a
RouterDelegate needs to return a
onPopPage callback now uses
notifyListeners instead of
setState, since this class is now a
ChangeNotifier, not a widget. When the
RouterDelegate notifies its listeners, the
Router widget is likewise notified that the
currentConfiguration has changed and that its
build method needs to be called again to build a new
_handleBookTapped method also needs to use
notifyListeners instead of
When a new route has been pushed to the application,
setNewRoutePath, which gives our app the opportunity to update the app state based on the changes to the route:
RouteInformationParser provides a hook to parse incoming routes (
RouteInformation) and convert it into a user defined type (
BookRoutePath). Use the
Uri class to take care of the parsing:
This implementation is specific to this app, not a general route parsing solution. More on that later.
To use these new classes, we use the new
MaterialApp.router constructor and pass in our custom implementations:
Here’s the complete example:
Running this sample in Chrome now shows the routes as they are being navigated, and navigates to the correct page when the URL is manually edited.
You can provide a custom implementation of
TransitionDelegate that customizes how routes appear on (or are removed from) the screen when the list of pages changes. If you need to customize this, read on, but if you are happy with the default behavior you can skip this section.
Provide a custom
TransitionDelegate to a
Navigator that defines the desired behavior:
For example, the following implementation disables all transition animations:
This custom implementation overrides
resolve(), which is in charge of marking the various routes as either pushed, popped, added, completed, or removed:
markForPush— displays the route with an animated transition
markForAdd— displays the route without an animated transition
markForPop— removes the route with an animated transition and completes it with a result. “Completing” in this context means that the
resultobject is passed to the
markForComplete— removes the route without a transition and completes it with a
markForRemove— removes the route with no animated transition and without completing.
This class only affects the declarative API, which is why the back button still displays a transition animation.
How this example works: This example looks at both the new routes and the routes that are exiting the screen. It goes through all of the objects in
newPageRouteHistory and marks them to be added without a transition animation using
markForAdd. Next, it loops through values of the
locationToExitingPageRoute map. If it finds a route marked as
isWaitingForExitingDecision, then it calls
markForRemove to indicate that the route should be removed without a transition and without completing.
This larger demo shows how to add a
Router within another
Router. Many apps require routes for the destinations in a
BottomAppBar, and routes for a stack of views above it, which requires two Navigators. To do this, the app uses an application state object to store app-specific navigation state (the selected menu index and the selected
Book object). This example also shows how to configure which
Router handles the back button.
This article explored how to use these APIs for a specific app, but could also be used to build a higher-level API package. We hope that you’ll join us in exploring what a higher-level API built on top of these features can do for users.