Flutter 3.41 is live! Check out theFlutter 3.41 blog post!
Route and Navigator Refactoring
Some APIs and function signatures of the Route and Navigator classes have changed.
These breaking change docs are accurate, as of the release under which they are published. Over time, the workarounds described here might become inaccurate. We don't, in general, keep these breaking change docs up to date as of each release.
Thebreaking change index file lists the docs created for each release.
Summary
# TheRoute class no longer manages its overlay entries in overlay, and itsinstall() method no longer has aninsertionPoint parameter. TheisInitialRoute property inRouteSetting has been deprecated, andNavigator.pop() no longer returns a value.
Context
# We refactored the navigator APIs to prepare for the new page API and the introduction of theRouter widget as outlined in theRouter 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.
Description of change
# The boolean return value ofNavigator.pop() was not well defined, and the user could achieve the same result by callingNavigator.canPop(). Since the API forNavigator.canPop() was better defined, we simplifiedNavigator.pop() to not return a boolean value.
On the other hand, the navigator requires the ability to manually rearrange entries in the overlay to allow the user to change the route history in the new API. We changed it so that the route only creates and destroys its overlay entries, while the navigator inserts or removes overlay entries from the overlay. We also removed theinsertionPoint argument ofRoute.install() because it was obsolete after the change.
Finally, we removed theisInitialRoute property fromRouteSetting as part of refactoring, and provided theonGenerateInitialRoutes API for full control of initial routes generation.
Migration guide
#Case 1: An app depends onpop() returning a boolean value.
TextField(onTap:(){if(Navigator.pop(context))print('There still is at least one route after pop');elseprint('Oops! No more routes.');}) You could useNavigator.canPop() in combination withNavigator.pop() to achieve the same result.
TextField(onTap:(){if(Navigator.canPop(context))print('There still is at least one route after pop');elseprint('Oops! No more routes.');// Our navigator pops the route anyway.Navigator.pop(context);})Case 2: An app generates routes based onisInitialRoute.
MaterialApp(onGenerateRoute:(RouteSettingsetting){if(setting.isInitialRoute)returnFakeSplashRoute();elsereturnRealRoute(setting);}) There are different ways to migrate this change. One way is to set an explicit value forMaterialApp.initialRoute. You can then test for this value in place ofisInitialRoute. AsinitialRoute 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:(RouteSettingsetting){if(setting.name=='/')returnFakeSplashRoute();elsereturnRealRoute(setting);}) If there is a more complicated use case, you can use the new API,onGenerateInitialRoutes, inMaterialApp orCupertinoApp.
MaterialApp(onGenerateRoute:(RouteSettingsetting){returnRealRoute(setting);},onGenerateInitialRoutes:(StringinitialRouteName){return<Route>[FakeSplashRoute()];})Timeline
# Landed in version: 1.16.3
In stable release: 1.17
References
#Design doc:
API documentation:
Relevant issue:
Relevant PR:
- PR 44930 - Refactor the imperative api to continue working in the new navigation system
Unless stated otherwise, the documentation on this site reflects Flutter 3.38.6. Page last updated on 2025-10-30.View source orreport an issue.