Flutter's Router API: Declarative Navigation

Why it exists

Flutter's original Navigator API was a simple imperative stack, making it difficult to manage the browser URL bar, handle incoming deep links, or manipulate the navigation history. The Router API (Navigator 2.0) was created to provide a powerful, declarative system for full control over the app's navigation state, making Flutter a robust choice for web and desktop platforms.

The mental model

Think of the Router API as a state machine for navigation. Your app's state (e.g., which user is logged in, what product is being viewed) directly determines the stack of pages shown. The Router is a pipeline that takes raw information, like a URL from the browser, and transforms it into this page stack. You don't tell it how to get to a page; you tell it what the navigation state is.

How it works

The process involves several key components. First, a RouteInformationProvider gets routing information from the OS, like a new URL or a back button press. Second, a RouteInformationParser takes this raw information (e.g., the string "/products/123") and parses it into a structured, custom data object (e.g., ProductDetailsRoute(id: '123')). Third, the RouterDelegate receives this data object and, based on it and other app state, builds a Navigator widget with the correct list of Pages. The delegate is the brain of the operation. Finally, a BackButtonDispatcher manages back button events, delegating them to the appropriate RouterDelegate.

When to use it

Use the Router API for any non-trivial app, especially those targeting web or desktop where URL management is critical. It's necessary for handling deep links, custom navigation transitions, and nested routing scenarios (e.g., tabs within a page that have their own navigation stack). If you need to programmatically control the entire navigation history, this is the tool.

When not to use it

For very simple applications with a linear flow and no need for web support or deep linking, the original Navigator API (Navigator.push/pop) is simpler due to less boilerplate. If you find yourself writing a Parser and Delegate just to push one page, you might be over-engineering. Packages like go_router can simplify the Router API for you.

One canonical example

A user navigates to yourapp.com/users/42. The RouteInformationProvider reports the new route. Your RouteInformationParser converts the string "/users/42" into a UserDetailsRoute(id: '42') object. Your RouterDelegate receives this object, updates its internal state, and rebuilds its Navigator to show a HomePage with a UserDetailsPage(userId: '42') on top. The URL bar, app content, and navigation history are all perfectly in sync.