SavedStateHandle

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
SavedStateHandle.Companion

Public constructors

Creates a handle with the empty state.
SavedStateHandle(Map<String, Object> initialState)

Creates a handle with the given initial arguments.

Public methods
final @MainThread void

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

Returns a value associated with the given key.
final @MainThread @NonNull MutableLiveData<@NonNull T>
<T extends Object> getLiveData(String key)

Returns a androidx.lifecycle.LiveData that access data associated with the given key.
final @MainThread @NonNull MutableLiveData<@NonNull T>
<T extends Object> getLiveData(String key, T initialValue)

Returns a androidx.lifecycle.LiveData that access data associated with the given key.
final @MainThread @NonNull StateFlow<@NonNull T>
<T extends Object> getStateFlow(String key, T initialValue)

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

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

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

Associate the given value with the key.
final @MainThread void

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

Public constructors

SavedStateHandle

public final SavedStateHandle()

Creates a handle with the empty state.

SavedStateHandle

public final SavedStateHandle(Map<String, Object> initialState)

Creates a handle with the given initial arguments.

Parameters
Map<String, Object> initialState

initial arguments for the SavedStateHandle

Public methods

clearSavedStateProvider

@MainThread
public final void clearSavedStateProvider(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
String key

a key previously used with setSavedStateProvider

contains

@MainThread
public final boolean contains(String key)
Parameters
String key

The identifier for the value
Returns
boolean

true if there is value associated with the given key.

get

@MainThread
public final T <T extends Object> get(String key)

Returns a value associated with the given key.

Parameters
String key

a key used to retrieve a value.

getLiveData

@MainThread
public final @NonNull MutableLiveData<@NonNull T> <T extends Object> getLiveData(String key)

Returns a androidx.lifecycle.LiveData that access data associated with the given key.

Parameters
String key

The identifier for the value
See also
getLiveData

getLiveData

@MainThread
public final @NonNull MutableLiveData<@NonNull T> <T extends Object> getLiveData(String key, T initialValue)

Returns a androidx.lifecycle.LiveData that access data associated with the given key.

`LiveData<String> liveData = savedStateHandle.get(KEY, "defaultValue");`

Keep in mind that LiveData can have null as a valid value. If the initialValue is null and the data does not already exist in the SavedStateHandle, the value of the returned LiveData will be set to null and observers will be notified. You can call getLiveData if you want to avoid dispatching null to observers.

`String defaultValue = ...; // nullable
LiveData<String> liveData;
if (defaultValue != null) {
    liveData = savedStateHandle.getLiveData(KEY, defaultValue);
} else {
    liveData = savedStateHandle.getLiveData(KEY);
}`
Parameters
String key

The identifier for the value
T initialValue

If no value exists with the given key, a new one is created with the given initialValue. Note that passing null will create a LiveData with null value.

getStateFlow

@MainThread
public final @NonNull StateFlow<@NonNull T> <T extends Object> getStateFlow(String key, 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.

Parameters
String key

The identifier for the flow
T initialValue

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

keys

@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

@MainThread
public final T <T extends Object> remove(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
String key

a key
Returns
T

a value that was previously associated with the given key.

set

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

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

This also sets values for any active LiveDatas or Flows.

Parameters
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

@MainThread
public final void setSavedStateProvider(
    String key,
    SavedStateRegistry.SavedStateProvider provider
)

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

Calls to get with this same key will return the previously saved state as a Bundle 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
String key

a key which will populated with a Bundle produced by the provider
SavedStateRegistry.SavedStateProvider provider

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