Deep-dive into Compose Side-effect APIs LaunchedEffect and rememberCoroutineScope. Exploring differences and use-cases where we should use LaunchedEffect vs rememberCoroutineScope .

It’s a detailed guide about rememberCoroutineScope and LaunchedEffect the side-effect APIs in Jetpack Compose. These APIs are tailored built to execute suspend functions in their specific use-cases which we will explore in detail in this story.

Effect Apis rememberCoroutineScope and LaunchedEffect should only be used to launch suspend functions which are performing UI related tasks.

Page Content

Overview of the page content

• What is Side-effect?
• LaunchedEffect Side-effect API
• LaunchedEffect UnderTheHood
• LaunchedEffect Example
• LaunchedEffect Applications
• rememberCoroutineScope API
• rememberCoroutineScope UnderTheHood
• rememberCoroutineScope Example
• rememberCoroutineScope Applications
• Comparison b/w LaunchedEffect & rememberCoroutineScope
• Github project

What is Side-effect?

Side-effect is anything happening out of the scope of a composable function which eventually affects the composable function, it could be some state changes or anything happening on UI like user actions which has an effect on Composable. Both APIs are built to handle that effect in a controlled environment.

First Let’s explore LaunchedEffect in detail.

LaunchedEffect Side-effect API

LaunchedEffect is a composable function and it can only be executed from another composable function. LaunchedEffect takes at least one parameter and a suspend function. It executes that suspend function via launching a coroutine within the scope of the container composable. LaunchedEffect executes that suspend function as soon as it enters the Composition the first time and when one of its passed variables changes its value. When LaunchedEffect has to execute a new suspend function due to side-effect then it cancels the previously running coroutine and launches a new one with the new suspend function. LaunchedEffect also cancels the launched coroutine when it leaves the Composition itself. Coroutine is always launched within the scope of the container composable function.

LaunchedEffect UnderTheHood

Let’s look at the one of the functions declaration for LaunchedEffect

By looking at the code above following points to recap

• LaunchedEffect is a composable function so can only be executed within another composable function
• LaunchedEffect is taking a parameter and a suspend function that must be executed
• LaunchedEffect is passing current composable coroutine context passing in to LaunchedEffectImpl with suspend function that will be executed, which shows the coroutine will be launched within the scope of the parent composable function.
• LaunchedEffectImpl takes suspend function as a block of code and lanches coroutine, canceling the previously running coroutine if it exists
• LaunchedEffect expects at least one parameter to be passed, If you don’t want to pass any parameter you can either pass null or Unit . In this case I would choose to pass Unit as parameter. If you would pass Unit or null as parameter then suspend function will be executed exactly once and that in the Composition phase.

LaunchedEffect launches coroutine with the block of code in the scope of composable functions, the executed coroutine is canceled when LaunchedEffect leaves the composition or if any of the LaunchedEffect parameter changes.

LaunchedEffect Example

Let’s look at the code example below to understand some of the characteristics of LaunchedEffect

In the code example above LaunchedEffectTestScreen composable is using LaunchedEffect to show a snackbar the first time and when the passed parameter snackbarCount changes. The corresponding viewModel code is below.

In ViewModel snackbarCount StateFlow starts with an initial value of 1. ViewModel is further launching a coroutine to update the snackbarCount StateFlow snackbarCount every second till max 3 times. As the value for snackbarCount will change LaunchedEffect will execute on every value change and a new coroutine will be launched with canceling the previous one. Log output of the above code will look like this below.

It shows the LaunchedEffect executes the coroutine with snackbarCount 1 on launch and next time it launches a new coroutine with snackbarCount value of 2, cancelling the previous one. You can see JobCancellationException in the log for coroutine 1 and 2.

LaunchedEffect Applications

LaunchedEffect is usually effective when we want to execute a UI related task (suspend function) at the start during the Composition phase. But it will also execute when the passed state parameters values change. Following are some Applications of LaunchedEffect.

1. Scrolling LazyList to a specific position: In a chat application when a user first time loads the App or chat screen we want the user to see latest messages so we will scroll the chat messages to the bottom of the list, this can be achieved with the following code below using LaunchedEffect.

LaunchedEffect(Unit, block = {
    lazyListState.scrollToItem(messages.size - 1)
})

We are passing Unit as a parameter that means we only want to call this suspend block when the first time a user enters the screen i.e during the Composition phase. As soon as the user enters the screen it will scroll to the bottom of the list.

Github Project repo having this example is mentioned below.

LoadingScreen composable is showing a full screen composable with CircularProgressIndicator in the middle of the screen to show loading state in UI. LoadingScreen is also using the Api LauncedEffect passing Unit as parameter because we want to launch the passed block only when LoadingScreen enters the screen i.e during the Composition phase. LaunchedEffect is executing suspend function which is using delay to mimic backend response ( we don’t have backend yet ) and waiting for 5 seconds to display loading screen before calling onTimeOut method.

Now we will need to change the starter code in MainActivity to add a switch for LoadingScreen as below.

In MainActivity we are remembering the boolean state storing information about when to show LoadingScreen at first it’s value is true so LoadingScreen gets called passing in lambda which is turning the showLoading flag false — this method will get called inside LaunchedEffect within LoadingScreen after 5 seconds as we saw the code before. So after 5 seconds the flag showLoading turns false and It goes into the else part showing LaunchedEffectTestScreen.

Full code is available below.

Composable is observing the state from viewModel in showNetworkUnavailable . If the value is true it will execute LaunchedEffect which is showing a snackbar message about network is not available And when value turns false then LaunchedEffect will leave Composition and cancel the coroutine launched before.

Let’s see ViewModel to see full picture.

ViewModel is mimicking the effect of Network unavailable as we do not need to implement complete Network status listeners for the sake of example. ViewModel is exposing networkUnavailable StateFlow with initial value false and in the coroutine after 2 seconds it turns networkUnavailable value to true . As the value changes after 2 seconds the composable will show a snackbar message after 2 seconds executing a suspend function within LaunchedEffect.

That’s it related to LaunchedEffect . There are many other practical applications of LaunchedEffect But hope these helped in understanding LaunchedEffect in general.

rememberCoroutineScope Side-effect API

LaunchedEffect side-effect API is helpful to call suspend functions via coroutine during the Composition phase. But there are situations where we want to do some actions but not within the Composition but rather later in time e.g when user performs some actions on the UI, for that we need a scope to launch a coroutine where rememberCoroutineScope provides a coroutine scope bound with the scope of the composable where its being called to be aware of the life-cycle of the composable and cancels when it leaves the composition. With that scope we can call coroutines when we are not in the Composition i.e we can launch coroutine out of the scope of Composable in during user actions.

rememberCoroutineScope UnderTheHood

Let’s look at the function rememberCoroutineScope.

A few points to verify as below

• rememberCoroutineScope is a composable function
• It creates a coroutine scope scoped with the current composable so it will be aware of the composable life-cycle so will be automatically canceled as composable leaves the composition.

rememberCoroutineScope Example

Let’s look at the basic example showing usage of rememberCoroutineScope as in code below.

Above code is showing a Text and a Button on the screen. We are taking a coroutine scope using rememberCoroutineScope and using it in the Button onClick event listener to launch a coroutine which increments the counter on every user button press event. onClick event listener is not in the scope of the Composition, it’s an event listener that’s why we need explicit coroutine scope to launch a coroutine outside the scope of a composable but it is scoped with the composable life-cycle.

rememberCoroutineScope Applications

There are many practical applications of rememberCoroutineScope . We will see some Applications which I have already used.

1. LazyList with Go to Top/Bottom Buttons: There are usually scenarios where we have a list of data and buttons on the UI in order to scroll that list content to the Bottom or to the Top when the user performs those particular actions. Below code shows that case using rememberCoroutineScope and launching coroutine to execute those suspend functions on the LazyList.

2. ViewPager with Next and Prev Buttons: To scroll ViewPager on Next and Prev buttons actions is also an ideal application of rememberCoroutineScope as shown in code below.

Full code for the ViewPager Implementation example is below.

This article was previously published on proandroiddev.com