# FlowExtKt

Added in 2.8.0

*** ** * ** ***

<br />

```
public final class FlowExtKt
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/lifecycle/FlowExtKt#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)( @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/Lifecycle lifecycle, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State minActiveState )` Flow operator that emits values from `this` upstream Flow when the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` is at least at `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` state. |

## Public methods

### flowWithLifecycle

Artifact: [androidx.lifecycle:lifecycle-runtime](https://developer.android.com/jetpack/androidx/releases/lifecycle) [View Source](https://cs.android.com/search?q=file:androidx/lifecycle/FlowExt.kt+function:flowWithLifecycle)

```
public static final @NonNull Flow<@NonNull T> <T extends Object> flowWithLifecycle(
    @NonNull Flow<@NonNull T> receiver,
    @NonNull Lifecycle lifecycle,
    @NonNull Lifecycle.State minActiveState
)
```

Flow operator that emits values from `this` upstream Flow when the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` is at least at `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` state. The emissions will be stopped when the lifecycle state falls below `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` state.

The flow will automatically start and cancel collecting from `this` upstream flow as the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` moves in and out of the target state.

If `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` upstream Flow completes emitting items, `flowWithLifecycle` will trigger the flow collection again when the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` state is reached.

This is NOT a terminal operator. This operator is usually followed by `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/collect.html`, or `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/index.html` and `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/index.html` to process the emitted values.

Note: this operator creates a hot flow that only closes when the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` is destroyed or the coroutine that collects from the flow is cancelled.

```
class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        /* ... */
        // Launches a coroutine that collects items from a flow when the Activity
        // is at least started. It will automatically cancel when the activity is stopped and
        // start collecting again whenever it's started again.
        lifecycleScope.launch {
            flow
                .flowWithLifecycle(lifecycle, Lifecycle.State.STARTED)
                .collect {
                    // Consume flow emissions
                 }
        }
    }
}
```

`flowWithLifecycle` cancels the upstream Flow when `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` falls below `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` state. However, the downstream Flow will be active without receiving any emissions as long as the scope used to collect the Flow is active. As such, please take care when using this function in an operator chain, as the order of the operators matters. For example, `flow1.flowWithLifecycle(lifecycle).combine(flow2)` behaves differently than `flow1.combine(flow2).flowWithLifecycle(lifecycle)`. The former continues to combine both flows even when `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` falls below `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` state whereas the combination is cancelled in the latter case.

Warning: `https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State#INITIALIZED` is not allowed in this API. Passing it as a parameter will throw an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

Tip: If multiple flows need to be collected using `flowWithLifecycle`, consider using the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(androidx.lifecycle.Lifecycle).repeatOnLifecycle(androidx.lifecycle.Lifecycle.State,kotlin.coroutines.SuspendFunction1)` API to collect from all of them using a different `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/index.html` per flow instead. That's more efficient and consumes less resources as no hot flows are created.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/Lifecycle lifecycle` | The `https://developer.android.com/reference/androidx/lifecycle/Lifecycle` where the restarting collecting from `this` flow work will be kept alive. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/lifecycle/Lifecycle.State minActiveState` | `https://developer.android.com/reference/androidx/lifecycle/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. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` that only emits items from `this` upstream flow when the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)` is at least in the `https://developer.android.com/reference/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State)`. |