The `Route` class no longer manages its overlay entries in overlay, and its `install()` method no longer has an `insertionPoint` parameter. The `isInitialRoute` property in `RouteSetting` has been deprecated, and `Navigator.pop()` no longer returns a value.
Original behavior
We refactored the navigator APIs to prepare for the new page API and the introduction of the `Router` widget as outlined in the Router design document. This refactoring introduced some function signature changes in order to make the existing navigator APIs continue to work with the new page API.
New behavior
The boolean return value of `Navigator.pop()` was not well defined, and the user could achieve the same result by calling `Navigator.canPop()`. Since the API for `Navigator.canPop()` was better defined, we simplified `Navigator.pop()` to not return a boolean value.
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses Route, RouteSetting, Router and related APIs.
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
Case 1: An app depends on pop() returning a boolean value.
TextField(
onTap: () {
if (Navigator.pop(context))
print('There still is at least one route after pop');
else
print('Oops! No more routes.');
}
)You could use Navigator.canPop() in combination with
Navigator.pop() to achieve the same result.
TextField(
onTap: () {
if (Navigator.canPop(context))
print('There still is at least one route after pop');
else
print('Oops! No more routes.');
// Our navigator pops the route anyway.
Navigator.pop(context);
}
)Case 2: An app generates routes based on isInitialRoute.
MaterialApp(
onGenerateRoute: (RouteSetting setting) {
if (setting.isInitialRoute)
return FakeSplashRoute();
else
return RealRoute(setting);
}
)There are different ways to migrate this change.
One way is to set an explicit value for MaterialApp.initialRoute.
You can then test for this value in place of isInitialRoute.
As initialRoute inherits its default value outside of Flutter's scope,
you must set an explicit value for it.
MaterialApp(
initialRoute: '/', // Set this value explicitly. Default might be altered.
onGenerateRoute: (RouteSetting setting) {
if (setting.name == '/')
return FakeSplashRoute();
else
return RealRoute(setting);
}
)If there is a more complicated use case,
you can use the new API, onGenerateInitialRoutes,
in MaterialApp or CupertinoApp.
MaterialApp(
onGenerateRoute: (RouteSetting setting) {
return RealRoute(setting);
},
onGenerateInitialRoutes: (String initialRouteName) {
return <Route>[FakeSplashRoute()];
}
)AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Official migration guide
- Route
- Route.install
- RouteSetting.isInitialRoute
- Navigator
- Navigator.pop
- Navigator.canPop
- Issue 45938: Router
- PR 44930
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.