Google is committed to advancing racial equity for Black communities. See how.

androidx.compose.runtime.savedinstancestate

Interfaces

Saver

The Saver describes how the object of Original class can be simplified and converted into something which is Saveable.

SaverScope

Scope used in Saver.save.

UiSavedStateRegistry

Allows components to save and restore their state using the saved instance state mechanism.

Top-level functions summary

Saver<Original, Saveable>
Saver(save: SaverScope.(value: Original) -> Saveable?, restore: (value: Saveable) -> Original?)

The Saver describes how the object of Original class can be simplified and converted into something which is Saveable.

UiSavedStateRegistry
UiSavedStateRegistry(restoredValues: Map<String, List<Any?>>?, canBeSaved: (Any) -> Boolean)

Creates UiSavedStateRegistry.

Saver<T, Any>

The default implementation of Saver which does not perform any conversion.

Saver<Original, Any>
listSaver(save: SaverScope.(value: Original) -> List<Saveable>, restore: (list: List<Saveable>) -> Original?)

The Saver implementation which allows to represent your Original class as a list of Saveable values.

Saver<T, Any>
mapSaver(save: SaverScope.(value: T) -> Map<String, Any>, restore: (Map<String, Any>) -> T?)

The Saver implementation which allows to represent your class as a map of values which can be saved individually.

T
rememberSavedInstanceState(vararg inputs: Any?, saver: Saver<T, out Any> = autoSaver(), key: String? = null, init: () -> T)

Remember the value produced by init.

MutableState<T>
savedInstanceState(vararg inputs: Any?, saver: Saver<T, out Any> = autoSaver(), key: String? = null, policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(), init: () -> T)

Used to introduce a state value of type T into a composition.

Top-level properties summary

ProvidableAmbient<UiSavedStateRegistry?>

Ambient with a current UiSavedStateRegistry instance.

Top-level functions

Saver

fun <Original, Saveable : Any> Saver(
    save: SaverScope.(value: Original) -> Saveable?,
    restore: (value: Saveable) -> Original?
): Saver<Original, Saveable>

The Saver describes how the object of Original class can be simplified and converted into something which is Saveable.

What types can be saved is defined by UiSavedStateRegistry, by default everything which can be stored in the Bundle class can be saved. The implementations can check that the provided value can be saved via SaverScope.canBeSaved

You can pass the implementations of this class as a parameter for savedInstanceState or rememberSavedInstanceState.

import androidx.compose.runtime.savedinstancestate.Saver

data class Holder(var value: Int)

// this Saver implementation converts Holder object which we don't know how to save
// to Int which we can save
val HolderSaver = Saver<Holder, Int>(
    save = { it.value },
    restore = { Holder(it) }
)
Parameters
save: SaverScope.(value: Original) -> Saveable? Defines how to convert the value into a saveable one. If null is returned the value will not be saved.
restore: (value: Saveable) -> Original? Defines how to convert the restored value back to the original Class. If null is returned the value will not be restored and would be initialized again instead.

UiSavedStateRegistry

fun UiSavedStateRegistry(
    restoredValues: Map<String, List<Any?>>?,
    canBeSaved: (Any) -> Boolean
): UiSavedStateRegistry

Creates UiSavedStateRegistry.

Parameters
restoredValues: Map<String, List<Any?>>? The map of the restored values
canBeSaved: (Any) -> Boolean Function which returns true if the given value can be saved by the registry

autoSaver

fun <T> autoSaver(): Saver<T, Any>

The default implementation of Saver which does not perform any conversion.

It is used by savedInstanceState and rememberSavedInstanceState by default.

See Also

listSaver

fun <Original : Any, Saveable : Any> listSaver(
    save: SaverScope.(value: Original) -> List<Saveable>,
    restore: (list: List<Saveable>) -> Original?
): Saver<Original, Any>

The Saver implementation which allows to represent your Original class as a list of Saveable values.

What types can be saved is defined by UiSavedStateRegistry, by default everything which can be stored in the Bundle class can be saved.

You can use it as a parameter for savedInstanceState or rememberSavedInstanceState.

import androidx.compose.runtime.savedinstancestate.listSaver

data class Size(val x: Int, val y: Int)

val sizeSaver = listSaver<Size, Int>(
    save = { listOf(it.x, it.y) },
    restore = { Size(it[0], it[1]) }
)

mapSaver

fun <T : Any> mapSaver(
    save: SaverScope.(value: T) -> Map<String, Any>,
    restore: (Map<String, Any>) -> T?
): Saver<T, Any>

The Saver implementation which allows to represent your class as a map of values which can be saved individually.

What types can be saved is defined by UiSavedStateRegistry, by default everything which can be stored in the Bundle class can be saved.

You can use it as a parameter for savedInstanceState or rememberSavedInstanceState.

import androidx.compose.runtime.savedinstancestate.mapSaver

data class User(val name: String, val age: Int)

val userSaver = run {
    val nameKey = "Name"
    val ageKey = "Age"
    mapSaver(
        save = { mapOf(nameKey to it.name, ageKey to it.age) },
        restore = { User(it[nameKey] as String, it[ageKey] as Int) }
    )
}

rememberSavedInstanceState

@Composable fun <T : Any> rememberSavedInstanceState(
    vararg inputs: Any?,
    saver: Saver<T, out Any> = autoSaver(),
    key: String? = null,
    init: () -> T
): T

Remember the value produced by init.

It behaves similarly to remember, but the stored value will survive the activity or process recreation using the saved instance state mechanism (for example it happens when the screen is rotated in the Android application).

import androidx.compose.runtime.savedinstancestate.rememberSavedInstanceState

val list = rememberSavedInstanceState { mutableListOf<Int>() }

This function works nicely with mutable objects, when you update the state of this object instead of recreating it. If you work with immutable objects savedInstanceState can suit you more as it wraps the value into the MutableState.

If you use it with types which can be stored inside the Bundle then it will be saved and restored automatically using autoSaver, otherwise you will need to provide a custom Saver implementation via the saver param.

import androidx.compose.runtime.savedinstancestate.Saver

data class Holder(var value: Int)

// this Saver implementation converts Holder object which we don't know how to save
// to Int which we can save
val HolderSaver = Saver<Holder, Int>(
    save = { it.value },
    restore = { Holder(it) }
)
Parameters
vararg inputs: Any? A set of inputs such that, when any of them have changed, will cause the state to reset and init to be rerun
saver: Saver<T, out Any> = autoSaver() The Saver object which defines how the state is saved and restored.
key: String? = null An optional key to be used as a key for the saved value. If not provided we use the automatically generated by the Compose runtime which is unique for the every exact code location in the composition tree
init: () -> T A factory function to create the initial value of this state

savedInstanceState

@Composable fun <T> savedInstanceState(
    vararg inputs: Any?,
    saver: Saver<T, out Any> = autoSaver(),
    key: String? = null,
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(),
    init: () -> T
): MutableState<T>

Used to introduce a state value of type T into a composition.

It behaves similarly to remember { mutableStateOf(...) }, but the stored value will survive the activity or process recreation using the saved instance state mechanism (for example it happens when the screen is rotated in the Android application).

import androidx.compose.runtime.savedinstancestate.savedInstanceState

var value by savedInstanceState { "value" }

This function works nicely with immutable values as we wrap them into MutableState and update the values in this state. If you work with a mutable object and going to update the state of this object instead of recreating it rememberSavedInstanceState can suit you more.

If you use it with types which can be stored inside the Bundle then it will be saved and restored automatically using autoSaver, otherwise you will need to provide a custom Saver implementation via the saver param.

import androidx.compose.runtime.savedinstancestate.Saver

data class Holder(var value: Int)

// this Saver implementation converts Holder object which we don't know how to save
// to Int which we can save
val HolderSaver = Saver<Holder, Int>(
    save = { it.value },
    restore = { Holder(it) }
)
Parameters
vararg inputs: Any? A set of inputs such that, when any of them have changed, will cause the state to reset and init to be rerun
saver: Saver<T, out Any> = autoSaver() The Saver object which defines how the state is saved and restored.
key: String? = null An optional key to be used as a key for the saved value. If not provided we use the automatically generated by the Compose runtime which is unique for the every exact code location in the composition tree
policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy() a callback to compare the previous and new instance of T when MutableState.value is written to. The policy is used to determine how composition should be scheduled. See SnapshotMutationPolicy.
init: () -> T A factory function to create the initial value of this state

Top-level properties

UiSavedStateRegistryAmbient

val UiSavedStateRegistryAmbient: ProvidableAmbient<UiSavedStateRegistry?>

Ambient with a current UiSavedStateRegistry instance.