This post is a continuation of my previous blog about the LookaheadScope API in Jetpack Compose, where I delved into various APIs and demonstrated an example animation utilizing Box layouts. If you haven’t read it yet, I strongly encourage you to do so before proceeding. The concepts covered in that post will be foundational to our discussion here.

This post aims to provide a clear and straightforward explanation of how to create a container transform animation using Lookahead APIs. In the end, we will end up creating a UX like this:

Quick recap

Let's quickly go through some points we know about LookaheadScope. These concepts are discussed in more detail in my previous article.

1. The LookaheadScope API allows us to “look ahead” and pre-calculate the size and position of the target destination while animating. It achieves that using a “lookahead pass” before the actual measure/layout pass.

2. Using these pre-calculated values, we can decide an approach logic in the “approach pass” of how to gradually reach this destination state, which will define the animation.

What is a container transform animation?

Container transform animation is a design pattern that morphs one UI container into another, often employing a shared element to bridge two UI components. It uses persistent elements to create a smooth and seamless transition between the starting and ending states.

Let’s dive into the code

In the previous article, we explored the movableContent and movableContentWithReceiverOf APIs of Jetpack Compose. The latter allows the creation of movable content within a receiver context, enabling the preservation of state while content is repositioned. We will extensively leverage this API in conjunction with LookaheadScope to create the UX described earlier.

The UX design in question consists of two main components: a top/center header card layout featuring a circle and two rounded rectangles, and a lower layout composed of four colored attribute cards, each adorned with a circle and one or two rounded rectangles. This setup is conceptual, and designed for simplicity. In practical applications, these shapes could be replaced with Image and Text composables without affecting the functionality.

Step 1: Create a custom modifier using approachLayout Modifier

As elaborated in the previous post, we will now develop a custom modifier named animateLayout by leveraging the approachLayout Modifier. The approachLayout modifier plays a crucial role during the approach pass and is utilized within LookaheadScope to delineate the method by which a composable should measure and place its content throughout the animation process.

Within the isMeasurementApproachComplete and isPlacementApproachComplete checks, we'll determine whether our measurement and placement processes have reached their intended destinations. To accomplish this, we will employ the lambda arguments lookaheadSize and lookaheadCoordinates to craft our logic. In this scenario, we're opting for a tween animation with a duration of 1800 milliseconds to slow down the animation, enhancing its visibility and allowing for a more detailed observation.

In the trailing lambda of approachMeasure, we will define an interpolation method for the animation. This interpolation will smoothly transition the measurement or placement from its previous size and position to the designated target size and position. We'll ascertain the target size using lookaheadSize, and the target position through lookaheadCoordinates and localLookaheadPositionOf.

It’s important to note that localLookaheadPositionOf is utilized for obtaining the converted offset relative to a specific position coordinate within the Lookahead coordinate space. This technique ensures that the animation transitions are smooth and precise, directly correlating the starting points to their final destinations based on the defined animation parameters.

context (LookaheadScope)
@OptIn(ExperimentalAnimatableApi::class, ExperimentalComposeUiApi::class)
fun Modifier.animateLayout(): Modifier = composed {
    val sizeAnim = remember { DeferredTargetAnimation(IntSize.VectorConverter) }
    val offsetAnim = remember { DeferredTargetAnimation(IntOffset.VectorConverter) }
    val scope = rememberCoroutineScope()
    this.approachLayout(
        isMeasurementApproachComplete = { lookaheadSize ->
            sizeAnim.updateTarget(lookaheadSize, scope, tween(1800))
            sizeAnim.isIdle
        },
        isPlacementApproachComplete = { lookaheadCoordinates ->
            val target = lookaheadScopeCoordinates.localLookaheadPositionOf(lookaheadCoordinates)
            offsetAnim.updateTarget(target.round(), scope, tween(1800))
            offsetAnim.isIdle
        }
    ) { measurable, _ ->
        val (animWidth, animHeight) = sizeAnim.updateTarget(lookaheadSize, scope)
        measurable.measure(Constraints.fixed(animWidth, animHeight))
            .run {
                layout(width, height) {
                    coordinates?.let {
                        val target = lookaheadScopeCoordinates.localLookaheadPositionOf(it).round()
                        val animOffset = offsetAnim.updateTarget(target, scope)
                        val current = lookaheadScopeCoordinates.localPositionOf(it, Offset.Zero).round()
                        val (x, y) = animOffset - current
                        place(x, y)
                    } ?: place(0, 0)
                }
            }
    }
}

After creating the animateLayout modifier, it becomes a powerful tool that we can employ to animate our UI elements in subsequent sections of the code.

Step 2: Define the parent and animation states

First, we’ll construct the top/center header card layout followed by the bottom layout. It’s crucial to recognize that the layout transitions between two states. These states switch upon tapping the screen or parent container. To manage this behavior, we’ll begin by defining our parent composable. We will also introduce a mutable Boolean state, named isExpanded, to represent the toggle state. This flag will be instrumental in controlling the animation, dictating whether the layout is in its expanded or non-expanded form based on user interaction.

@Composable
fun ContainerTransformAnimationWithLookahead() {
    var isExpanded by remember { mutableStateOf(false) }
    Surface(
        modifier = Modifier.fillMaxSize().clickable { isExpanded = !isExpanded },
        color = Color(0xFFFFFFFF)
    ) {
        // Content here
    }
}

Step 3: Define the movable contents for the header section

For the top header card view, we have 4 movable contents:

1. Header image (Circle)

2. Header title (Long rounded rectangle)

3. Header subtitle (Short rounded rectangle)

4. Header container (Card container)

For each one of these, we have to define remembered tracking composable lambdas. We will leverage movableContentWithReceiverOf with LookaheadScope for this.

Let’s do it first for the header image:

val headerImage = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier> { modifier ->
        Box(
            modifier = Modifier
                .animateLayout()
                .then(modifier)
                .drawBehind {
                    drawCircle(Color(0xFF949494))
                }
        )
    }
}

Here’s what’s happening: Each component is encapsulated within a remembered composable lambda, enabling it to be tracked. This ability to track compositions facilitates the creation of a composable that dynamically switches its content layout between a row and a column, contingent upon a specific parameter. We’ve employed the animateLayout() Modifier, introduced earlier, to generate the actual animation effect.

The LookaheadScope is utilized as the receiver context, a necessity for the animateLayout() modifier to function properly. Moreover, we've incorporated a Modifier as a parameter, allowing for external style adjustments that correspond with the layout transitions. This modifier is appended using .then(modifier) after applying animateLayout(). It's important to note that styling elements intended to remain consistent across different layout (or animated) states should be explicitly defined within this composable at the time of its creation, ensuring a seamless transition and maintaining visual coherence throughout the animation process.

Similarly, we will define the header title and subtitle:

val headerTitle = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier> { modifier ->
        Box(
            modifier = Modifier
                .animateLayout()
                .then(modifier)
                .graphicsLayer {
                    clip = true
                    shape = RoundedCornerShape(100)
                }
                .background(Color(0xFFACACAC))
        )
    }
}
val headerSubTitle = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier> { modifier ->
        Box(
            modifier = Modifier
                .animateLayout()
                .then(modifier)
                .graphicsLayer {
                    clip = true
                    shape = RoundedCornerShape(100)
                }
                .background(Color(0xFFC2C2C2))
        )
    }
}

Now, we will define the header container, which will hold the above three elements. This is a bit different from the above implementations. Let's see the code:

val headerContainer = remember {
    movableContentWithReceiverOf<LookaheadScope, @Composable () -> Unit> { content ->
        Box(
            modifier = Modifier
                .animateLayout()
                .padding(16.dp)
                .graphicsLayer {
                    clip = true
                    shape = RoundedCornerShape(10)
                }
                .background(Color(0xFFE7E7E7))
        ) {
            content()
        }
    }
}

In this scenario, everything remains consistent with the previous components, with the notable exception of the argument type: instead of a Modifier, a Composable function is used. This adjustment is made because a Modifier isn't required for this specific use case, as the card's styling remains constant across both states. Instead, what's needed is a way to pass content into this Box—specifically, the three UI elements: image, title, and subtitle. The rationale behind this approach and its practical application will become more apparent through examples showcasing its usage.

Step 4: Use the defined movable contents for the header section

Now, we will employ the movable contents defined earlier to construct two layouts, toggling between them based on the isExpanded Boolean flag. All of these operations will occur within the LookAheadScope. It's crucial to understand that without LookAheadScope, our movable contents cannot be utilized. This scope provides the necessary context for our movable content to function correctly, enabling the seamless transition between expanded and non-expanded states as dictated by the isExpanded condition.

LookaheadScope {
    Column(
        modifier = Modifier.padding(horizontal = 16.dp, vertical = 32.dp),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Box(
            modifier = Modifier.fillMaxSize().weight(if (isExpanded) 1f else 4f),
            contentAlignment = if (isExpanded) Alignment.TopStart else Alignment.Center
        ) {
            if (isExpanded) {
                headerContainer {
                    Row(
                        modifier = Modifier.padding(16.dp),
                        verticalAlignment = Alignment.CenterVertically
                    ) {
                        headerImage(Modifier.size(48.dp))
                        Spacer(Modifier.width(16.dp))
                        Column {
                            headerTitle(Modifier.height(20.dp).width(280.dp))
                            Spacer(Modifier.height(16.dp))
                            headerSubTitle(Modifier.height(20.dp).width(172.dp))
                        }
                    }
                }
            } else {
                headerContainer {
                    Column(
                        modifier = Modifier.padding(16.dp),
                        horizontalAlignment = Alignment.CenterHorizontally
                    ) {
                        headerImage(Modifier.size(120.dp))
                        Spacer(Modifier.height(32.dp))
                        headerTitle(Modifier.height(24.dp).width(280.dp))
                        Spacer(Modifier.height(16.dp))
                        headerSubTitle(Modifier.height(24.dp).width(172.dp))
                    }
                }
            }
        }
      // Remaining code of the screen to be continued here
    }
}

The provided code outlines two distinct layouts: one displaying the header card section at the top of the screen (in its expanded state) and the other showing it in the middle of the screen (in its non-expanded state). For both layouts, we’ve utilized the headerContainer as the movable content container, incorporating headerImage, headerTitle, and headerSubTitle as its contents. Additionally, we've applied specific styling to these elements using the previously defined Modifier argument.

This setup allows for dynamic styling adjustments — specifically, the width and height of the elements — based on whether the layout is in its expanded or non-expanded state, as well as its positioning. The Lookahead API is tasked with animating these changes, ensuring a smooth transition between states.

With this, we conclude the discussion on the header section.

Step 5: Define the movable contents for the attribute section

Moving on to the attribute cards section, I’ll keep the explanation brief as we’ll be applying the same concepts introduced previously.

Let’s define the movable contents for the attributes container for four colored Boxes, the image, title, and subtitle.

val attributeColors = listOf(
    Color(0xFFFF928D),
    Color(0xFFFFDB8D),
    Color(0xFFA7E5FF),
    Color(0xFFB6E67F),
)
val attributes = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier, @Composable () -> Unit> { modifier, content ->
        attributeColors.forEach { color ->
            Box(
                Modifier
                    .animateLayout()
                    .graphicsLayer {
                        clip = true
                        shape = RoundedCornerShape(10)
                    }
                    .background(color)
                    .then(modifier)
            ) {
                content()
            }
        }
    }
}
val attributeImage = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier> { modifier ->
        Box(
            modifier = Modifier
                .animateLayout()
                .then(modifier)
                .drawBehind {
                    drawCircle(Color(0x99FFFFFF))
                }
        )
    }
}
val attributeTitle = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier> { modifier ->
        Box(
            modifier = Modifier
                .animateLayout()
                .then(modifier)
                .graphicsLayer {
                    clip = true
                    shape = RoundedCornerShape(100)
                }
                .background(Color(0x99FFFFFF))
        )
    }
}
val attributeSubtitle = remember {
    movableContentWithReceiverOf<LookaheadScope, Modifier> { modifier ->
        Box(
            modifier = Modifier
                .animateLayout()
                .then(modifier)
                .graphicsLayer {
                    clip = true
                    shape = RoundedCornerShape(100)
                }
                .background(Color(0x99FFFFFF))
        )
    }
}

Note that here, for the attributes component, the movableContentWithReceiverOf takes both a Modifier and Composable content as arguments. The modifier will help us to pass styles for the Box container while using them in animation.

Step 6: Use the defined movable contents for the attributes section

Similar to what we have done previously, we will use the movable contents to define two layouts: one for the expanded state and another for the non-expanded state. Also, we will switch between them based on the isExpanded flag.

LookaheadScope {
    Column(
        modifier = Modifier.padding(horizontal = 16.dp, vertical = 32.dp),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        // Previous code for the header section
        Box(
            modifier = Modifier
                .weight(if (isExpanded) 4f else 1f)
                .padding(horizontal = 8.dp)
        ) {
            if (isExpanded) {
                Column(
                    verticalArrangement = Arrangement.spacedBy(8.dp)
                ) {
                    attributes(
                        Modifier.height(140.dp).fillMaxWidth()
                    ) {
                        Row(
                            modifier = Modifier.padding(16.dp).fillMaxSize(),
                            verticalAlignment = Alignment.CenterVertically
                        ) {
                            attributeImage(Modifier.size(64.dp))
                            Spacer(Modifier.width(16.dp))
                            Column {
                                attributeTitle(Modifier.height(20.dp).fillMaxWidth())
                                Spacer(Modifier.height(16.dp))
                                attributeSubtitle(Modifier.height(20.dp).fillMaxWidth())
                            }
                        }
                    }
                }
            } else {
                Row(
                    horizontalArrangement = Arrangement.spacedBy(8.dp)
                ) {
                    attributes(
                        Modifier.size(width = 64.dp, height = 80.dp)
                    ) {
                        Column(
                            modifier = Modifier.fillMaxSize().padding(8.dp),
                            horizontalAlignment = Alignment.CenterHorizontally
                        ) {
                            attributeImage(Modifier.size(32.dp))
                            Spacer(Modifier.height(8.dp))
                            attributeTitle(Modifier.height(16.dp).fillMaxWidth())
                        }
                    }
                }
            }
        }
    }
}

Note that here, we have omitted the attributeSubtitle in the non-expanded state. This is because we do not want it for the smaller card view in the non-expanded condition.

Also, it’s important to note that we adjusted the weight of the Box composables for header and attribute sections based on the isExpanded flag. This was important for our layouts to move up and down accordingly.

That’s it. If we run the above code now, we will see the desired animation as shared in the beginning.

We can also experiment by not omitting the attributeSubtitle rather, changing its size to 0.dp for the non-expanded state:

attributeSubtitle(Modifier.size(0.dp))

This will create an effect where the subtitle in the attributes section will shrink and disappear after animating to the non-expanded state:

The full code for this is available here.

Additional resources

If you want to learn more about how Lookahead works internally, I highly recommend this blog “Introducing LookaheadLayout” by Jorge Castillo: https://substack.com/inbox/post/64358322.

Also, the official docs for LookaheadScope: https://developer.android.com/reference/kotlin/androidx/compose/ui/layout/LookaheadScope.

And, my previous blog: Animations with Lookahead in Jetpack Compose.

Conclusion

I hope this article sheds light on the diverse possibilities that the LookaheadScope APIs can unlock. Although this API is currently experimental and subject to future changes, one thing is certain: it represents a promising tool that could significantly simplify animation in Compose development.

LookaheadLayout was first introduced in Version 1.3.0-alpha01 (see commit). Since then the API has gone through many changes. Check for some of the important changes listed at the end of this article.

As mentioned by Jaewoong Eum in this tweet: “This allows us to look ahead and calculate a new layout while allowing the actual measurement & placement of every frame to be different than the pre-calculation.” Also, Doris Liu in this tweet shared an amazing example of lookahead with movable content, which made it possible to move UI between a single-column and a double-column layout without losing their animation states.

In this article, I will try to explain the various functions and interfaces that I have explored so far in this API and then analyze an official example for animating four Box composables provided in the document.

How does it work?

Quick Overview

1. Lookahead pass: All layouts will first determine their target or destination layout. This allows a pre-calculation of the layout when it changes and use this information to measure and place layouts during each frame of the animation (next point).

2. Approach pass: Then they will run the measurement and placement approach or logic to reach the destination gradually.

3. The LookaheadScope interface creates a scope for the above two steps.

4. The measurement and placement approach in the approach pass is defined by the Modifier.approachLayout or by the ApproachLayoutModifierNode interface (creating custom approach logic in an explicit Modifier Node).

Let's understand the APIs

LookaheadScope

There is a LookaheadScope interface and a LookaheadScope composable. The interface is a receiver scope for all child layouts within the composable. It provides access to the lookaheadScopeCoordinates from any child's PlacementScope. This allows any child to convert LayoutCoordinates to the LayoutCoordinates in lookahead coordinate space using the toLookaheadCoordinates() function. This is particularly useful for animations where we want to calculate positions based on the future state of the layout.

ApproachMeasureScope

A scope that provides access to the lookahead results. The ApproachLayoutModifierNode can leverage these results to define how measurements and placements approach their destination.

approachLayout Modifier and ApproachLayoutModifierNode

The approachLayout modifier is instrumental in managing the approach pass (it replaces the now-deprecated Modifier.intermediateLayout). It operates within the LookaheadScope to establish the methodology for measuring and positioning a composable's content throughout an animation. This modifier constructs an "approach layout" that facilitates a gradual transition towards the target layout defined during the lookahead pass.

Internally, the approachLayout modifier utilizes the ApproachLayoutModifierNode API, a new Modifier Node tailored for the destination layout as determined in the lookahead phase. This Node relies on input from the users to confirm the completion of measurement and placement processes. Such confirmations enable the system to bypass the approach phase once concluded, thereby enhancing layout performance by avoiding unnecessary recalculations.

DeferredTargetAnimation

The DeferredTargetAnimation is a new experimental API for creating those animations whose target is unknown at instantiation. It can be used for size or position animations where the target size or position stays unknown until the later measure and placement phase. It has an updateTarget function, which sets up an animation or updates an already running animation. It returns the current value of the animation, after launching the animation in the given coroutineScope. It also has an isIdle Boolean property which returns true when the animation has finished running and reached its destination, or when the animation has not been set up.

Some important concepts here:

1. lookaheadSize: The destination/target size of the layout obtained in the ApproachMeasureScope. This is the size of the ApproachLayoutModifierNode measured during the lookahead pass.

2. localLookaheadPositionOf: It calculates the local position in the Lookahead coordinate space. It is used to obtain the target position during placement by using LookaheadScope.localLookaheadPositionOf and the lookahead LayoutCoordinates in the ApproachMeasureScope.

3. By knowing the target size and position, animations or other layout adjustments can be defined in the ApproachLayoutModifierNode to morph the layout gradually in both size and position to arrive at its precalculated bounds.

4. isMeasurementApproachComplete: A block that indicates whether the measurement has reached the destination size. It is invoked after the destination has been determined by the lookahead pass, before approachMeasure is invoked. It receives lookahead size in the argument to decide whether the destination size has been reached.

5. isPlacementApproachComplete: A block that indicates whether the position has approached the destination defined by the lookahead. Based on this, the system can decide whether additional approach placements are necessary. It is invoked after the destination position has been determined by the lookahead pass, and before the placement phase in approachMeasure.

6. Once both of the above two blocks return true, the system may skip approach pass until additional approach passes are necessary as indicated by them. If the above two approach callbacks are incomplete for a long time, the system might skip approach pass whenever possible. Hence it’s important to be accurate about these two callbacks.

Implement in code

We have learned a lot of concepts. But we do not know how to use them yet. Let’s write some code with these APIs.

Let’s start with an example where we want to animate four colored Boxes smoothly from a Row view to a Column view and vice-versa, on the click of the container. This example has been taken from the official docs here for LookAheadScope. We want to create something like this:

Now, we can follow two ways to use Lookahead APIs:

1. Write a custom implementation of the ApproachLayoutModifierNode

2. Use the approachLayout Modifier (internally uses ApproachLayoutModifierNode)

Both are ideally doing the same thing: defining an approach or logic to reach the destination. I will show both ways separately to obtain the desired animation shown above.

1. Writing a custom implementation of the ApproachLayoutModifierNode

Step 1:Create movable contents and switch layouts

First, we will create movable contents for the four colored Boxes. For this, we will use the movableContentOf API. This enables us to move around content without the need for recomposition. It works by receiving a composable lambda function that it will remember and move to wherever it is invoked. Then using a Boolean mutable state we will toggle them between a Row and a Column on the click of the parent Box container.

@Composable
fun LookAheadWithSimpleMovableContent() {
    val colors = listOf(
        Color(0xffff6f69),
        Color(0xffffcc5c),
        Color(0xff264653),
        Color(0xFF679138),
    )
    var isInColumn by remember { mutableStateOf(true) }
    val items = remember {
        movableContentOf {
            colors.forEach { color ->
                Box(
                    Modifier
                        .padding(8.dp)
                        .size(80.dp)
                        .background(color, RoundedCornerShape(10))
                )
            }
        }
    }

    Box(
        modifier = Modifier.fillMaxSize().clickable { isInColumn = !isInColumn },
        contentAlignment = Alignment.Center
    ) {
        if (isInColumn) {
            Column { items() }
        } else {
            Row { items() }
        }
    }
}

This will create a behavior like this. The layouts are switching but there is no animation as we have not added any.

Step 2: Use theLookaheadScopeAPI

Next, we will wrap our content with the LookaheadScope composable. This will provide us with the scope to “look ahead” so that we can determine the destination of our Box layouts through a lookahead pass.

So, our code will now look like this:

@Composable
fun LookAheadWithSimpleMovableContent() {
    // ...
    var isInColumn by remember { mutableStateOf(true) }
    LookaheadScope { // Wrapped with LookaheadScope
        // ...
        val items = remember {
            movableContentOf {
                // ...
            }
        }

        Box(
            modifier = Modifier.fillMaxSize().clickable { isInColumn = !isInColumn },
            contentAlignment = Alignment.Center
        ) {
            // Remaining code
        }
    }
}

Step 3: A custom implementation of ApproachLayoutModifierNode

Now the most crucial part. We will use the LookaheadScope from the above step to create a custom implementation of the ApproachLayoutModifierNode.

For this, we have to override 3 functions:

1. isMeasurementApproachComplete

2. isPlacementApproachComplete

3. approachMeasure

First, we have to create an offset animation of the type DeferredTargetAnimation, the target of which will be known during placement.

private val offsetAnimation: DeferredTargetAnimation<IntOffset, AnimationVector2D> = 
    DeferredTargetAnimation(IntOffset.VectorConverter)

Then override isMeasurementApproachComplete. As we are only animating the placement here, we can consider the measurement approach complete. So we can simply return a true here.

override fun isMeasurementApproachComplete(lookaheadSize: IntSize): Boolean {
    return true
}

Now we’ll override the isPlacementApproachComplete.

override fun Placeable.PlacementScope.isPlacementApproachComplete(
    lookaheadCoordinates: LayoutCoordinates
): Boolean {
    val target: IntOffset = with(lookaheadScope) {
        lookaheadScopeCoordinates.localLookaheadPositionOf(lookaheadCoordinates).round()
    }
    offsetAnimation.updateTarget(target, coroutineScope)
    return offsetAnimation.isIdle
}

Let’s try to understand what is happening in the above code. Our main objective of this function is to return true when the offset animation is complete, and false otherwise. First, we are acquiring the target position of the layout using the localLookaheadPositionOf with the layout’s coordinates. We have discussed previously that localLookaheadPositionOf calculates the local position of the layout in the Lookahead coordinate space. Then we will call updateTarget on the offsetAnimation that we created at the beginning with this acquired target position. This function will set up the animation or will update the already running animation based on the target. Finally, we will return offsetAnimation.isIdle which will return true when the animation has finished running.

Now, we’ll override the approachMeasure.

override fun ApproachMeasureScope.approachMeasure(
    measurable: Measurable,
    constraints: Constraints
): MeasureResult {
    val placeable = measurable.measure(constraints)
    return layout(placeable.width, placeable.height) {
        val coordinates = coordinates
        if (coordinates != null) {
            val target = with(lookaheadScope) {
                lookaheadScopeCoordinates.localLookaheadPositionOf(coordinates).round()
            }
            val animatedOffset = offsetAnimation.updateTarget(target, coroutineScope)
            val placementOffset = with(lookaheadScope) {
                lookaheadScopeCoordinates.localPositionOf(coordinates, Offset.Zero).round()
            }
            val (x, y) = animatedOffset - placementOffset
            placeable.place(x, y)
        } else {
            placeable.place(0, 0)
        }
    }
}

Let’s try to understand what is happening in the above code. The function approachMeasure accepts a Measurable and Constraints and returns a MeasureResult. So we are first measuring our measurable (which is our layout) using the constraints. This generates a Placeable. By definition, we know that a Placeable corresponds to a child layout that can be positioned by its parent layout. So we need to position or place this Placeable. Now, similar to the previous step, we are calculating the target offset within the lookaheadScope, using the availableLayoutCoordinates. Then using the updateTarget function and the target offset, we are starting an offset animation. This gives us the animated offset or position. Then, we are calculating the current offset within the given LookaheadScope using the localPositionOf function. We then calculate the delta between the animated position and the current position in lookaheadScope. Finally, we put the child layout in the animated position using the place function.

Both localLookaheadPositionOf and localPositionOf are used to get the converted offset relative to a specific coordinate. The only difference is that unlike localPositionOf, localLookaheadPositionOf uses the lookahead position for coordinate calculation.

Till here we are done with the custom implementation of the ApproachLayoutModifierNode and overridden all three functions.

Step 4: Create a custom node element

Now we have to create a custom node element for the AnimatedPlacementModifierNode created above by implementing the ModifierNodeElement abstract class. It takes a LookaheadScope instance in the constructor and creates/updates our custom ApproachLayoutModifierNode.

data class AnimatePlacementNodeElement(val lookaheadScope: LookaheadScope) :
    ModifierNodeElement<AnimatedPlacementModifierNode>() {

    override fun update(node: AnimatedPlacementModifierNode) {
        node.lookaheadScope = lookaheadScope
    }

    override fun create(): AnimatedPlacementModifierNode {
        return AnimatedPlacementModifierNode(lookaheadScope)
    }
}

Step 5: Create a Modifier to use the custom node element

We will create a Modifier that will internally use the custom node element AnimatePlacementNodeElement created above. This Modifier will be used with the colored Boxes that we want to animate.

fun Modifier.animatePlacementInScope(lookaheadScope: LookaheadScope): Modifier {
    return this.then(AnimatePlacementNodeElement(lookaheadScope))
}

Step 6: Use the above-createdModifier

Going back to the initial code we wrote, we will use this Modifier with the movable content Boxes. And we will pass the current LookaheadScope instance using this as we already wrapped it inside the LookaheadScope composable.

@Composable
fun LookAheadWithSimpleMovableContent() {
    // ...
    var isInColumn by remember { mutableStateOf(true) }
    LookaheadScope {
        val items = remember {
            movableContentOf {
                colors.forEach { color ->
                    Box(
                        Modifier
                            .padding(8.dp)
                            .size(80.dp)
                            .animatePlacementInScope(this) // Add Modifier here
                            .background(color, RoundedCornerShape(10))
                    )
                }
            }
        }
      // Remaining code
    }
}

Our implementation of Lookahead APIs with movable content is completed and now we will see the desired behavior. A smooth animation of the four Boxes between Row to Column layouts.

See the complete code for this example here:https://github.com/pushpalroy/ComposeLayoutPlayground/…/LookAheadWithCustomApproachLayoutModifierNode.kt

2. Using the approachLayout Modifier

This approach will be very similar to the previous way, with some differences.

Step 1: Create movable contents with LookaheadScope receiver

In the former approach, we used the movableContentOf API. In this approach, we will use the movableContentWithReceiverOf API. This is also used to create movable content but with a receiver context, which in our case will be the LookaheadScope. So our previous code to initialize the items of colored Boxes will become:

val items = remember {
    movableContentWithReceiverOf<LookaheadScope> {
        colors.forEach { color ->
            Box(
                Modifier
                    .padding(8.dp)
                    .size(80.dp)
                    .background(color, RoundedCornerShape(10))
            )
        }
    }
}

The remaining code for switching the layout between Row and Column will remain the same as the former code.

Step 2: Create a Modifier using the approachLayout Modifier

This step is very similar to how we created the custom implementation of ApproachLayoutModifierNode before. The approachLayout Modifier also provides us the three lambdas to invoke: isMeasurementApproachComplete, isPlacementApproachComplete and approachMeasure. This is exactly the same as how we have overridden the three functions previously. Also, we are going to write the same login inside each of these lambdas for our use case.

Note how we marked the entire Modifier function with context (LookaheadScope) at the top. This means our animateBounds Modifier will only work in the context of a LookaheadScope. This also helps to access the lookaheadScopeCoordinates for calculating the localPosition in the Lookahead coordinate space.

context (LookaheadScope)
@OptIn(ExperimentalAnimatableApi::class, ExperimentalComposeUiApi::class)
fun Modifier.animateBounds(): Modifier = composed {
    val offsetAnim = remember { DeferredTargetAnimation(IntOffset.VectorConverter) }
    val scope = rememberCoroutineScope()
    this.approachLayout(
        isMeasurementApproachComplete = {
            true
        },
        isPlacementApproachComplete = {
            val target = lookaheadScopeCoordinates.localLookaheadPositionOf(it)
            offsetAnim.updateTarget(target.round(), scope)
            offsetAnim.isIdle
        }
    ) { measurable, constraints ->
        measurable.measure(constraints)
            .run {
                layout(width, height) {
                    coordinates?.let {
                        val target = lookaheadScopeCoordinates.localLookaheadPositionOf(it).round()
                        val animOffset = offsetAnim.updateTarget(target, scope)
                        val current = lookaheadScopeCoordinates.localPositionOf(it, Offset.Zero).round()
                        val (x, y) = animOffset - current
                        place(x, y)
                    } ?: place(0, 0)
                }
            }
    }
}

Note: If we see the internals of the approachLayout Modifier, we will find that it is in fact creating a ApproachLayoutElement data class which is an implementation of the ModifierNodeElement abstract class (Step 4 of our former way). And a custom implementation of ApproachLayoutModifierNode is there, called the ApproachLayoutModifierNodeImpl (Step 3 of our former way). So basically both the ways we just covered do the same thing.

Step 3: Use the above-created Modifier in our layout

Now the obvious step, we will use the animateBounds modifier in our layout. This is similar to Step 6 of our former way. As we used movableContentWithReceiverOf<LookaheadScope> the animateBounds() will execute in the context of LookaheadScope, which we need.

// Remaining Code
// ..
val items = remember {
    movableContentWithReceiverOf<LookaheadScope> {
        colors.forEach { color ->
            Box(
                Modifier
                    .padding(8.dp)
                    .size(80.dp)
                    .animateBounds() // Use modifier here
                    .background(color, RoundedCornerShape(10))
            )
        }
    }
}
// ..
// Remaining Code

All the other codes will remain the same. If we run the above code it will result in the same animation we obtained earlier.

See the complete code for this example here:

https://github.com/pushpalroy/ComposeLayoutPlayground/…/LookAheadWithApproachLayoutModifier.kt

It’s obvious that the second approach, that is using the approachLayout Modifier is an easier way and requires writing less code for our use case.

Customize animations

In the isPlacementApproachComplete lambda, we are updating the offset animation using the updateTarget function:

offsetAnim.updateTarget(target.round(), scope)

The updateTarget has a default animationSpec of spring(), which we can customize. For example, we can pass a tween() like this:

offsetAnim.updateTarget(target.round(), scope, tween(durationMillis = 800))

This will create an animation like this:

Animate size along with placement

If we remember, in the previous animation we have just animated the placement of the Boxes. As we only animated the placement here and not the size, we considered the measurement was approach complete. So we returned a true inside the isMeasurementApproachComplete lambda.

What if we want to animate the size as well? Let’s do that.

Let’s modify the last code and switch the size of each Box between 80.dp and 20.dp based on whether the layout is a Row or Column.

// ..
var isInColumn by remember { mutableStateOf(true) }
val items = remember {
    movableContentWithReceiverOf<LookaheadScope> {
        colors.forEach { color ->
            Box(
                Modifier
                    .padding(8.dp)
                    .size(if (isInColumn) 80.dp else 20.dp)
                    .animateBounds()
                    .background(color, RoundedCornerShape(10))
            )
        }
    }
}
// Remaining Code

So now based on the isInColumn flag, we are changing the size. That means if the layout is a Column 80.dp will be used else 20.dp will be used.

Also, let’s increase the animation duration of the offset inside isPlacementApproachComplete so that we see clearly what is happening. Let's use a tween animation for 3000ms.

// ..
isPlacementApproachComplete = {
    val target = lookaheadScopeCoordinates.localLookaheadPositionOf(it)
    offsetAnim.updateTarget(target.round(), scope, tween(3000))
    offsetAnim.isIdle
}
// ..

Now without any further modification, if we run the code now, we will see this:

If we look closely, the size is changing but there is no animation for that. We can only see animation for placement. The size is just snapping from 80.dp to 20.dp quickly.

Let’s add animation for the size change:

Similar to the offsetAnim, we will create a DeferredTargetAnimation called the sizeAnim, which will track the animation for size. Then instead of returning true inside isMeasurementApproachComplete, now we will do updateTarget on sizeAnim and return if it’s idle:

// ..
this.approachLayout(
  isMeasurementApproachComplete = {
      sizeAnim.updateTarget(it, scope, tween(2000))
      sizeAnim.isIdle
  },
  isPlacementApproachComplete = {
    // Same as before
  }
// ..

The above code will return true inside isMeasurementApproachComplete when the size animation is complete. Note that we have used a tween animation of duration 2000ms for the size animation.

Now, inside the approachMeasure block, we will do sizeAnim.updateTarget with the lookaheadSize to get the animWidth and animHeight. This is the measured size of the layout while animating. We will then use this constraint to measure the measurable: Constraints.fixed(animWidth, animHeight).

this.approachLayout(
    isMeasurementApproachComplete = {
        // ..
    },
    isPlacementApproachComplete = {
        // ..
    }
) { measurable, _ ->
    val (animWidth, animHeight) = sizeAnim.updateTarget(lookaheadSize, scope)
    measurable.measure(Constraints.fixed(animWidth, animHeight))
        .run {
            layout(width, height) {
                coordinates?.let {
                    val target = lookaheadScopeCoordinates.localLookaheadPositionOf(it).round()
                    val animOffset = offsetAnim.updateTarget(target, scope)
                    val current = lookaheadScopeCoordinates.localPositionOf(it, Offset.Zero).round()
                    val (x, y) = animOffset - current
                    place(x, y)
                } ?: place(0, 0)
            }
        }
}

This will create an effect like this:

Now we can see that the Boxes' size and placement are getting animated smoothly.

See the complete code for this example here:

https://github.com/pushpalroy/ComposeLayoutPlayground/…/LookAheadWithApproachLayoutModifier2.kt

You can find all the examples along with some other examples of Lookahead in this repository:

Some important API changes

1. In Version 1.7.0-alpha03, the ApproachLayoutModifierNode API has been added to support creating custom approach logic in an explicit Modifier Node.

2. In Version 1.6.0-alpha03, the LookaheadScope composable and interfaces are made stable. Also, a new enter/exit transition to scale content to container size has been added. Read here.

3. In Version 1.6.0-alpha02, LookaheadLayout and LookaheadLayoutScope have been finally removed and replaced by LookaheadScope APIs.

4. In Version 1.6.0-alpha01, support for lookahead has been added to LazyList.

5. In Version 1.5.0-alpha03, new behavior has been added due to which SubcomposeLayouts that don’t have conditional slots work nicely with lookahead animations.

6. In Version 1.5.0-alpha01, LookaheadLayout has been replaced by LookaheadScope, which is no longer a Layout.

7. In Version 1.3.0-alpha01, LookaheadLayout was first introduced. See the commit here.

Additional resources

Learn more about LookAheadLayout from these resources:

1. Official Docs:
   https://developer.android.com/reference/kotlin/androidx/compose/ui/layout/LookaheadScope

2. Introducing LookaheadLayout byJorge Castillo**:
   **https://substack.com/inbox/post/64358322

3. This blog by Ji Sungbin:
   https://betterprogramming.pub/introducing-jetpack-composes-new-layout-lookaheadlayout-eb30406f715

Conclusion

Lookahead is a potent API within Jetpack Compose that, when utilized correctly, enables the creation of stunning and highly performant animations, including shared element transitions among others. This article aims to provide an initial exploration and shed light on various aspects of this new API, encouraging further experimentation.

Check out the follow-up article where I demonstrate how to create a container transform animation using Lookahead: Container Transform Animation with Lookahead in Jetpack Compose

Follow me: @pushpalroy

If we look closely, the indicator sizes also diminish for images further away from the current selection, providing a focused visual effect.

In this article, we will learn how to create this UX using Jetpack Compose. The idea is to create a composable named DraggableIndicator and use it along with a HorizontalPager.

So let’s get started.

Step-by-step Approach

Step 1: Set up the basic composable structure

We have to create a composable called DraggableIndicator which will look like this. It will have the following arguments:

• pagerState: A PagerState instance which will be used by the HorizontalPager.

• itemCount: The total count of items or images in the pager.

• onPageSelected: A callback function that is invoked when a new page is selected through drag gestures.

We’ll start the parent with a simple Box.

@Composable
fun DraggableIndicator(
    modifier: Modifier = Modifier,
    state: PagerState,
    itemCount: Int,
    onPageSelect: (Int) -> Unit,
) {
    Box(modifier = modifier) {
        // Indicators will be added here
    }
}

Step 2: Add the indicators

Next, we will draw each indicator using a Box and drawBehind modifier with an initial style ofGray color and add them in a horizontal row using a LazyRow.

LazyRow(
    modifier = Modifier.padding(8.dp).widthIn(max = 100.dp),
    horizontalArrangement = Arrangement.spacedBy(8.dp),
    verticalAlignment = Alignment.CenterVertically
) {
    items(itemCount) { index ->
        Box(
            modifier = Modifier
                .size(10.dp)
                .drawBehind {
                  drawCircle(color)
                }
        )
    }
}

Step 3: Adjust indicator size and color based on the current page

Now as we discussed at the start, we want to create a visual effect for our indicators, such that the indicator sizes diminish for images further away from the current selection. To achieve this, we have to calculate a scaleFactor for each indicator dot, based on the currentPage state and the indicator index. The currentPage here is simply the Int state obtained from the PagerState of the pager. Also, we are switching the color of each indicator between 2 values based on the currently selected page.

items(itemCount) { i ->
    val scaleFactor = 1f - (0.1f * abs(i - currentPage)).coerceAtMost(0.4f)
    val color = if (i == currentPage) Color(0xFF03A9F4) else Color.Gray
    Box(
        modifier = Modifier
            .size(10.dp)
            .graphicsLayer {
                scaleX = scaleFactor
                scaleY = scaleFactor
            }
            .drawBehind {
                drawCircle(color)
            }
    )
}

The formula we are using to calculate the scale factor for each indicator here is:

val scaleFactor = 1f - (0.1f * abs(i - currentPage)).coerceAtMost(0.4f)

Let’s try to understand what is happening in the above formula:

• 1f: This represents the base scale factor, implying that in the default state (when the indicator is the current page), it should not be scaled down at all (i.e., it retains its original size).

• 0.1f * abs(i - currentPage): This portion of the formula calculates the difference in position between the current indicator (i) and the currently selected page (currentPage). The absolute value (abs) ensures that the distance is always a positive number, regardless of whether the current indicator is before or after the current page. This distance is then multiplied by 0.1f, determining how much the scale factor decreases as the distance from the current page increases. This means, that for each step away from the current page, the indicator scales down by 10%.

• .coerceAtMost(0.4f): This method caps the maximum scale-down effect to 40% (0.4f). Without this cap, indicators far away from the current page could become too small or even disappear. By limiting the scale factor reduction to a maximum of 40%, we ensure that all indicators remain visible and maintain a minimum scale, contributing to a balanced and harmonious visual effect across the carousel.

The result is a dynamic scaling effect where the size of each indicator smoothly decreases as the distance from the current page increases, up to a maximum scale reduction.

Step 4: Enable long-press and drag gestures

Now, the most interesting part. We need to implement a gesture that will enable us to first long-press on the indicators and then scroll left and right. For this will use the pointerInput Modifier along with the detectDragGesturesAfterLongPress suspend function which is an extension of the PointerInputScope. This is a very useful function of the androidx.compose.foundation.gestures package.

val accumulatedDragAmount = remember { mutableFloatStateOf(0f) }
var enableDrag by remember { mutableStateOf(false) }

Modifier.pointerInput(Unit) {
    detectDragGesturesAfterLongPress(
        onDragStart = {
            enableDrag = true
            accumulatedDragAmount.floatValue = 0f
        },
        onDrag = { change, dragAmount ->
            change.consume()
            accumulatedDragAmount.floatValue += dragAmount.x
            // Logic to update currentPage based on drag
        },
        onDragEnd = {
            enableDrag = false
            accumulatedDragAmount.floatValue = 0f
        }
    )
}

Let’s try to understand what is happening:

Here the gesture detector waits for the pointer down and long press, after which it calls onDrag for each drag event, which is exactly what we need. onDragStart is called when a long press is detected and onDragEnd is called after all pointers are up. The enableDrag flag tracks the point when drag is enabled and disabled. This is important because we want the drag to be disabled as soon as the user leaves the long press. The accumulatedDragAmount tracks the total drag distance, which will be used later to decide page scrolling.

Step 5: Change pages on drag

Now inside the onDrag lambda, we will use the value of accumulatedDragAmount to incorporate the logic to change the current page.

First, we need to calculate a drag threshold. The threshold represents the minimum distance the user needs to drag to trigger a page change. This mechanism ensures that slight, unintentional drags do not cause the carousel to switch pages. We will not hardcode this value to a fixed dp because the threshold should change based on the number of items in the carousel. Otherwise, the user might have to swipe more or less if the item count changes causing a weird experience. This is a one-time calculation that we need to add at the top of our composable. Feel free to play around with this calculation to create a desired user experience.

val density = LocalDensity.current
val threshold = remember {
    with(density) {
        ((80.dp / (itemCount.coerceAtLeast(1))) + 10.dp).toPx()
    }
}

Now using the threshold and accumulatedDragAmount we will write the logic to change the current page inside onDrag.

if (abs(accumulatedDragAmount.value) >= threshold) {
    val nextPage = if (accumulatedDragAmount.value < 0) state.currentPage + 1 else state.currentPage - 1
    val correctedNextPage = nextPage.coerceIn(0, itemCount - 1)

    if (correctedNextPage != state.currentPage) {
        onPageSelect(correctedNextPage)
    }
    accumulatedDragAmount.value = 0f
}

Let’s try to understand what is happening:

• abs(accumulatedDragAmount.value) >= threshold: This condition checks if the absolute value of the accumulated drag amount (i.e., the total distance the user has dragged, disregarding direction) has reached or exceeded a predefined threshold. This determines nextPage.

• If accumulatedDragAmount.value < 0, it implies the user has dragged to the left, intending to move to the next page. Therefore, state.currentPage + 1 is computed.

• Conversely, if accumulatedDragAmount.value > 0, the user has dragged to the right, indicating a move to the previous page, hence state.currentPage - 1.

• correctedNextPage: The nextPage value is then coerced within the bounds of 0 and itemCount - 1 using coerceIn. This step ensures that the page index stays within the valid range of pages available in the carousel, preventing index out-of-bounds errors.

• If correctedNextPage is different from state.currentPage, the onPageSelect(correctedNextPage) callback is invoked. This action effectively updates the carousel to display the new page selected by the user's drag gesture.

• Finally, accumulatedDragAmount.value is reset to 0f. This reset is crucial for starting the drag distance calculation afresh for subsequent drag gestures, ensuring that each drag gesture is evaluated independently of the previous ones.

Step 6: Scroll to the indicator position on the drag

Our implementation of the drag gesture is completed. Now we need to make sure that the LazyRow of indicators scroll automatically when the user drags. For this, we will add this LaunchedEffect at the top of our composable which animate scroll to the currentPage index whenever the page changes.

LaunchedEffect(currentPage) {
    coroutineScope.launch {
        lazyListState.animateScrollToItem(index = currentPage)
    }
}

Step 7: Add interactive haptic feedback!

Now when everything is done, it will be cool to add some kind of haptic feedback effect (sensory effect that is created by a device vibrating) so that users get feedback with the interaction. We will provide feedback at 2 points: One when drag is enabled after long-press and then when each page changes.

To do this first we need to initialize a hapticFeedback at the top:

 val haptics = LocalHapticFeedback.current

Then use it when inside onDragStart when drag is enabled after long-press on the indicators:

.pointerInput(Unit) {
  detectDragGesturesAfterLongPress(
      onDragStart = {
          haptics.performHapticFeedback(HapticFeedbackType.LongPress)
          accumulatedDragAmount.floatValue = 0f
          enableDrag = true
      },
// Remaining code

Also inside onDrag when the page changes:

onDrag = { change, dragAmount ->
  if (enableDrag) {
      change.consume()
      accumulatedDragAmount.floatValue += dragAmount.x
      if (abs(accumulatedDragAmount.floatValue) >= threshold) {
          // Remaining code
          if (correctedNextPage != state.currentPage) {
              haptics.performHapticFeedback(HapticFeedbackType.TextHandleMove)
              onPageSelect(correctedNextPage)
          }
          // Remaining code
      }
  }
},
// Remaining code

That’s it.

We have come a long way to create our composable DraggableIndicator.

Now we will use this in our code.

Use the composable in our code

Consider this sample code for usage. Here we are using a HorizontalPager to show a list of image items in a carousel. Below the Pager, we are showing the indicators using DraggableIndicator.

val state = rememberPagerState(
    initialPage = 0,
    initialPageOffsetFraction = 0f
) { list.size } // Here, list is images list

val coroutineScope = rememberCoroutineScope()
Column(
    modifier = Modifier.padding(24.dp),
    verticalArrangement = Arrangement.Center,
    horizontalAlignment = Alignment.CenterHorizontally
) {
    HorizontalPager(
        modifier = Modifier.height(280.dp),
        state = state,
    ) { page ->
        // Pager content: Image, Card, etc.
    }
    Spacer(modifier = Modifier.height(16.dp))
    // Using our composable here
    DraggableIndicator(
        modifier = Modifier,
        state = state,
        itemCount = colorList.size,
        onPageSelect = { page ->
            coroutineScope.launch {
                state.scrollToPage(page)
            }
        },
    )
}

Final Result

Source code

The entire source code is available here:

A Quick Recap to the Rendering

Jetpack Compose renders a frame in the following 3 phases: Composition, Layout, and Drawing. On a high level, the responsibilities of these phases are: “What to show”, “Where to show” and “How to show” respectively. In the Composition phase, the runtime executes the composable functions and generates a UI tree consisting of layout nodes, that contain all information for the next 2 phases. In the Layout phase, with the help of the UI tree information, each node’s size and location are determined in 2D space. The entire UI tree is traversed and each node does these: Measure its children if any, based on the measurements decide on its own size, and each child node is placed in 2D space relative to the nodes’s own position. In the Draw phase, each node is traversed again from the top of the tree to the bottom, and based on the size and position measurements from the previous phase, they are drawn on the screen.

These are repeated in every frame where data is changed. Also, you can skip some phase(s) if data is not changed. Compose tracks what state is read within each of them. This allows Compose to notify only the specific phases that need to perform work for each affected element of your UI. This is extremely important for us to understand because based on the code we are writing we can skip some phases in the rendering, which can improve performance.

A Quick Recap to Stability in Compose

Compose considers types to be either stable or unstable. A type is stable if it is immutable, or if Compose can know whether its value has changed between recompositions (notify Composition upon mutating). A type is unstable if Compose can’t know whether its value has changed between recompositions. If a composable has stable parameters that have not changed, Compose skips it. If a composable has unstable parameters, Compose always recomposes it when it recomposes the component’s parent. We can use the Compose compiler reports, using which the Compose compiler can output the results of its stability inference for inspection. The compiler marks functions to be either skippable or restartable. A skippable function denotes Compose can skip it during recomposition if all its arguments are equal with their previous values. Normally a function is marked as skippable if all its parameters are stable and thus Compose can infer when it has or has not changed. A restartable function denotes that this composable can serve as a restarting “scope”. This means that whenever this Composable needs to recompose, it will not trigger the recomposition of its parent scope. Rather this function itself can be a point of entry for where Compose can start re-executing code for recomposition after state changes.

Rules to Overcome Common Pitfalls

1. Avoid using unstable collections as much as possible

The Compose compiler cannot be completely sure that collections such as List, Map, and Set are truly immutable and therefore mark them as unstable. This means, that if we use unstable collections as an argument in a composable function, the argument will be marked as unstable. This even the argument does not change, the composable will recompose if the parent recomposes.

Consider this example to understand: Here when the FavoriteButton was toggled, the list articles would also be recomposed as it has an unstable parameter type: List. Even if the Article class is stable in this example, that won’t help because the List is unstable.

@Composable
fun UnstableListScreen(viewModel: ListViewModel = viewModel()) {
    var favorite by remember { mutableStateOf(false) }
    Column(
        modifier = Modifier.padding(16.dp)
    ) {
        FavoriteButton(isFavorite = favorite, onToggle = { favorite = !favorite })
        Spacer(modifier = Modifier.height(16.dp))
        UnstableList(viewModel.articles)
    }
}

@Composable
private fun UnstableList(
    articles: List<Article>, // List = Unstable, Article = Stable
    modifier: Modifier = Modifier // Stable
) {
    LazyColumn(modifier = modifier) {
        items(articles) { article ->
            Text(text = article.name)
        }
    }
}

Overcome:

Solution 1: To overcome this issue, we can use the Kotlinx Immutable collections instead of using the default collections. Here the same code is modified by using the PersistentList from the Immutable Collections library as a replacement of List. This makes articles as stable. Hence, when the FavoriteButton was toggled, the list of articles was not recomposed.

@Composable
fun StableListScreen(viewModel: ListViewModel = viewModel()) {
    var favorite by remember { mutableStateOf(false) }
    Column(
        modifier = Modifier.padding(16.dp)
    ) {
        FavoriteButton(isFavorite = favorite, onToggle = { favorite = !favorite })
        Spacer(modifier = Modifier.height(16.dp))
        StableList(viewModel.articles)
    }
}

@Composable
private fun StableList(
    articles: PersistentList<Article>, // PersistentList = Stable, Article = Stable
    modifier: Modifier = Modifier // Stable
) {
    LazyColumn(modifier = modifier) {
        items(articles) { article ->
            Text(text = article.name)
        }
    }
}

Solution 2: Though Solution 1 is a much more straightforward approach, one thing to consider here is the library is still in Alpha. So if we are skeptical about using this library in production code, we can use another approach: Using an Immutable wrapper around a standard List.

We should also follow this approach if the type of class used in the List cannot be made stable. Thus even if the List or Article is unstable, ArticleList will be stable because we are using the @Immutable annotation.

@Immutable
data class ArticleList(
    val articles: List<Article> // List = Unstable or Article = Unstable
)

Then instead of using the List directly in the above code, we can use this ArticleList.

@Composable
private fun StableList(
    articles: ArticleList, // ArticleList = Stable
    modifier: Modifier = Modifier // Stable
) {
    LazyColumn(modifier = modifier) {
        items(articles) { article ->
            Text(text = article.name)
        }
    }
}

2. Remember the code inside the clickable() Modifier

If we use the clickable() modifier on a composable, the lambda onClick of each item is reallocated every time the parent recomposes. This is because the object of the lambda is not auto-remembered.

Consider this example to understand: Here on adding each item to the LazyColumn (on the press of the Button), the entire list including the previous items is recomposed. This is because we have the clickable() modifier on each item of the list. So the lambda onClick of each item is reallocated every time the LazyColumn recomposes. This is because the object of the lambda is not remembered. This might cause serious performance issues as the remaining items on the list have no reason to recompose unnecessarily.

@Composable
fun ListWithNonRememberedClickableItems(viewModel: ListViewModel = viewModel()) {
    val dynamicList by viewModel.dynamicArticles.collectAsState()
    Column(
        modifier = Modifier.padding(16.dp)
    ) {
        Button(
            onClick = { viewModel.addArticleToDynamicList() }
        ) {
            Text(text = "Add item")
        }
        Spacer(modifier = Modifier.height(32.dp))
        ListWithNonRememberedClickableItems(dynamicList)
    }
}

@Composable
private fun ListWithNonRememberedClickableItems(
    articles: List<Article>,
    modifier: Modifier = Modifier
) {
    val context = LocalContext.current
    LazyColumn(modifier = modifier) {
        items(articles) { article ->
            Text(
                modifier = Modifier.clickable { // Not remembered
                    Toast.makeText(context, "Clicked item: ${article.id}", Toast.LENGTH_SHORT).show()
                },
                text = article.name
            )
        }
    }
}

Overcome: To overcome this issue, we can wrap the clickable() Modifier inside a remember block. Thus the lambda object will be remembered and the won’t be reallocated every time the parent recomposes.

@Composable
fun ListWithRememberedClickableItems(
    articles: List<Article>,
    modifier: Modifier = Modifier
) {
    val context = LocalContext.current
    LazyColumn(modifier = modifier) {
        items(articles) { article ->
            Text(
                modifier = Modifier.then(
                    remember {
                        Modifier.clickable { // Remembered
                            Toast.makeText(context, "Clicked item: ${article.id}", Toast.LENGTH_SHORT).show()
                        }
                    }
                ),
                text = article.name
            )
        }
    }
}

Consider another simple example: Here typing anything in the TextField will recompose the parent composable function. But the Text composable “Toggle me” has nothing to do with it. Still, it will recompose, as it is using the clickable() Modifier, which is not remembered.

@Composable
fun ChildWithNonRememberedClickableModifier() {
    var text by remember { mutableStateOf("") }
    var isClicked by remember { mutableStateOf(false) }
    Column(modifier = Modifier.padding(24.dp)) {
        Text(
            modifier = Modifier,
            text = "Toggle state: $isClicked"
        )
        Spacer(modifier = Modifier.height(8.dp))
        Text(
            modifier = Modifier
                .padding(8.dp)
                .clickable { isClicked = !isClicked },
            text = "Toggle me"
        )
        Spacer(modifier = Modifier.height(16.dp))
        TextField(value = text, onValueChange = { text = it })
    }
}

Overcome: Similarly, to fix this issue, we can wrap the clickable() Modifier inside a remember block. Thus the lambda object will be remembered and the won’t be reallocated every time the parent recomposes.

@Composable
fun ChildWithRememberedClickableModifier() {
    var text by remember { mutableStateOf("") }
    var isClicked by remember { mutableStateOf(false) }
    Column(modifier = Modifier.padding(24.dp)) {
        Text(
            modifier = Modifier,
            text = "Toggle state: $isClicked"
        )
        Spacer(modifier = Modifier.height(8.dp))
        Text(
            modifier = Modifier
                .padding(8.dp)
                .then(
                    remember {
                        Modifier.clickable { isClicked = !isClicked }
                    }
                ),
            text = "Toggle me"
        )
        Spacer(modifier = Modifier.height(16.dp))
        TextField(value = text, onValueChange = { text = it })
    }
}

3. Remember lamdas with calls on an unstable object

This is very well explained by Ben Trengrove in the “Unstable lambdas” section of the blog Strong Skipping Mode Explained. In short, as of now, the compose compiler does not auto-remember lambdas with unstable captures. And as discussed before if lambdas are not remembered, they will be reallocated every time the parent recomposes.

Consider this example to understand: Here as ListViewModel is unstable, the lambda onValueChnage containing the call viewModel.numberChanged(it) is not auto-remembered by the compiler. Thus when the parent recomposes due to the change in the TextField input, the NumberComposable also recomposes, even when it has nothing to do with the change of TextField.

@Composable
fun CallOnUnstableObjectWithNonRememberedLambda(viewModel: ListViewModel = viewModel()) { // ListViewModel is unstable
    val number by viewModel.number.collectAsState()
    var text by remember { mutableStateOf("") }
    Column(modifier = Modifier.padding(16.dp)) {
        NumberComposable(
            current = number,
            onValueChange = { viewModel.numberChanged(it) }
        )
        Spacer(modifier = Modifier.height(16.dp))
        TextField(value = text, onValueChange = { text = it })
    }
}

Overcome: To fix this problem, the onValueChange lambda content should be wrapped in a remember block.

@Composable
fun CallOnUnstableObjectWithRememberedLambda(viewModel: ListViewModel = viewModel()) { // ListViewModel is unstable
    val number by viewModel.number.collectAsState()
    var text by remember { mutableStateOf("") }
    Column(modifier = Modifier.padding(16.dp)) {
        NumberComposable(
            current = number,
            onValueChange = remember { { viewModel.numberChanged(it) } }
        )
        Spacer(modifier = Modifier.height(16.dp))
        TextField(value = text, onValueChange = { text = it })
    }
}

4. Avoid using background() Modifier while animating color

Let’s think about the 3 phases of rendering we discussed at the start of this blog: Composition, Layout, and Draw. The background() modifier takes a color argument which is quite useful at times. But it’s also worth highlighting that this modifier causes all the 3 phases of rendering to run, even though it could have skipped the Composition and Layout phase (as the content or position of the Box is not changing, just the color is changing). This means if we are changing the argument color very frequently then heavy computation is done because the composable might recompose that frequently.

Consider this example to understand: Here the background() modifier is used on a Box composable, and the color is changed very frequently by using animation. As the color changes every 1 second, the Box recomposes every 1 second.

@Composable
fun CompositionInEveryPhase() {
    Box(
        modifier = Modifier.fillMaxSize().padding(16.dp)
    ) {
        var isNeedColorChange by remember { mutableStateOf(false) }
        val startColor = Color.Blue
        val endColor = Color.Green
        val backgroundColor by animateColorAsState(
            if (isNeedColorChange) endColor else startColor,
            animationSpec = tween(durationMillis = 800, delayMillis = 100, easing = LinearEasing),
            label = "Animate background color"
        )
        LaunchedEffect(Unit) {
            while (true) {
                delay(1000)
                isNeedColorChange = !isNeedColorChange
            }
        }
        Box(
            modifier = Modifier
                .size(300.dp)
                .align(Alignment.Center)
                .background(color = backgroundColor)
        )
    }
}

Overcome: To fix this issue, we can use the drawBehind{} lambda modifier and drawRect() function to draw the background color, which will only run the Draw phase, just skipping the first 2 phases.

@Composable
fun CompositionOnlyInDrawPhase() {
        // Remaining code
        Box(
            modifier = Modifier
                .size(300.dp)
                .align(Alignment.Center)
                .drawBehind {
                    drawRect(color = backgroundColor)
                }
        )
    }
}

5. Avoid using transform modifiers directly while animating value

We often need to perform transform animations in Compose (rotation, scale, position). While using direct transform modifiers like Modifier.rotate() if we change the value of the argument: degrees, then the entire composable will recompose. This means if we are changing the argument degrees very frequently then heavy computation is done because the composable might recompose that frequently. This recomposition is unnecessary since the appearance of the composable is not changing, we are just rotating it.

Consider this example to understand: Here we are using the rotate modifier directly on a Box composable, and changing the rotation degrees using an infinite animation. As a result, the Box recomposes whenever the value of the degree animates.

@Composable
fun TransformUsingRotateModifier() {
    Box(modifier = Modifier.fillMaxSize()) {
        val transition = rememberInfiniteTransition(label = "Infinite transition")
        val rotationDegree by transition.animateFloat(
            initialValue = 0f,
            targetValue = 1f,
            animationSpec = infiniteRepeatable(animation = tween(3000)),
            label = "Infinite animation"
        )
        Box(
            modifier = Modifier
                .align(Alignment.Center)
                .rotate(rotationDegree * 360f)
                .size(100.dp)
                .background(Color.Gray)
        )
    }
}

Overcome: To fix this performance caveat, we should use the graphicsLayer{} lambda modifier whenever possible. This Modifier only affects the draw phase, hence skipping the Composition and Layout phases, thus skipping recompositions. We should use it whenever possible while dealing with clipping, transform, rotation, or alpha changes.

@Composable
fun TransformUsingGraphicsLayerModifier() {
        // Remaining code
        Box(
            modifier = Modifier
                .align(Alignment.Center)
                .graphicsLayer {
                    rotationZ = rotationRatio * 360f
                }
                .size(100.dp)
                .background(Color.Gray)
        )
    }
}

That’s all for this article!

All the examples used in this blog are available in this repo:

Use the “Layout Inspector” tool of Android Studio to run the examples and see the recompositions count, which will help a lot to understand.

I hope this writing will help many developers avoid these common pitfalls and write Jetpack Compose code with best practices in mind.

Insets refer to the areas on a screen that are not fully usable for our app’s UI due to system UI elements like the status bar, navigation bar, display cutouts (often referred to as the notch or pinhole), and the IME keyboard.

By default, our app’s UI is restricted to being laid out within the system UI, like the status bar and navigation bar. This ensures that system UI elements don’t obscure the app’s content.

Then why should we worry about Insets at all?

It is recommended apps opt-in to display in these areas where system UI is also being displayed (going edge-to-edge), which results in a more seamless user experience and allows our app to take full advantage of the window space available to it.

As modern smartphones embrace edge-to-edge screens and diverse aspect ratios, the management of insets has escalated in importance.

“With great power comes great responsibility”

In essence, we’re shifting from a system-controlled insets paradigm to one where developers actively engage in enabling edge-to-edge displays or drawing behind system UI elements, thus taking control of insets management!

How to get started?

Initial Setup

We have to get our app full control of the area where it will draw the content. Without this setup, our app may draw black or solid colors behind the system UI, or not animate synchronously with the software keyboard.

• Call the enableEdgeToEdge function in Activity onCreate.

This call requests that our app display behind the system UI. The app will then be in control of how those insets are used to adjust the UI.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    enableEdgeToEdge()

    setContent {
        // App content here
    }
}

• Set android:windowSoftInputMode="adjustResize" in our Activity AndroidManifest.xml.

This setting allows our app to receive the size of the software IME as insets, which we can use to pad and lay out content appropriately when the IME appears and disappears in our app.

<activity
  android:name=".ui.MainActivity"
  android:label="@string/app_name"
  android:windowSoftInputMode="adjustResize"
  android:theme="@style/Theme.MyApplication"
  android:exported="true">

Let’s have a look at how our app looks like at this point with the below code:

setContent {
    Box(
        modifier = Modifier
             .fillMaxSize()
             .background(color = Color.DarkGray)
       )
}

We can see that the colored Box has filled the entire screen and drawing even behind the system bars (top status bar and bottom navigation bar). This means, that now our code is capable of drawing behind the system UI and we can control these areas ourselves!

Controlling Insets

Once our Activity is displaying behind the system UI and has taken control of handling all the Insets manually, we can use the Compose APIs to ensure that our app’s interactable content does not overlap with the system UI.

These APIs also synchronize our app’s layout with inset changes.

There are two primary ways to use the Inset types to adjust our Composable layouts: Padding Modifiers and Inset Size Modifiers.

Padding Modifiers

We can use Modifier.windowInsetsPadding(windowInsets: WindowInsets) to apply Window insets as padding. It works very similar to Modifier.padding.

There are some built-in Window insets like WindowInsets.systemBars, WindowInsets.statusBars, WindowInsets.navigationBars, etc. which we can use to provide the desired padding.

For example in the previous code, if we want to leave out the status bar and navigation bar and then draw the Grey box we can do:

setContent {
    Box(
        modifier = Modifier
            .fillMaxSize()
            .background(color = Color.LightGray)
            .windowInsetsPadding(WindowInsets.systemBars)
    ) {
        Box(
            modifier = Modifier
                .fillMaxSize()
                .background(color = Color.DarkGray)
        )
    }
}

Modifier windowInsetsPadding(WindowInsets.systemBars) adds padding for the top status bar and bottom navigation bar, which are colored with LightGray for understanding. This will make our app look like this:

We can also use windowInsetsPadding(WindowInsets.statusBars) or windowInsetsPadding(WindowInsets.navigationBars) to control these Insets separately.

There are also many built-in methods for the most common types of Insets. For example:

1. safeDrawingPadding(), equivalent to windowInsetsPadding(WindowInsets.safeDrawing)

2. safeContentPadding(), equivalent to windowInsetsPadding(WindowInsets.safeContent)

3. safeGesturesPadding(), equivalent to windowInsetsPadding(WindowInsets.safeGestures)

Inset size modifiers

These modifiers help in setting the size of a component to the exact size of the insets. These are useful for sizing a Spacer that takes up an Inset size while creating a screen.

For example, we can write the last code like this using Inset size modifiers to provide padding for the status bar and navigation bar. This will produce the same result:

setContent {
    Column {
        Spacer(
            modifier = Modifier
                .fillMaxWidth()
                .background(color = Color.LightGray)
                .windowInsetsTopHeight(WindowInsets.statusBars)
        )
        Box(
            modifier = Modifier
                .fillMaxSize()
                .background(color = Color.DarkGray)
                .weight(1f)
        )
        Spacer(
            modifier = Modifier
                .fillMaxWidth()
                .background(color = Color.LightGray)
                .windowInsetsBottomHeight(WindowInsets.navigationBars)
        )
    }
}

Here instead of adding Insets padding to the DarkGrey Box like the last time, we added LightGray Spacers which take up the exact sizes of the status bar and navigation bar.

Resize component padding with Keyboard IME

There are times when we would want to apply dynamic padding to our UI component based on whether the keyboard IME is open or closed. A good use case is when we add an input field at the bottom of a list.

Consider this code:

setContent {
    Column(
        modifier = Modifier.fillMaxSize().systemBarsPadding()
    ) {
        LazyColumn(
            modifier = Modifier.weight(1f),
            reverseLayout = true
        ) {
            items(100) { index ->
                Text(text = "Item $index", modifier = Modifier.padding(16.dp).fillMaxWidth())
            }
        }

        var textFieldValue by remember { mutableStateOf(TextFieldValue()) }

        TextField(
            modifier = Modifier.fillMaxWidth(),
            value = textFieldValue,
            onValueChange = { textFieldValue = it },
            placeholder = {
                Text(text = "Type something here")
            }
        )
    }
}

If we do not handle the padding for the TextField:

Here we can see that when the keyboard opens, the TextField stays at the bottom of the screen, which does not provide a very good user experience.

After handling the TextField padding:

We will just add the imePadding() modifier to the TextField above.

The code will now look like:

// Same code as above

TextField(
    modifier = Modifier.fillMaxWidth().imePadding(), // IME padding added
    value = textFieldValue,
    onValueChange = { textFieldValue = it },
    placeholder = {
        Text(text = "Type something here")
    }
)

Now, the TextField padding will change and also animate with the changing state of the IME and thus will produce an effect that the input field is moving up along with the keyboard:

Animate keyboard IME while scrolling

There is another experimental API modifier imeNestedScroll() which when added to a scrolling container, animates and opens the keyboard when scrolling to the bottom of the container.

If we modify the above code, by adding this modifier to the LazyColumn:

// Same code as above

LazyColumn(
    modifier = Modifier.weight(1f).imeNestedScroll(), // Modifier added
    reverseLayout = true
) {

// Same code as previous

Will produce this experience:

Insets Consumption

Now, a few questions might pop into our minds at this point.

Considering any inset padding modifier (say safeDrawingPadding()), do we need to apply it only once in the Composable hierarchy? What will happen if we apply it more than once? If we apply it to a parent and then again to a child below, will the padding be added twice?

Well, here comes the concept of Insets consumption.

The in-built inset padding modifiers automatically “consume” the portion of the insets that are applied as padding. While doing deeper down the composition tree, the nested inset padding modifiers and the inset size modifiers, which are applied to the child composables know that some portion of the insets has already been consumed (or applied or considered) by the outer modifiers, and hence skip applying those insets again, thus avoiding duplication of space.

Let’s see an example to understand this:

setContent {
    var textFieldValue by remember { mutableStateOf(TextFieldValue()) }
    LazyColumn(
        Modifier.windowInsetsPadding(WindowInsets.statusBars).imePadding()
    ) {
        items(count = 30) {
            Text(
                modifier = Modifier.fillMaxWidth().padding(16.dp),
                text = "Item $it"
            )
        }
        item {
            TextField(
                modifier = Modifier.fillMaxWidth().height(56.dp),
                value = textFieldValue,
                onValueChange = { textFieldValue = it },
                placeholder = { Text(text = "Type something here") }
            )
        }
        item {
            Spacer(
                Modifier.windowInsetsBottomHeight(
                    WindowInsets.systemBars
                )
            )
        }
    }
}

This code displays a long list of items in a LazyColumn. At the bottom of the list, there is a TextField for user input, and at the end there is a Spacer which provides space for the bottom system navigation bar using a window insets size modifier. Also, an imePadding has been applied to the LazyColumn.

Here, when the keyboard is closed, the IME has no height, hence the imePadding() modifier applies no padding. Hence no insets are being consumed and the height of the Spacer at this point is the size of the bottom system bar. When the keyboard opens, the IME insets animate to match the size of the IME, and the imePadding() modifier begins to apply bottom padding to the LazyColumn. As a result, it also starts “consuming” that amount of insets.

Now at this point, an amount of the spacing for the bottom system bar has been already applied by the imePadding() modifier, therefore the height of the Spacer starts to decrease. At some point in time, when the IME padding size exceeds the size of the bottom system bar, the height of the Spacer becomes zero. When the keyboard closes the same mechanism happens in reverse.

This behavior is accomplished through communication between all windowInsetsPadding modifiers.

This is how the above code looks like in action:

Let’s see another example:

In this example, we would explore the modifier: Modifier.consumedWindowInsets(insets: WindowInsets).

This modifier is used to consume insets in the same way as the Modifier.windowInsetsPadding, but it doesn't apply the consumed insets as padding.

Another modifier is the Modifier.consumedWindowInsets(paddingValues: PaddingValues), which takes an arbitrary PaddingValues to consume.

This is useful for informing children when padding or spacing is provided by some other mechanism than the inset padding modifiers, such as an ordinary Modifier.padding or fixed-height spacers.

Consider this code:

setContent {
    Scaffold { innerPadding ->
        // innerPadding contains inset information to use and apply
        Box(
            modifier = Modifier
                .fillMaxSize()
                .background(color = Color.LightGray)
                .padding(innerPadding)
        ) {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(color = Color.Red)
                    .windowInsetsPadding(WindowInsets.safeDrawing)
            ) {
                Box(
                    modifier = Modifier
                        .fillMaxSize()
                        .background(color = Color.DarkGray)
                )
            }
        }
    }
}

This code will look like this:

We can see that there is some problem with this result. Though the innerPadding from the Scaffold lambda is applied, as a padding to the outer Box, the windowInsetsPadding(WindowInsets.safeDrawing) of the inner Box produces a duplicate padding (visible in Red color). That means, for some reason, Inset consumption did not happen here.

This is because, by default, aScaffold provides insets as parameters paddingValues for us to consume and use. Scaffold does not apply the insets to content; this responsibility is ours.

Thus if we want to avoid this duplicate padding, we need to consume the padding ourselves using the consumeWindowInsets(innerPadding) modifier.

Considering this as the updated code:

setContent {
    Scaffold { innerPadding ->
        // innerPadding contains inset information to use and apply
        Box(
            modifier = Modifier
                .fillMaxSize()
                .background(color = Color.LightGray)
                .padding(innerPadding)
                // Consume this insets so that it's not applied again when using safeDrawing in the hierarchy below
                .consumeWindowInsets(innerPadding)
        ) {
              // Remaining code
          }
        }
    }
}

will produce this:

Thus, once the innerPadding is consumed by the outer Box, the windowInsetsPadding(WindowInsets.safeDrawing) of the inner Box does not apply any duplicate padding.

That’s it for this article!

I hope this writing will help many developers understand why we need Insets and how to use them.

You can get all the examples at this repo: https://github.com/pushpalroy/ComposeInsetsPlayground