androidx.lifecycle.compose

Interfaces

LifecyclePauseOrDisposeEffectResult

Interface used for LifecycleResumeEffect to run the effect within the onPauseOrDispose clause when an (ON_PAUSE)Lifecycle.Event.ON_PAUSE event is received or when cleanup is

LifecycleStopOrDisposeEffectResult

Interface used for LifecycleStartEffect to run the effect within the onStopOrDispose clause when an (ON_STOP)Lifecycle.Event.ON_STOP event is received or when cleanup is needed for the work that was kicked off in the ON_START effect.

Classes

LifecycleResumePauseEffectScope

Receiver scope for LifecycleResumeEffect that offers the onPauseOrDispose clause to couple the ON_RESUME effect.

LifecycleStartStopEffectScope

Receiver scope for LifecycleStartEffect that offers the onStopOrDispose clause to couple the ON_START effect.

Top-level functions summary

Unit
@Composable
LifecycleEventEffect(
    event: Lifecycle.Event,
    lifecycleOwner: LifecycleOwner,
    onEvent: () -> Unit
)

Schedule an effect to run when the Lifecycle receives a specific Lifecycle.Event.

Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1).

Unit
@Composable
LifecycleResumeEffect(
    vararg keys: Any?,
    lifecycleOwner: LifecycleOwner,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
)

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of keys).

Unit
@Composable
LifecycleResumeEffect(
    key1: Any?,
    key2: Any?,
    lifecycleOwner: LifecycleOwner,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
)

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1 or key2).

Unit
@Composable
LifecycleResumeEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    lifecycleOwner: LifecycleOwner,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
)

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1 or key2 or key3).

Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1).

Unit
@Composable
LifecycleStartEffect(
    vararg keys: Any?,
    lifecycleOwner: LifecycleOwner,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
)

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of keys).

Unit
@Composable
LifecycleStartEffect(
    key1: Any?,
    key2: Any?,
    lifecycleOwner: LifecycleOwner,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
)

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1 or key2).

Unit
@Composable
LifecycleStartEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    lifecycleOwner: LifecycleOwner,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
)

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1 or key2 or key3).

Extension functions summary

State<T>
@Composable
<T : Any?> StateFlow<T>.collectAsStateWithLifecycle(
    lifecycle: Lifecycle,
    minActiveState: Lifecycle.State,
    context: CoroutineContext
)

Collects values from this StateFlow and represents its latest value via State in a lifecycle-aware manner.

State<T>
@Composable
<T : Any?> StateFlow<T>.collectAsStateWithLifecycle(
    lifecycleOwner: LifecycleOwner,
    minActiveState: Lifecycle.State,
    context: CoroutineContext
)

Collects values from this StateFlow and represents its latest value via State in a lifecycle-aware manner.

State<T>
@Composable
<T : Any?> Flow<T>.collectAsStateWithLifecycle(
    initialValue: T,
    lifecycle: Lifecycle,
    minActiveState: Lifecycle.State,
    context: CoroutineContext
)

Collects values from this Flow and represents its latest value via State in a lifecycle-aware manner.

State<T>
@Composable
<T : Any?> Flow<T>.collectAsStateWithLifecycle(
    initialValue: T,
    lifecycleOwner: LifecycleOwner,
    minActiveState: Lifecycle.State,
    context: CoroutineContext
)

Collects values from this Flow and represents its latest value via State in a lifecycle-aware manner.

State<Lifecycle.State>

Collects values from the Lifecycle.currentStateFlow and represents its latest value via State.

Top-level functions

LifecycleEventEffect

@Composable
fun LifecycleEventEffect(
    event: Lifecycle.Event,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    onEvent: () -> Unit
): Unit

Schedule an effect to run when the Lifecycle receives a specific Lifecycle.Event.

Using a LifecycleEventObserver to listen for when LifecycleEventEffect enters the composition, onEvent will be launched when receiving the specified event.

This function should not be used to listen for Lifecycle.Event.ON_DESTROY because Compose stops recomposing after receiving a Lifecycle.Event.ON_STOP and will never be aware of an ON_DESTROY to launch onEvent.

This function should also not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

import androidx.lifecycle.compose.LifecycleEventEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleEventEffect(Lifecycle.Event.ON_RESUME) {
        dataAnalytics.trackScreenView("screen1")
    }

    // ...
}
Parameters
event: Lifecycle.Event

The Lifecycle.Event to listen for

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

onEvent: () -> Unit

The effect to be launched when we receive an event callback

Throws
kotlin.IllegalArgumentException

if attempting to listen for Lifecycle.Event.ON_DESTROY

@Composable
fun LifecycleResumeEffect(
    key1: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:

LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here

onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onPauseOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.

A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
key1: Any?

The unique value to trigger recomposition upon change

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleResumeEffect(
    vararg keys: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of keys). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:

LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here

onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onPauseOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.

A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
vararg keys: Any?

The unique values to trigger recomposition upon changes

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleResumeEffect(
    key1: Any?,
    key2: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1 or key2). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:

LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here

onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onPauseOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.

A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
key1: Any?

A unique value to trigger recomposition upon change

key2: Any?

A unique value to trigger recomposition upon change

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleResumeEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1 or key2 or key3). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:

LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here

onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onPauseOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.

A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
key1: Any?

A unique value to trigger recomposition upon change

key2: Any?

A unique value to trigger recomposition upon change

key3: Any?

A unique value to trigger recomposition upon change

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleStartEffect(
    key1: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:

LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here

onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onStopOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.

A LifecycleStartEffect's key is a value that defines the identity of the effect. If the key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
key1: Any?

The unique value to trigger recomposition upon change

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleStartEffect(
    vararg keys: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of keys). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:

LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here

onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onStopOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.

A LifecycleStartEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
vararg keys: Any?

The unique values to trigger recomposition upon changes

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleStartEffect(
    key1: Any?,
    key2: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1 or key2). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:

LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here

onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onStopOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.

A LifecycleStartEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
key1: Any?

A unique value to trigger recomposition upon change

key2: Any?

A unique value to trigger recomposition upon change

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

@Composable
fun LifecycleStartEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit

Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1 or key2 or key3). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:

LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here

onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect {
        val timeTracker = dataAnalytics.startTimeTracking()

        onStopOrDispose {
            timeTracker.stopTimeTracking()
        }
    }

    // ...
}

A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.

A LifecycleStartEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:

  • Observable objects that the effect subscribes to

  • Unique request parameters to an operation that must cancel and retry if those parameters change

This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.

This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.

Parameters
key1: Any?

The unique value to trigger recomposition upon change

key2: Any?

The unique value to trigger recomposition upon change

key3: Any?

The unique value to trigger recomposition upon change

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The lifecycle owner to attach an observer

effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult

The effects to be launched when we receive the respective event callbacks

Extension functions

collectAsStateWithLifecycle

@Composable
fun <T : Any?> StateFlow<T>.collectAsStateWithLifecycle(
    lifecycle: Lifecycle,
    minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
    context: CoroutineContext = EmptyCoroutineContext
): State<T>

Collects values from this StateFlow and represents its latest value via State in a lifecycle-aware manner.

The StateFlow.value is used as an initial value. Every time there would be new value posted into the StateFlow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycle is at least minActiveState.

This StateFlow is collected every time lifecycle reaches the minActiveState Lifecycle state. The collection stops when lifecycle falls below minActiveState.

import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.compose.collectAsStateWithLifecycle

class ExampleState {
    private val _uiState = MutableStateFlow("")
    val uiState: StateFlow<String> = _uiState.asStateFlow()
}

val state = remember { ExampleState() }

val uiState by state.uiState.collectAsStateWithLifecycle()
Text(text = uiState)

Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.

Parameters
lifecycle: Lifecycle

Lifecycle used to restart collecting this flow.

minActiveState: Lifecycle.State = Lifecycle.State.STARTED

Lifecycle.State in which the upstream flow gets collected. The collection will stop if the lifecycle falls below that state, and will restart if it's in that state again.

context: CoroutineContext = EmptyCoroutineContext

CoroutineContext to use for collecting.

collectAsStateWithLifecycle

@Composable
fun <T : Any?> StateFlow<T>.collectAsStateWithLifecycle(
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
    context: CoroutineContext = EmptyCoroutineContext
): State<T>

Collects values from this StateFlow and represents its latest value via State in a lifecycle-aware manner.

The StateFlow.value is used as an initial value. Every time there would be new value posted into the StateFlow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycleOwner's lifecycle is at least minActiveState.

This StateFlow is collected every time the lifecycleOwner's lifecycle reaches the minActiveState Lifecycle state. The collection stops when the lifecycleOwner's lifecycle falls below minActiveState.

import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.compose.collectAsStateWithLifecycle

class ExampleState {
    private val _uiState = MutableStateFlow("")
    val uiState: StateFlow<String> = _uiState.asStateFlow()
}

val state = remember { ExampleState() }

val uiState by state.uiState.collectAsStateWithLifecycle()
Text(text = uiState)

Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.

Parameters
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

LifecycleOwner whose lifecycle is used to restart collecting this flow.

minActiveState: Lifecycle.State = Lifecycle.State.STARTED

Lifecycle.State in which the upstream flow gets collected. The collection will stop if the lifecycle falls below that state, and will restart if it's in that state again.

context: CoroutineContext = EmptyCoroutineContext

CoroutineContext to use for collecting.

collectAsStateWithLifecycle

@Composable
fun <T : Any?> Flow<T>.collectAsStateWithLifecycle(
    initialValue: T,
    lifecycle: Lifecycle,
    minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
    context: CoroutineContext = EmptyCoroutineContext
): State<T>

Collects values from this Flow and represents its latest value via State in a lifecycle-aware manner.

Every time there would be new value posted into the Flow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycle is at least minActiveState.

This Flow is collected every time lifecycle reaches the minActiveState Lifecycle state. The collection stops when lifecycle falls below minActiveState.

import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.compose.collectAsStateWithLifecycle

class ExampleState {
    val counter = flow {
        var count = 0
        while (true) {
            emit(count++)
            delay(1000)
        }
    }
}

val state = remember { ExampleState() }
val count by state.counter.collectAsStateWithLifecycle(initialValue = 0)
Text(text = "$count")

Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.

Parameters
initialValue: T

The initial value given to the returned State.value.

lifecycle: Lifecycle

Lifecycle used to restart collecting this flow.

minActiveState: Lifecycle.State = Lifecycle.State.STARTED

Lifecycle.State in which the upstream flow gets collected. The collection will stop if the lifecycle falls below that state, and will restart if it's in that state again.

context: CoroutineContext = EmptyCoroutineContext

CoroutineContext to use for collecting.

collectAsStateWithLifecycle

@Composable
fun <T : Any?> Flow<T>.collectAsStateWithLifecycle(
    initialValue: T,
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
    context: CoroutineContext = EmptyCoroutineContext
): State<T>

Collects values from this Flow and represents its latest value via State in a lifecycle-aware manner.

Every time there would be new value posted into the Flow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycleOwner's lifecycle is at least minActiveState.

This Flow is collected every time the lifecycleOwner's lifecycle reaches the minActiveState Lifecycle state. The collection stops when the lifecycleOwner's lifecycle falls below minActiveState.

import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.compose.collectAsStateWithLifecycle

class ExampleState {
    val counter = flow {
        var count = 0
        while (true) {
            emit(count++)
            delay(1000)
        }
    }
}

val state = remember { ExampleState() }
val count by state.counter.collectAsStateWithLifecycle(initialValue = 0)
Text(text = "$count")

Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.

Parameters
initialValue: T

The initial value given to the returned State.value.

lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

LifecycleOwner whose lifecycle is used to restart collecting this flow.

minActiveState: Lifecycle.State = Lifecycle.State.STARTED

Lifecycle.State in which the upstream flow gets collected. The collection will stop if the lifecycle falls below that state, and will restart if it's in that state again.

context: CoroutineContext = EmptyCoroutineContext

CoroutineContext to use for collecting.

currentStateAsState

@Composable
fun Lifecycle.currentStateAsState(): State<Lifecycle.State>

Collects values from the Lifecycle.currentStateFlow and represents its latest value via State. The StateFlow.value is used as an initial value. Every time there would be new value posted into the StateFlow the returned State will be updated causing recomposition of every State.value usage.