{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

EffectsKt

public final class EffectsKt


Summary

Public methods

static final void

This method is deprecated. DisposableEffect must provide one or more 'key' parameters that define the identity of the DisposableEffect and determine when its previous effect should be disposed and a new effect started for the new key.

static final void

A side effect of composition that must run for any new unique value of key1 and must be reversed or cleaned up if key1 changes or if the DisposableEffect leaves the composition.

static final void

A side effect of composition that must run for any new unique value of keys and must be reversed or cleaned up if any keys change or if the DisposableEffect leaves the composition.

static final void

A side effect of composition that must run for any new unique value of key1 or key2 and must be reversed or cleaned up if key1 or key2 changes, or if the DisposableEffect leaves the composition.

static final void

A side effect of composition that must run for any new unique value of key1, key2 or key3 and must be reversed or cleaned up if key1, key2 or key3 changes, or if the DisposableEffect leaves the composition.

static final void

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

static final void

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext.

static final void

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext.

static final void

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext.

static final void
@Composable
@NonRestartableComposable
LaunchedEffect(
    Object key1,
    Object key2,
    Object key3,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull <Error class: unknown class>Unit> block
)

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext.

static final void

Schedule effect to run when the current composition completes successfully and applies changes.

static final @NonNull <Error class: unknown class>

Return a CoroutineScope bound to this point in the composition using the optional CoroutineContext provided by getContext.

Public methods

DisposableEffect

@Composable
@NonRestartableComposable
public static final void DisposableEffect(
    @ExtensionFunctionType @NonNull Function1<@NonNull DisposableEffectScope, @NonNull DisposableEffectResult> effect
)

A side effect of composition that must be reversed or cleaned up if the DisposableEffect leaves the composition.

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

DisposableEffect

@Composable
@NonRestartableComposable
public static final void DisposableEffect(
    Object key1,
    @ExtensionFunctionType @NonNull Function1<@NonNull DisposableEffectScope, @NonNull DisposableEffectResult> effect
)

A side effect of composition that must run for any new unique value of key1 and must be reversed or cleaned up if key1 changes or if the DisposableEffect leaves the composition.

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

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

DisposableEffect

@Composable
@NonRestartableComposable
public static final void DisposableEffect(
    Object keys,
    @ExtensionFunctionType @NonNull Function1<@NonNull DisposableEffectScope, @NonNull DisposableEffectResult> effect
)

A side effect of composition that must run for any new unique value of keys and must be reversed or cleaned up if any keys change or if the DisposableEffect leaves the composition.

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

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

DisposableEffect

@Composable
@NonRestartableComposable
public static final void DisposableEffect(
    Object key1,
    Object key2,
    @ExtensionFunctionType @NonNull Function1<@NonNull DisposableEffectScope, @NonNull DisposableEffectResult> effect
)

A side effect of composition that must run for any new unique value of key1 or key2 and must be reversed or cleaned up if key1 or key2 changes, or if the DisposableEffect leaves the composition.

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

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

DisposableEffect

@Composable
@NonRestartableComposable
public static final void DisposableEffect(
    Object key1,
    Object key2,
    Object key3,
    @ExtensionFunctionType @NonNull Function1<@NonNull DisposableEffectScope, @NonNull DisposableEffectResult> effect
)

A side effect of composition that must run for any new unique value of key1, key2 or key3 and must be reversed or cleaned up if key1, key2 or key3 changes, or if the DisposableEffect leaves the composition.

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

DisposableEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided, performing cleanup for the old operation before initializing the new. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

@Composable
fun UserProfile(userRepository: UserRepository, userRequest: UserDataRequest) {
    var userDataState by remember { mutableStateOf<UserDataState>(UserDataState.Loading) }

    // If either the repository or request change, we must cancel our old data fetch
    // and begin a new data fetch. We will cancel the current data fetch if UserProfile
    // leaves the composition.
    DisposableEffect(userRepository, userRequest) {
        val requestDisposable = userRepository.fetchUserData(
            userRequest,
            onSuccess = { response ->
                userDataState = UserDataState.UserData(response)
            },
            onError = { throwable ->
                userDataState = UserDataState.Error(throwable.message)
            }
        )

        onDispose {
            requestDisposable.dispose()
        }
    }

    // ...
}

A DisposableEffect must include an onDispose clause as the final statement in its effect block. If your operation does not require disposal it might be a SideEffect instead, or a LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to dispose for every call to effect. Both effect and dispose will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks.

LaunchedEffect

@Composable
public static final void LaunchedEffect(
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull <Error class: unknown class>Unit> block
)

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be Job.cancel when the LaunchedEffect leaves the composition.

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

LaunchedEffect

@Composable
@NonRestartableComposable
public static final void LaunchedEffect(
    Object key1,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull <Error class: unknown class>Unit> block
)

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be Job.cancel and re-launched when LaunchedEffect is recomposed with a different key1. The coroutine will be Job.cancel when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key1. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

LaunchedEffect

@Composable
@NonRestartableComposable
public static final void LaunchedEffect(
    Object keys,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull <Error class: unknown class>Unit> block
)

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be Job.cancel and re-launched when LaunchedEffect is recomposed with any different keys. The coroutine will be Job.cancel when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

LaunchedEffect

@Composable
@NonRestartableComposable
public static final void LaunchedEffect(
    Object key1,
    Object key2,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull <Error class: unknown class>Unit> block
)

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be Job.cancel and re-launched when LaunchedEffect is recomposed with a different key1 or key2. The coroutine will be Job.cancel when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

LaunchedEffect

@Composable
@NonRestartableComposable
public static final void LaunchedEffect(
    Object key1,
    Object key2,
    Object key3,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull <Error class: unknown class>Unit> block
)

When LaunchedEffect enters the composition it will launch block into the composition's CoroutineContext. The coroutine will be Job.cancel and re-launched when LaunchedEffect is recomposed with a different key1, key2 or key3. The coroutine will be Job.cancel when the LaunchedEffect leaves the composition.

This function should not be used to (re-)launch ongoing tasks in response to callback events by way of storing callback data in MutableState passed to key. Instead, see rememberCoroutineScope to obtain a CoroutineScope that may be used to launch ongoing jobs scoped to the composition in response to event callbacks.

SideEffect

@Composable
@NonRestartableComposable
public static final void SideEffect(@NonNull Function0<Unit> effect)

Schedule effect to run when the current composition completes successfully and applies changes. SideEffect can be used to apply side effects to objects managed by the composition that are not backed by snapshots so as not to leave those objects in an inconsistent state if the current composition operation fails.

effect will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running RememberObserver event callbacks. SideEffects are always run after RememberObserver event callbacks.

A SideEffect runs after every recomposition. To launch an ongoing task spanning potentially many recompositions, see LaunchedEffect. To manage an event subscription or other object lifecycle, see DisposableEffect.

rememberCoroutineScope

@Composable
public static final @NonNull <Error class: unknown class> rememberCoroutineScope(
    @DisallowComposableCalls @NonNull Function0<@NonNull CoroutineContext> getContext
)

Return a CoroutineScope bound to this point in the composition using the optional CoroutineContext provided by getContext. getContext will only be called once and the same CoroutineScope instance will be returned across recompositions.

This scope will be CoroutineScope.cancel when this call leaves the composition. The CoroutineContext returned by getContext may not contain a Job as this scope is considered to be a child of the composition.

The default dispatcher of this scope if one is not provided by the context returned by getContext will be the applying dispatcher of the composition's Recomposer.

Use this scope to launch jobs in response to callback events such as clicks or other user interaction where the response to that event needs to unfold over time and be cancelled if the composable managing that process leaves the composition. Jobs should never be launched into any coroutine scope as a side effect of composition itself. For scoped ongoing jobs initiated by composition, see LaunchedEffect.

This function will not throw if preconditions are not met, as composable functions do not yet fully support exceptions. Instead the returned scope's CoroutineScope.coroutineContext will contain a failed Job with the associated exception and will not be capable of launching child jobs.