Restore state on Android

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. With the 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:

1. Define a restorationId or a restorationScopeId for all widgets that support it, such as TextField and ScrollView. This automatically enables built-in state restoration for those widgets.

2. 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 RestorableProperty widgets in a State class that uses the RestorationMixin. Register those widgets with the mixin in a restoreState method.

3. If you use any Navigator API (like push, pushNamed, and so on) migrate to the API that has "restorable" in the name (restorablePush, restorablePushNamed, and so on) to restore the navigation stack.

Other considerations:

• Providing a restorationId to MaterialApp, CupertinoApp, or WidgetsApp automatically enables state restoration by injecting a RootRestorationScope. If you need to restore state above the app class, inject a RootRestorationScope manually.

• The difference between a restorationId and a restorationScopeId: Widgets that take a restorationScopeID create a new restorationScope (a new RestorationBucket) into which all children store their state. A restorationId means the widget (and its children) store the data in the surrounding bucket.

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 push with restorablePush.

The VeggieSeasons example (listed under "Other resources" below) implements navigation with the go_router package. Setting the restorationId values occur in the lib/screens classes.

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 RestorationManager page.

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:

  • Defining a RestorablePropery as an instance property
  • Registering the properties
  • Updating the property values
  • Using property values in build
    

• 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 statePersistence.

• For more information on navigation and the go_router package, check out Navigation and routing.

Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-06-04. View source or report an issue.