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

This function is deprecated. LifecycleResumeEffect must provide one or more 'key' parameters that define the identity of the LifecycleResumeEffect and determine when its previous effect coroutine should be cancelled and a new effect launched for the new key.

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

This function is deprecated. LifecycleStartEffect must provide one or more 'key' parameters that define the identity of the LifecycleStartEffect and determine when its previous effect coroutine should be cancelled and a new effect launched for the new key.

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).

() -> Unit
@Composable
dropUnlessResumed(lifecycleOwner: LifecycleOwner, block: () -> Unit)

Returns a new decorated function that will invoke the given block if the lifecycleOwner's lifecycle state is at least State.RESUMED.

() -> Unit
@Composable
dropUnlessStarted(lifecycleOwner: LifecycleOwner, block: () -> Unit)

Returns a new decorated function that will invoke the given block if the lifecycleOwner's lifecycle state is at least State.STARTED.

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 properties summary

ProvidableCompositionLocal<LifecycleOwner>

The CompositionLocal containing the current LifecycleOwner.

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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
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(
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit

It is an error to call LifecycleStartEffect without at least one key parameter.

This deprecated-error function shadows the varargs overload so that the varargs version is not used without key parameters.

@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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect(dataAnalytics) {
        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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect(dataAnalytics) {
        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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect(dataAnalytics) {
        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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleResumeEffect(dataAnalytics) {
        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(
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit

It is an error to call LifecycleStartEffect without at least one key parameter.

This deprecated-error function shadows the varargs overload so that the varargs version is not used without key parameters.

@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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect(dataAnalytics) {
        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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect(dataAnalytics) {
        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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect(dataAnalytics) {
        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.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect

@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
    LifecycleStartEffect(dataAnalytics) {
        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

@Composable
fun dropUnlessResumed(
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    block: () -> Unit
): () -> Unit

Returns a new decorated function that will invoke the given block if the lifecycleOwner's lifecycle state is at least State.RESUMED. Otherwise, block is not invoked.

For Navigation users, it's recommended to safeguard navigate methods when using them while a composable is in transition as a result of navigation.

import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.lifecycle.compose.dropUnlessResumed

Button(
    onClick = dropUnlessResumed {
        // Run on clicks only when the lifecycle is at least RESUMED.
        // Example: navController.navigate("next_screen")
    },
) {
    Text(text = "Navigate to next screen")
}
Parameters
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The LifecycleOwner whose lifecycle will be observed. Defaults to the current LocalLifecycleOwner.

block: () -> Unit

The callback to be executed when the observed lifecycle state is at least State.RESUMED.

Returns
() -> Unit

A decorated function that invoke block only if the lifecycle state is at least State.RESUMED.

@Composable
fun dropUnlessStarted(
    lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
    block: () -> Unit
): () -> Unit

Returns a new decorated function that will invoke the given block if the lifecycleOwner's lifecycle state is at least State.STARTED. Otherwise, block is not invoked.

import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.lifecycle.compose.dropUnlessStarted

Button(
    onClick = dropUnlessStarted {
        // Run on clicks only when the lifecycle is at least STARTED.
        // Example: navController.navigate("next_screen")
    },
) {
    Text(text = "Navigate to next screen")
}
Parameters
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current

The LifecycleOwner whose lifecycle will be observed. Defaults to the current LocalLifecycleOwner.

block: () -> Unit

The callback to be executed when the observed lifecycle state is at least State.STARTED.

Returns
() -> Unit

A decorated function that invoke block only if the lifecycle state is at least State.STARTED.

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.Lifecycle
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.Lifecycle
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.Lifecycle
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.Lifecycle
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.

Top-level properties

val LocalLifecycleOwnerProvidableCompositionLocal<LifecycleOwner>

The CompositionLocal containing the current LifecycleOwner.