androidx.appstate.transform

Interfaces

DisposableState

A State that can be disposed to stop its underlying state transformation.

Cmn
TransformScope

A scope for launching state transformations via launchTransform.

Cmn

Classes

RunnableTransformScope

A TransformScope that manages a shared headless Composition and requires calling run to execute state transformations created via launchTransform.

Cmn

Composables

transform

A Composable transform that remembers the resulting State and ties the headless composition to the current CoroutineScope provided by the Compose lifecycle.

Cmn

Top-level functions summary

suspend Unit
listener(dispatcher: CoroutineDispatcher, onUpdate: @Composable () -> Unit)

Suspend function that executes a Composable onUpdate block in a headless Composition.

Cmn
State<R>
<R : Any?> transform(
    initialValue: R,
    scope: CoroutineScope,
    container: SavedStateContainer,
    dispatcher: CoroutineDispatcher,
    onUpdate: @Composable (R) -> R
)

This is a convenience function for TransformScope.launchTransform that runs the transform within the given CoroutineScope.

Cmn

Top-level functions

suspend fun listener(
    dispatcher: CoroutineDispatcher = Dispatchers.Default,
    onUpdate: @Composable () -> Unit
): Unit

Suspend function that executes a Composable onUpdate block in a headless Composition.

This function bridges reactive Compose state (or Flows collected as state) into a continuously updated State object outside of a traditional Compose UI hierarchy. The onUpdate block is automatically recomposed whenever any Compose state it reads is updated.

Parameters
dispatcher: CoroutineDispatcher = Dispatchers.Default

The CoroutineDispatcher thread this listener should run on.

onUpdate: @Composable () -> Unit

The Composable block that will be recomposed when its state dependencies change.

fun <R : Any?> transform(
    initialValue: R,
    scope: CoroutineScope,
    container: SavedStateContainer = SavedStateContainer(),
    dispatcher: CoroutineDispatcher = Dispatchers.Default,
    onUpdate: @Composable (R) -> R
): State<R>

This is a convenience function for TransformScope.launchTransform that runs the transform within the given CoroutineScope.

This function bridges reactive Compose state (or Flows collected as state) into a continuously updated State object outside a traditional Compose UI hierarchy. The transform block is automatically recomposed whenever any Compose state it reads is updated, and the newly returned value is pushed into the resulting State.

By default, this function uses an unattached SavedStateContainer. In order for androidx.compose.runtime.saveable.rememberSaveable inside onUpdate to work properly (saving and restoring state across configuration changes or process death), developers must provide their own SavedStateContainer, such as one obtained from SavedStateHandle.getOrCreateContainer:

class MyViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
val uiState: State<Int> = transform(
initialValue = 0,
scope = viewModelScope,
container = savedStateHandle.getOrCreateContainer("myTransform"),
) {
var count by rememberSaveable { mutableStateOf(0) }
count
}
}

The same is also possible with a androidx.savedstate.SavedStateRegistry via androidx.savedstate.SavedStateRegistry.getOrCreateContainer.

Parameters
initialValue: R

The initial value to populate the returned State before the first composition completes.

scope: CoroutineScope

The CoroutineScope in which the recomposer and frame clock will run.

container: SavedStateContainer = SavedStateContainer()

The SavedStateContainer used to save and restore androidx.compose.runtime.saveable.rememberSaveable state. Developers must provide their own SavedStateContainer for rememberSaveable to persist and restore state properly.

dispatcher: CoroutineDispatcher = Dispatchers.Default

The CoroutineDispatcher thread this transform should run on.

onUpdate: @Composable (R) -> R

The Composable block that computes the value of type R.

Returns
State<R>

A State containing the latest result of the transform block.