compose-animations

name: compose-animations description: "Use when writing or reviewing Jetpack Compose motion: visibility enter/exit, animating one property toward a target, color or size transitions, multiple properties from one state, switching composable content, or choosing between AnimatedVisibility, animate*AsState, rememberTransition, AnimatedContent, and Crossfade."

Compose: animations

Official reference: Quick guide to Animations in Compose. See also Choose an animation API, Value-based animations, Animation modifiers and composables.

Core principle

Pick the smallest API that matches the problem: built-in visibility and layout transitions first, then a single animated value, then a shared transition object when several values must move together, then gesture-level or imperative APIs when the framework cannot express the motion.

Pick the smallest animation API

Appear and disappear

Prefer AnimatedVisibility when the UI should leave or join the tree with enter/exit transitions.

AnimatedVisibility(visible = expanded) {
    Text("Details…")
}

animateFloatAsState on alpha only fades; the composable stays in composition and continues to participate in layout unless you gate it yourself. Use that tradeoff when you intentionally keep children mounted (state, focus) but visually hidden. For true remove-from-tree behavior, use AnimatedVisibility (or conditional composition with AnimatedVisibility / AnimatedContent patterns from the quick guide).

Background color

Use animateColorAsState for smooth color targets.

For animated fills behind children, the quick guide recommends drawing with Modifier.drawBehind rather than Modifier.background() so the animated color is applied in the draw phase appropriately for performance.

val background = animateColorAsState(
    targetValue = if (selected) selectedColor else idleColor,
    label = "background",
)
Box(
    Modifier.drawBehind { drawRect(background.value) },
) { /* content */ }

Size changes

Modifier.animateContentSize() animates layout size changes—common for expanding/collapsing text or dynamic chips—without hand-rolling width/height animations.

Value-based animations (animate*AsState)

Compose provides animate*AsState for Float, Dp, Color, Size, Offset, Rect, Int, IntOffset, IntSize, and more. You supply the target; the API owns the animation state.

• Pass an AnimationSpec via animationSpec (e.g. spring, tween) when defaults are wrong for the UI.
• Set a distinct label for debugging and tooling when multiple animations exist in one composable.
• For completion or sequencing details, see Value-based animations.

val width by animateDpAsState(
    targetValue = if (expanded) 200.dp else 56.dp,
    animationSpec = spring(dampingRatio = 0.7f, stiffness = Spring.StiffnessMedium),
    label = "fabWidth",
)

Multiple properties: rememberTransition

When one piece of state (e.g. enum class Phase { A, B, C }) should drive several animated values in lockstep, use rememberTransition and define child animations on that transition:

val transition = rememberTransition(targetState = phase, label = "phase")
val alpha by transition.animateFloat(label = "alpha") { target ->
    if (target == Phase.Visible) 1f else 0f
}
val offset by transition.animateDp(label = "offset") { target ->
    if (target == Phase.Visible) 0.dp else 24.dp
}

Avoid multiple independent animate*AsState calls that should stay visually synchronized but can drift if specs or targets diverge. Older code may use updateTransition; prefer rememberTransition for new code.

Choosing between content-level APIs

Use the official Choose an animation API tree when unsure. Compressed rules:

Art-based motion (illustrations, Lottie, complex vector timelines) is outside this skill; use dedicated libraries and the “additional resources” links on Animations.

Decision flow (high level)

flowchart TD
  start[Animation_need]
  start --> showHide{Show_or_hide_subtree}
  showHide -->|yes| av[AnimatedVisibility]
  showHide -->|no| oneProp{Single_property_to_target}
  oneProp -->|yes| asState["animate*AsState"]
  oneProp -->|no| multiProp{Many_props_one_state}
  multiProp -->|yes| rt[rememberTransition]
  multiProp -->|no| swapTree{Different_composable_content}
  swapTree -->|yes| ac[AnimatedContent_or_Crossfade]
  swapTree -->|no| advanced[Animatable_or_lower_level]

AnimatedContent keys for state holders

When AnimatedContent receives a state-holder wrapper such as AsyncResult<T>, Result<T>, or a sealed UiState, decide what should actually trigger the transition. Usually the animation should run when the content shape changes (loading → content → error), not when the payload inside the same shape changes.

Use contentKey to map rich state to the animation identity:

AnimatedContent(
    targetState = result,
    contentKey = { state ->
        when (state) {
            AsyncResult.Loading -> "loading"
            is AsyncResult.Success -> "content"
            is AsyncResult.Error -> "error"
        }
    },
    label = "profile-content",
) { state ->
    when (state) {
        AsyncResult.Loading -> Loading()
        is AsyncResult.Success -> Profile(state.value)
        is AsyncResult.Error -> ErrorMessage(state.throwable)
    }
}

Without contentKey, every unequal Success(value) can be treated as new content. That is useful if a payload change should animate, but noisy when fresh data updates the same screen shape.

Choose keys by visual shape:

Animated values and composition performance

animate*AsState returns State that updates frequently. If that value feeds Modifier.offset, Modifier.graphicsLayer, scroll-adjacent layout, or other frame-rate paths, avoid reading it in the composable body with by and then passing it into value-form modifiers—use deferred reads (block modifiers, draw/ layout lambdas) instead. See compose-state-deferred-reads.

If recomposition counters spike during motion unrelated to bad stability, see compose-recomposition-performance.

Advanced pointers (read the linked docs)

• Gesture-driven or cancelable motion: Animatable with snapTo, decay, and pointerInput—Advanced animation example: Gestures and Drag, swipe, and fling.
• Infinite or repeating cycles: rememberInfiniteTransition.
• Seekable / test-controlled progress: SeekableTransitionState and related APIs for predictable timelines in tests or tooling.

Common mistakes

When not to use this skill

• Side-effect timing (LaunchedEffect, clicks launching work): use compose-side-effects.
• Deep performance tuning of where snapshot state is read: use compose-state-deferred-reads as the primary reference.