Savedstate

Write pluggable components that save the UI state when a process dies, and restore it when the process restarts.
Latest Update Stable Release Release Candidate Beta Release Alpha Release
July 2, 2025 1.3.1 - - -

Declaring dependencies

To add a dependency on SavedState, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    // Java language implementation
    implementation "androidx.savedstate:savedstate:1.3.1"

    // Kotlin
    implementation "androidx.savedstate:savedstate-ktx:1.3.1"
}

Kotlin

dependencies {
    // Java language implementation
    implementation("androidx.savedstate:savedstate:1.3.1")

    // Kotlin
    implementation("androidx.savedstate:savedstate-ktx:1.3.1")
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.3

Version 1.3.0

May 7, 2025

androidx.savedstate:savedstate-*:1.3.0 is released. Version 1.3.0 contains these commits.

Important changes since 1.2.0

  • LocalSavedStateRegistryOwner has been moved from Compose UI to the new savedstate-compose module so that its Compose-based helper APIs can be used outside of Compose UI. This should always be used when using Compose UI 1.9.0-alpha02 and higher, but is backward compatible such that it can be used with all versions of Compose.
  • The savedstate-ktx kotlin extensions have now been moved to the base savedstate module.
  • SavedStateRegistryOwner instances retrieved via findViewTreeSavedStateRegistryOwner can now be resolved through disjoint parents of a view, such as a ViewOverlay. See the release notes of core or the documentation in ViewTree.setViewTreeDisjointParent for more information on disjoint view parents.

Kotlin Multiplatform

  • The SavedState module is now KMP compatible. Supported platforms now include Android, iOS, Linux, Mac, and JVM desktop environments.

  • Introduce SavedState opaque type as an abstraction to provide a consistent way to save and restore application state in KMP. It includes a SavedStateReader and SavedStateWriter for modifying the state to be saved. On Android, SavedState is a type alias for Bundle, ensuring binary compatibility and facilitating the migration of existing APIs to a common source set. On other platforms, SavedState is a Map<String, Any> instance.

      // Create a new SavedState object using the savedState DSL:
  val savedState = savedState {
    putInt("currentPage", 1)
    putString("filter", "favorites")
  }

  // Read from a SavedState object
  val currentPage = savedState.read { getInt("currentPage") }

  // Edit an existing SavedState object
  savedState.write {
    remove("currentPage")
  }

KotlinX Serialization Support

  • SavedState now includes KotlinX Serialization support. You can convert a class annotated with @Serializable to a SavedState using the methods encodeToSavedState and decodeFromSavedState. The returned SavedState is a regular Bundle on Android and can be used by any API that accepts a Bundle.

    @Serializable
data class Person(val firstName: String, val lastName: String)

fun main() {
    val person = Person("John", "Doe")
    val encoded: SavedState = encodeToSavedState(person)
    val decoded: Person = decodeFromSavedState(encoded)
}

  • While most types (such as primitive types) are directly supported without any configuration needed, additional serializers that can be used with @Serializable(with = ___:class)can be found in the androidx.savedstate.serialization.serializers package in the savedstate module and the androidx.savedstate.compose.serialization.serializers package in the savedstate-compose module.

  • We also have included saved, a lazy property delegate, to make it easy to store @Serializable classes in a SavedStateRegistryOwner (e.g., ComponentActivity, Fragment, etc.) and have those classes automatically be restored across process death and recreation. Please note the saved delegate is lazy and will not call the init lambda or save anything into the SavedStateRegistry until it is accessed.

    @Serializable
data class Person(val firstName: String, val lastName: String)

class MyActivity : ComponentActivity() {
    var person by saved { Person("John", "Doe") }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        this.person = Person("Jane", "Doe")
    }
}

  • There is a similar saved property delegate for SavedStateHandle added in Lifecycle 2.9.0.

Version 1.3.0-rc01

April 23, 2025

androidx.savedstate:savedstate-*:1.3.0-rc01 is released. Version 1.3.0-rc01 contains these commits.

Version 1.3.0-beta01

April 9, 2025

androidx.savedstate:savedstate-*:1.3.0-beta01 is released. Version 1.3.0-beta01 contains these commits.

Dependency Updates

  • This library now targets Kotlin 2.0 language level and requires KGP 2.0.0 or newer. (Idb6b5)

Version 1.3.0-alpha11

March 26, 2025

androidx.savedstate:savedstate-*:1.3.0-alpha11 is released with no notable public changes. Version 1.3.0-alpha11 contains these commits.

Version 1.3.0-alpha10

March 12, 2025

androidx.savedstate:savedstate-*:1.3.0-alpha10 is released. Version 1.3.0-alpha10 contains these commits.

New Features

  • Add non-reified method variants for get collections in SavedStateReader. (I0b641, b/399820614)
  • Add encodeDefaults to SavedStateConfiguration, allowing customizing whether properties with default values should be encoded. (I893cc, b/395104517)
  • Add SnapshotStateMapSerializer to support mutableStateMapOf. (Ie6f19, b/378895074)
  • Add SnapshotStateListSerializer to support mutableStateListOf. (I4d888, b/378895074)
  • Add getOrNull alternative methods for SavedStateReader.get variants. These methods will auto-box primitive values. (I6228c, b/399820614)

API Changes

  • Remove getOrElse from SavedStateReader in favor of getOrNull() ?: else(). (I87317, b/399820614)
  • Remove inline modifier from SavedStateReader and SavedStateWriter methods. (If2a02, b/399820614)
  • Remove built-in Android-specific List and Array serializers out of public API (Ida293)
  • Replace SparseParcelableArraySerializer with SparseArraySerializer (I91de8)
  • Make all SavedStateReader.get behave consistently by throwing when value type doesn't match return type (I78c4a, b/399317598)
  • Rename SavedState*Delegates to SavedState*Delegate. (I8589b, b/399629301)
  • Rename SavedStateConfig to SavedStateConfiguration. (I043a5, b/399629301)

Version 1.3.0-alpha09

February 26, 2025

androidx.savedstate:savedstate-*:1.3.0-alpha09 is released. Version 1.3.0-alpha09 contains these commits.

New Features

  • Add fallback for built-in types, ensuring that all types supported by Bundle can be used with encodeAsSavedState/decodeFromSavedState by default or, for properties in @Serializable classes, via the @Contextual annotation. (Ic01d2)
  • Include support for classDiscriminator and classDiscriminatorMode on SavedStateConfig. (I69b66, b/395104517)

API Changes

  • Add SavedStateConfig parameter to saved() delegates (I39b3a)
  • Makes built-in serializers singleton objects (Ifeee4)
  • SavedStateConfig properties are now public, enabling other modules to use these configurations. (Ie5f49, b/378897438)
  • Support @Serializer(with = ...) for MutableStateFlowSerializer and MutableStateSerializer (I90953)
  • Add contentDeepToString to SavedStateReader (I14d10)

Version 1.3.0-alpha08

February 12, 2025

androidx.savedstate:savedstate-*:1.3.0-alpha08 is released. Version 1.3.0-alpha08 contains these commits.

New Features

  • Move MutableStateSerializer to savedstate-compose from lifecycle-viewmodel-compose, allowing you to use the SavedState Serialization APIs with Compose’s MutableState. (I4f690, b/378895074)

API Changes

  • Add a factory function to create SavedState from an existing SavedState. (I39f9a)
  • Adds support for Array<SavedState> and List<SavedState> in androidx.savedstate. (Idd8a5)
  • Add SavedStateConfig optional parameter to SavedState encoding/decoding (I6c4c0)

Version 1.3.0-alpha07

January 29, 2025

androidx.savedstate:savedstate-*:1.3.0-alpha07 is released. Version 1.3.0-alpha07 contains these commits.

New Features

  • Add MutableStateFlowSerializer for serializing kotlinx.coroutines.flow.MutableStateFlow. (I6a892, b/378895070)

API Changes

  • Replace overloaded SavedStateRegistryOwner.saved() delegate functions with default parameters (Icd1c1)
  • Make JavaSerializableSerializer and ParcelableSerializer abstract (I268f6)
  • Remove generic T : CharSequence from CharSequenceSerializer (Ib40bd)

Version 1.3.0-alpha06

December 11, 2024

androidx.savedstate:savedstate-*:1.3.0-alpha06 is released. Version 1.3.0-alpha06 contains these commits.

New Features

  • SavedState KMP now supports: IBinder, Size, SizeF, Array<Parcelable>, SparseArray<Parcelable> and Serializable (Android). (I1ba94, b/334076622)
  • Add KSerializer instances that can be used to encode/decode Java and Android types supported by Bundle by marking the relevant field in your class with @Serializable(with = ParcelableSerializer::class). (I8c10f, I28caf, b/376026712)
  • SavedStateRegistryOwner instances retrieved via findViewTreeSavedStateRegistryOwner can now be resolved through disjoint parents of a view, such as a ViewOverlay. See the release notes of core or the documentation in ViewTree.setViewTreeDisjointParent for more information on disjoint view parents. (Iccb33)

API Changes

  • Make the namings and package organization more consistent with SavedStateRegistryOwnerDelegate (I8c135, b/376026744)

Version 1.3.0-alpha05

November 13, 2024

androidx.savedstate:savedstate-*:1.3.0-alpha05 is released. Version 1.3.0-alpha05 contains these commits.

KotlinX Serialization Support

  • SavedState now includes KotlinX Serialization support. You can convert a class annotated with @Serializable to a SavedState using the methods encodeToSavedState and decodeFromSavedState. The returned SavedState is a regular Bundle on Android and can be used by any API that accepts a Bundle. (I6f59f, b/374102924)

    @Serializable
data class Person(val firstName: String, val lastName: String)

fun main() {
    val person = Person("John", "Doe")
    val encoded: SavedState = encodeToSavedState(person)
    val decoded: Person = decodeFromSavedState(encoded)
}

  • We also have included saved, a lazy property delegate, to make it easy to store @Serializable classes in a SavedStateRegistryOwner (e.g., ComponentActivity, Fragment, etc.) and have those classes automatically be restored across process death and recreation. Please note the saved delegate is lazy and will not call the init lambda or save anything into the SavedStateRegistry until it is accessed. (I66739, b/376027806)

    @Serializable
data class Person(val firstName: String, val lastName: String)

class MyActivity : ComponentActivity() {
    var person by saved { Person("John", "Doe") }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        this.person = Person("Jane", "Doe")
    }
}

  • There is a similar saved property delegate for SavedStateHandle added in Lifecycle 2.9.0-alpha07.

API Changes

  • Add toMap to SavedState, allowing any SavedState to be converted to a regular Map (shallow copy). (I487b9, b/334076622)
  • SavedState KMP now supports arrays. (Ic0552, b/334076622)

Version 1.3.0-alpha04

October 30, 2024

androidx.savedstate:savedstate-*:1.3.0-alpha04 is released. Version 1.3.0-alpha04 contains these commits.

API Changes

Version 1.3.0-alpha03

October 16, 2024

androidx.savedstate:savedstate-*:1.3.0-alpha03 is released with no notable changes. Version 1.3.0-alpha03 contains these commits.

Version 1.3.0-alpha02

October 2, 2024

androidx.savedstate:savedstate-*:1.3.0-alpha02 is released. Version 1.3.0-alpha02 contains these commits.

Kotlin Multiplatform

  • The SavedState module is now KMP compatible. Supported platforms now include Android, iOS, Linux, Mac, and JVM desktop environments. (I26305, b/334076622)

New Features

  • Introduce SavedState opaque type as an abstraction to provide a consistent way to save and restore application state in KMP. It includes a SavedStateReader and SavedStateWriter for modifying the state to be saved. On Android, SavedState is a type alias for Bundle, ensuring binary compatibility and facilitating the migration of existing APIs to a common source set. On other platforms, SavedState is a Map<String, Any> instance. (I18575, b/334076622)
  // Create a new SavedState object using the savedState DSL:
  val savedState = savedState {
    putInt("currentPage", 1)
    putString("filter", "favorites")
  }

  // Read from a SavedState object
  val currentPage = savedState.read { getInt("currentPage") }

  // Edit an existing SavedState object
  savedState.write {
    remove("currentPage")
  }

API Changes

  • SavedStateRegistry and SavedStateRegistryController are now KMP compatible. (Id7bb8, b/334076622)
  • SavedState, SavedStateWriter and SavedStateReader are now KMP compatible. (I26305, b/334076622)

Version 1.3.0-alpha01

August 7, 2024

androidx.savedstate:savedstate:1.3.0-alpha01 and androidx.savedstate:savedstate-ktx:1.3.0-alpha01 are released. Version 1.3.0-alpha01 contains these commits.

API Changes

  • The savedstate-ktx kotlin extensions have now been moved to the base savedstate module. (I1cc18, b/274803094)

Note

  • Update compileSdk to 35 (5dc41be)

Version 1.2.1

Version 1.2.1

March 22, 2023

androidx.savedstate:savedstate:1.2.1 and androidx.savedstate:savedstate-ktx:1.2.1 are released. Version 1.2.1 contains these commits.

Dependency Updates

Version 1.2.0

Version 1.2.0

June 29, 2022

androidx.savedstate:savedstate:1.2.0 and androidx.savedstate:savedstate-ktx:1.2.0 are released. Version 1.2.0 contains these commits.

Important changes since 1.1.0

  • SavedStateRegistryController now allows early attachment of the SavedStateRegistry via performAttach().
  • You can now retrieve a previously registered SavedStateProvider from a SavedStateRegistry via getSavedStateProvider().
  • The SavedState library has been rewritten in Kotlin.
    • For SavedStateRegistryOwner, this is a source incompatible change for those classes written in Kotlin - you must now override the savedStateRegistry property rather than implement the previous getSavedStateRegistry() function.
    • For ViewTreeSavedStateRegistryOwner, this is a source incompatible change for those classes written in Kotlin - you must now directly import and use the Kotlin extension methods on View of androidx.savedstate.setViewTreeSavedStateRegistryOwner and androidx.savedstate.findViewTreeSavedStateRegistryOwner to set and find a previously set owner. This replaces the savedstate-ktx API of findViewTreeSavedStateRegistryOwner.

Behavior Changes

  • SavedStateRegistry no longer saves an empty Bundle if there is no state to save.

Version 1.2.0-rc01

May 11, 2022

androidx.savedstate:savedstate:1.2.0-rc01 and androidx.savedstate:savedstate-ktx:1.2.0-rc01 are released. Version 1.2.0-rc01 contains these commits.

Documentation Changes

  • The SavedStateRegistryOwner Kdocs have been updated to clarify the responsibilities and contract that the owner has on how it should implement the interface or when they should call the methods on SavedStateRegistryController. (Iefc95, b/228887344)

Version 1.2.0-beta01

April 20, 2022

androidx.savedstate:savedstate:1.2.0-beta01 and androidx.savedstate:savedstate-ktx:1.2.0-beta01 are released. Version 1.2.0-beta01 contains these commits.

API Changes

  • The SavedStateRegistry and ViewTreeSavedStateRegistryOwner classes have been rewritten in Kotlin. For ViewTreeSavedStateRegistryOwner, this is a source incompatible change for those classes written in Kotlin - you must now directly import and use the Kotlin extension methods on View of androidx.savedstate.setViewTreeSavedStateRegistryOwner and androidx.savedstate.findViewTreeSavedStateRegistryOwner to set and find a previously set owner. This replaces the savedstate-ktx API of findViewTreeSavedStateRegistryOwner. This is binary compatible and remains source compatible for implementations written in the Java programming language. (b/220191285)

Version 1.2.0-alpha02

April 6, 2022

androidx.savedstate:savedstate:1.2.0-alpha02 and androidx.savedstate:savedstate-ktx:1.2.0-alpha02 are released. Version 1.2.0-alpha02 contains these commits.

New Features

  • You can now retrieve a previously registered SavedStateProvider from a SavedStateRegistry via getSavedStateProvider(). (I7ea47, b/215406268)

API Changes

  • The SavedStateRegistryOwner, SavedStateRegistryController, and Recreator classes have been rewritten in Kotlin. For SavedStateRegistryOwner, this is a source incompatible change for those classes written in Kotlin - you must now override the savedStateRegistry property rather than implement the previous getSavedStateRegistry() function. This is binary compatible and source compatible for implementations written in the Java programming language. (b/220191285)

Version 1.2.0-alpha01

January 26, 2022

androidx.savedstate:savedstate:1.2.0-alpha01 and androidx.savedstate:savedstate-ktx:1.2.0-alpha01 are released. Version 1.2.0-alpha01 contains these commits.

New Features

  • SavedStateRegistryController now allows early attachment of the SavedStateRegistry via performAttach(). (Ice4bf)

Behavior Changes

Version 1.1.0

Version 1.1.0

February 10, 2021

androidx.savedstate:savedstate:1.1.0 and androidx.savedstate:savedstate-ktx:1.1.0 are released. Version 1.1.0 contains these commits.

Major changes since 1.0.0

  • ViewTreeSavedStateRegistryOwner API: A new ViewTreeSavedStateRegistryOwner.get(View) API allows you to retrieve the containing SavedStateRegistry given a View instance. You must upgrade to Activity 1.2.0, Fragment 1.3.0, and AppCompat 1.3.0-alpha01 or higher to populate this correctly.
  • savedstate-ktx artifact: The new savedstate-ktx artifact has been added with a findViewTreeSavedStateRegistryOwner() Kotlin extension for working with ViewTreeSavedStateRegistryOwner.

Version 1.1.0-rc01

December 16, 2020

androidx.savedstate:savedstate:1.1.0-rc01 and androidx.savedstate:savedstate-ktx:1.1.0-rc01 are released with no changes since 1.1.0-beta01. Version 1.1.0-rc01 contains these commits.

Version 1.1.0-beta01

October 1, 2020

androidx.savedstate:savedstate:1.1.0-beta01 and androidx.savedstate:savedstate-ktx:1.1.0-beta01 are released with no changes since 1.1.0-alpha01. Version 1.1.0-beta01 contains these commits.

Version 1.1.0-alpha01

May 20, 2020

androidx.savedstate:savedstate:1.1.0-alpha01 and androidx.savedstate:savedstate-ktx:1.1.0-alpha01 are released. Version 1.1.0-alpha01 contains these commits.

New Features

Version 1.0.0

Version 1.0.0

September 5, 2019

androidx.savedstate:savedstate:1.0.0 is released. The commits included in this version can be found here.

Major features of SavedState 1.0.0

androidx.savedstate graduated to a stable release. This is a set of APIs that allow developers to plugin components into the restore / saveInstanceState process. The main entry point of the API is SavedStateRegistry, which provides a way to retrieve previously saved states using consumeRestoredStateForKey and register a callback to registerSavedStateProvider to provide a saved state once system requests it.

Version 1.0.0-rc01

July 2, 2019

androidx.savedstate:savedstate:1.0.0-rc01 is released. The commits included in this version can be found here.

Bug fixes

Version 1.0.0-beta01

May 7, 2019

androidx.savedstate:savedstate:1.0.0-beta01 is released. The commits included in this version can be found here.

Version 1.0.0-alpha02

March 13, 2019

androidx.savedstate:savedstate:1.0.0-alpha02 is released. androidx.savedstate:savedstate combines artifacts androidx.savedstate:savedstate-bundle and androidx.savedstate:savedstate-common into one artifact, because it was decided to simplify savedstate infrastructure and remove generics from SavedStateRegistry. Thus, there is no need for separate modules.

The full list of commits included in this version can be found here.

New features

  • SavedStateRegistry.runOnNextRecreaction(Class<? extends AutoRecreated> clazz ) was added. The given class will be instantiated and the method AutoRecreated.onRecreated will be run when the owning component restarted.

API changes

  • Generics removed from SavedStateRegistry<T>
  • AbstractSavedStateRegistry & BundlableSavedStateRegistry are removed, use simple SavedStateRegistry instead
  • BundleSavedStateRegistryOwner is renamed to SavedStateRegistryOwner

Version 1.0.0-alpha01

December 17, 2018

This is the first release of SavedState.

New features

androidx.savedstate is a new set of alpha APIs that allow developers to plugin components to the restore / saveInstanceState process. The main entry point of the API is SavedStateRegistry<T>, which provides a way to retrieve previously savedstate via consumeRestoredStateForKey and register a callback to registerSavedStateProvider to provide a savedstate once system requests it.