public final class SavedStateHandle

A handle to saved state passed down to androidx.lifecycle.ViewModel. You should use SavedStateViewModelFactory if you want to receive this object in ViewModel's constructor.

This is a key-value map that will let you write and retrieve objects to and from the saved state. These values will persist after the process is killed by the system and remain available via the same object.

You can read a value from it via get or observe it via androidx.lifecycle.LiveData returned by getLiveData.

You can write a value to it via set or setting a value to androidx.lifecycle.MutableLiveData returned by getLiveData.

Summary

Nested types
public static class SavedStateHandle.Companion

Public constructors

Creates a handle with the empty state.

Creates a handle with the given initial arguments.

Public methods
final void

Clear any SavedStateProvider that was previously set via setSavedStateProvider.
final boolean
final T
@MainThread
<T extends Object> get(@NonNull String key)

Returns a value associated with the given key.
final @NonNull MutableStateFlow<@NonNull T>
@MainThread
<T extends Object> getMutableStateFlow(@NonNull String key, @NonNull T initialValue)

Returns a MutableStateFlow that will emit the currently active value associated with the given key.
final @NonNull StateFlow<@NonNull T>
@MainThread
<T extends Object> getStateFlow(@NonNull String key, @NonNull T initialValue)

Returns a StateFlow that will emit the currently active value associated with the given key.
final @NonNull Set<@NonNull String>

Returns all keys contained in this SavedStateHandle
final T
@MainThread
<T extends Object> remove(@NonNull String key)

Removes a value associated with the given key.
final void
@MainThread
<T extends Object> set(@NonNull String key, T value)

Associate the given value with the key.
final void

Set a SavedStateProvider that will have its state saved into this SavedStateHandle.

Extension functions
final @NonNull ReadWriteProperty<Object, @NonNull T>
<T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with fully qualified property or variable name as key and the default serializer.
final @NonNull ReadWriteProperty<Object, @NonNull T>
<T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull String key,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with the default serializer.
final @NonNull ReadWriteProperty<Object, @NonNull T>
<T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull <Error class: unknown class><@NonNull T> serializer,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with fully qualified property or variable name as key.
final @NonNull ReadWriteProperty<Object, @NonNull T>
<T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull String key,
    @NonNull <Error class: unknown class><@NonNull T> serializer,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T.
final @NonNull T
<T extends Object> SavedStateHandleKt.toRoute(
    @NonNull SavedStateHandle receiver,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap
)

Returns route as an object of type T
final @NonNull T
<T extends Object> SavedStateHandleKt.toRoute(
    @NonNull SavedStateHandle receiver,
    @NonNull KClass<@NonNull T> route,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap
)

Returns route as an object of type T

Public constructors

SavedStateHandle

Added in 1.0.0
public SavedStateHandle()

Creates a handle with the empty state.

SavedStateHandle

Added in 1.0.0
public SavedStateHandle(@NonNull Map<@NonNull String, Object> initialState)

Creates a handle with the given initial arguments.

Parameters
@NonNull Map<@NonNull String, Object> initialState

initial arguments for the SavedStateHandle

Public methods

clearSavedStateProvider

Added in 2.3.0
@MainThread
public final void clearSavedStateProvider(@NonNull String key)

Clear any SavedStateProvider that was previously set via setSavedStateProvider.

Note: calling this method within SavedStateProvider.saveState is supported, but will only affect future state saving operations.

Parameters
@NonNull String key

a key previously used with setSavedStateProvider

contains

Added in 1.0.0
@MainThread
public final boolean contains(@NonNull String key)
Parameters
@NonNull String key

The identifier for the value
Returns
boolean

true if there is value associated with the given key.

get

Added in 1.0.0
@MainThread
public final T <T extends Object> get(@NonNull String key)

Returns a value associated with the given key.

Note: If T is an Array of Parcelable classes, note that you should always use Array<Parcelable> and create a typed array from the result as going through process death and recreation (or using the Don't keep activities developer option) will result in the type information being lost, thus resulting in a ClassCastException if you directly try to assign the result to an Array<CustomParcelable> value.

val typedArray = savedStateHandle.get<Array<Parcelable>>("KEY").map {
  it as CustomParcelable
}.toTypedArray()
Parameters
@NonNull String key

a key used to retrieve a value.

getMutableStateFlow

Added in 2.9.0-alpha08
@MainThread
public final @NonNull MutableStateFlow<@NonNull T> <T extends Object> getMutableStateFlow(@NonNull String key, @NonNull T initialValue)

Returns a MutableStateFlow that will emit the currently active value associated with the given key.

val flow = savedStateHandle.getMutableStateFlow(KEY, "defaultValue")

Since this is a MutableStateFlow there will always be a value available which, is why an initial value must be provided. The value of this flow is changed by making a call to set, passing in the key that references this flow or by updating the value of the returned MutableStateFlow

If there is already a value associated with the given key, the initial value will be ignored.

Note 1: If T is an Array of Parcelable classes, note that you should always use Array<Parcelable> and create a typed array from the result as going through process death and recreation (or using the Don't keep activities developer option) will result in the type information being lost, thus resulting in a ClassCastException if you directly try to collect the result as an Array<CustomParcelable>.

val typedArrayFlow = savedStateHandle.getMutableStateFlow<Array<Parcelable>>(
  "KEY"
).map { array ->
  // Convert the Array<Parcelable> to an Array<CustomParcelable>
  array.map { it as CustomParcelable }.toTypedArray()
}

Note 2: On Android, this method is mutually exclusive with getLiveData for the same key. You should use either getMutableStateFlow or getLiveData to access the stored value, but not both. Using both methods with the same key will result in an IllegalStateException.

Parameters
@NonNull String key

The identifier for the flow
@NonNull T initialValue

If no value exists with the given key, a new one is created with the given initialValue.

getStateFlow

Added in 2.5.0
@MainThread
public final @NonNull StateFlow<@NonNull T> <T extends Object> getStateFlow(@NonNull String key, @NonNull T initialValue)

Returns a StateFlow that will emit the currently active value associated with the given key.

val flow = savedStateHandle.getStateFlow(KEY, "defaultValue")

Since this is a StateFlow there will always be a value available which, is why an initial value must be provided. The value of this flow is changed by making a call to set, passing in the key that references this flow.

If there is already a value associated with the given key, the initial value will be ignored.

Note: If T is an Array of Parcelable classes, note that you should always use Array<Parcelable> and create a typed array from the result as going through process death and recreation (or using the Don't keep activities developer option) will result in the type information being lost, thus resulting in a ClassCastException if you directly try to collect the result as an Array<CustomParcelable>.

val typedArrayFlow = savedStateHandle.getStateFlow<Array<Parcelable>>(
  "KEY"
).map { array ->
  // Convert the Array<Parcelable> to an Array<CustomParcelable>
  array.map { it as CustomParcelable }.toTypedArray()
}
Parameters
@NonNull String key

The identifier for the flow
@NonNull T initialValue

If no value exists with the given key, a new one is created with the given initialValue.

keys

Added in 1.0.0
@MainThread
public final @NonNull Set<@NonNull String> keys()

Returns all keys contained in this SavedStateHandle

Returned set contains all keys: keys used to get LiveData-s, to set SavedStateProviders and keys used in regular set.

remove

Added in 1.0.0
@MainThread
public final T <T extends Object> remove(@NonNull String key)

Removes a value associated with the given key. If there is a LiveData and/or StateFlow associated with the given key, they will be removed as well.

All changes to androidx.lifecycle.LiveDatas or StateFlows previously returned by SavedStateHandle.getLiveData or getStateFlow won't be reflected in the saved state. Also that LiveData or StateFlow won't receive any updates about new values associated by the given key.

Parameters
@NonNull String key

a key
Returns
T

a value that was previously associated with the given key.

set

Added in 1.0.0
@MainThread
public final void <T extends Object> set(@NonNull String key, T value)

Associate the given value with the key. The value must have a type that could be stored in SavedState

This also sets values for any active LiveDatas or StateFlows.

Parameters
@NonNull String key

a key used to associate with the given value.
T value

object of any type that can be accepted by Bundle.
Throws
kotlin.IllegalArgumentException

value cannot be saved in saved state

setSavedStateProvider

Added in 2.3.0
@MainThread
public final void setSavedStateProvider(
    @NonNull String key,
    @NonNull SavedStateRegistry.SavedStateProvider provider
)

Set a SavedStateProvider that will have its state saved into this SavedStateHandle. This provides a mechanism to lazily provide the SavedState of saved state for the given key.

Calls to get with this same key will return the previously saved state as a SavedState if it exists.

Bundle previousState = savedStateHandle.get("custom_object");
if (previousState != null) {
    // Convert the previousState into your custom object
}
savedStateHandle.setSavedStateProvider("custom_object", () -> {
    Bundle savedState = new Bundle();
    // Put your custom object into the Bundle, doing any conversion required
    return savedState;
});

Note: calling this method within SavedStateProvider.saveState is supported, but will only affect future state saving operations.

Parameters
@NonNull String key

a key which will populated with a SavedState produced by the provider
@NonNull SavedStateRegistry.SavedStateProvider provider

a SavedStateProvider which will receive a callback to SavedStateProvider.saveState when the state should be saved

Extension functions

SavedStateHandleDelegatesKt.saved

public final @NonNull ReadWriteProperty<Object, @NonNull T> <T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with fully qualified property or variable name as key and the default serializer.

import androidx.lifecycle.serialization.saved

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by savedStateHandle.saved { User(123, "foo") }
}
Parameters
@NonNull Function0<@NonNull T> init

The function to provide the initial value of the property.
Returns
@NonNull ReadWriteProperty<Object, @NonNull T>

A property delegate that manages the saving and restoring of the value.

SavedStateHandleDelegatesKt.saved

public final @NonNull ReadWriteProperty<Object, @NonNull T> <T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull String key,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with the default serializer.

import androidx.lifecycle.serialization.saved

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by savedStateHandle.saved(key = "bar") { User(123, "foo") }
}
Parameters
@NonNull String key

The String key to use for storing the value in the SavedStateHandle.
@NonNull Function0<@NonNull T> init

The function to provide the initial value of the property.
Returns
@NonNull ReadWriteProperty<Object, @NonNull T>

A property delegate that manages the saving and restoring of the value.

SavedStateHandleDelegatesKt.saved

public final @NonNull ReadWriteProperty<Object, @NonNull T> <T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull <Error class: unknown class><@NonNull T> serializer,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with fully qualified property or variable name as key.

import androidx.lifecycle.serialization.saved

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by savedStateHandle.saved(User::class.serializer()) { User(123, "foo") }
}
Parameters
@NonNull <Error class: unknown class><@NonNull T> serializer

The KSerializer to use for serializing and deserializing the value.
@NonNull Function0<@NonNull T> init

The function to provide the initial value of the property.
Returns
@NonNull ReadWriteProperty<Object, @NonNull T>

A property delegate that manages the saving and restoring of the value.

SavedStateHandleDelegatesKt.saved

public final @NonNull ReadWriteProperty<Object, @NonNull T> <T extends Object> SavedStateHandleDelegatesKt.saved(
    @NonNull SavedStateHandle receiver,
    @NonNull String key,
    @NonNull <Error class: unknown class><@NonNull T> serializer,
    @NonNull Function0<@NonNull T> init
)

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T.

import androidx.lifecycle.serialization.saved

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by
        savedStateHandle.saved(key = "bar", serializer = User::class.serializer()) {
            User(123, "foo")
        }
}
Parameters
@NonNull String key

The String key to use for storing the value in the SavedStateHandle.
@NonNull <Error class: unknown class><@NonNull T> serializer

The KSerializer to use for serializing and deserializing the value.
@NonNull Function0<@NonNull T> init

The function to provide the initial value of the property.
Returns
@NonNull ReadWriteProperty<Object, @NonNull T>

A property delegate that manages the saving and restoring of the value.

SavedStateHandleKt.toRoute

public final @NonNull T <T extends Object> SavedStateHandleKt.toRoute(
    @NonNull SavedStateHandle receiver,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap
)

Returns route as an object of type T

Extrapolates arguments from SavedStateHandle and recreates object T

Parameters
<T extends Object>

the entry's NavDestination.route as a KClass
@NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap

A mapping of KType to custom NavType<*> in T. May be empty if T does not use custom NavTypes.
Returns
@NonNull T

A new instance of this entry's NavDestination.route as an object of type T

SavedStateHandleKt.toRoute

public final @NonNull T <T extends Object> SavedStateHandleKt.toRoute(
    @NonNull SavedStateHandle receiver,
    @NonNull KClass<@NonNull T> route,
    @NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap
)

Returns route as an object of type T

Extrapolates arguments from SavedStateHandle and recreates object T

Parameters
@NonNull KClass<@NonNull T> route

the entry's NavDestination.route as a KClass
@NonNull Map<@NonNull KType, @NonNull NavType<@NonNull ?>> typeMap

A mapping of KType to custom NavType<*> in T. May be empty if T does not use custom NavTypes.
Returns
@NonNull T

A new instance of this entry's NavDestination.route as an object of type T