animateBounds

[Modifier] to animate layout changes (position and/or size) that occur within a [LookaheadScope].

Common

public fun Modifier.animateBounds(
    lookaheadScope: LookaheadScope,
    modifier: Modifier = Modifier,
    boundsTransform: BoundsTransform = DefaultBoundsTransform,
    animateMotionFrameOfReference: Boolean = false,
): Modifier

Modifier to animate layout changes (position and/or size) that occur within a LookaheadScope.

So, the given lookaheadScope defines the coordinate space considered to trigger an animation. For example, if lookaheadScope was defined at the root of the app hierarchy, then any layout changes visible within the screen will trigger an animation, if it, in contrast was defined within a scrolling parent, then, as long the LookaheadScope scrolls with is content, no animation will be triggered, as there will be no changes within its coordinate space.

The animation is driven with a FiniteAnimationSpec produced by the given BoundsTransform function, which you may use to customize the animations based on the initial and target bounds.

Do note that certain Layout Modifiers when chained with animateBounds, may only cause an immediate observable change to either the child or the parent Layout which can result in undesired behavior. For those cases you can instead provide it to the modifier parameter. This allows animateBounds to envelop the size and constraints change and propagate them gradually to both its parent and child Layout.

You may see the difference when supplying a Layout Modifier in modifier on the following example:

By default, changes in position under LayoutCoordinates.introducesMotionFrameOfReference are excluded from the animation and are instead immediately applied, as they are expected to be frequent/continuous (to handle Layouts under Scroll). You may change this behavior by passing animateMotionFrameOfReference as true. Keep in mind, doing that under a scroll may result in the Layout "chasing" the scroll offset, as it will constantly animate to the latest position.

A basic use-case is animating a layout based on content changes, such as the String changing on a Text:

It also provides an easy way to animate layout changes of a complex Composable Layout:

Since BoundsTransform is called when initiating an animation, you may also use it to calculate a keyframe based animation:

It may also be used together with movableContent as long as the given LookaheadScope is in a common place within the Layout hierarchy of the slots presenting the movableContent:

Parameters


lookaheadScope	The scope from which this `animateBounds` will calculate its animations from. This implies that as long as you're expecting an animation the reference of the given `LookaheadScope` shouldn't change, otherwise you may get unexpected behavior.
modifier	Optional intermediate Modifier, may be used in cases where otherwise immediate layout changes are perceived as gradual by both the parent and child Layout.
boundsTransform	Produce a customized `FiniteAnimationSpec` based on the initial and target bounds, called when an animation is triggered.
animateMotionFrameOfReference	When `true`, changes under `LayoutCoordinates.introducesMotionFrameOfReference` (for continuous positional changes, such as Scroll Offset) are included when calculating an animation. `false` by default, where the changes are instead applied directly into the layout without triggering an animation.