When a user runs a mobile app and then selects another app to run, the first app is moved to the background, or backgrounded. The operating system (both iOS and Android) might kill the backgrounded app to release memory and improve performance for the app running in the foreground.
When the user selects the app again, bringing it back to the foreground, the OS relaunches it. But, unless you’ve set up a way to save the state of the app before it was killed, you’ve lost the state and the app starts from scratch. The user has lost the continuity they expect, which is clearly not ideal. (Imagine filling out a lengthy form and being interrupted by a phone call before clicking Submit.)
So, how can you restore the state of the app so that it looks like it did before it was sent to the background?
Flutter has a solution for this with the
RestorationManager (and related classes)
in the services library.
RestorationManager, the Flutter framework
provides the state data to the engine as the state
changes, so that the app is ready when the OS signals
that it’s about to kill the app, giving the app only
moments to prepare.
You can enable state restoration with just a few tasks:
For custom widgets, you must decide what state you want to restore and hold that state in a
RestorableProperty. (The Flutter API provides various subclasses for different data types.) Define those
RestorablePropertywidgets in a
Stateclass that uses the
RestorationMixin. Register those widgets with the mixin in a
If you use any Navigator API (like
pushNamed, and so on) migrate to the API that has “restorable” in the name (
resstorablePushNamed, and so on) to restore the navigation stack.
WidgetsAppautomatically enables state restoration by injecting a
RootRestorationScope. If you need to restore state above the app class, inject a
The difference between a
restorationScopeId: Widgets that take a
restorationScopeIDcreate a new
RestorationBucket) into which all children store their state. A
restorationIdmeans the widget (and its children) store the data in the surrounding bucket.
Restoring navigation state
If you want your app to return to a particular route that the user was most recently viewing (the shopping cart, for example), then you must implement restoration state for navigation, as well.
If you use the Navigator API directly,
migrate the standard methods to restorable
methods (that have “restorable” in the name).
For example, replace
The VeggieSeasons example (listed under “Other resources” below)
implements navigation with the
values occur in the
Testing state restoration
To test state restoration, set up your mobile device so that
it doesn’t save state once an app is backgrounded.
To learn how to do this for both iOS and Android,
check out Testing state restoration on the
For further information on state restoration, check out the following resources:
- For an example that implements state restoration,
check out VeggieSeasons, a sample app written
for iOS that uses Cupertino widgets. An iOS app requires
a bit of extra setup in Xcode, but the restoration
classes otherwise work the same on both iOS and Android.
The following list links to relevant parts of the VeggieSeasons example:
To learn more about short term and long term state, check out Differentiate between ephemeral state and app state.
You might want to check out packages on pub.dev that perform state restoration, such as
- For more information on navigation and the
go_routerpackage, check out Navigation and routing.