Compose: animations

Core principle

Pick the smallest API that expresses the motion and its lifecycle.

Procedure

1. Identify the job: show or hide a subtree, animate one value, coordinate values from one state, resize content, swap content, or handle user-driven motion.
2. Choose the matching API from the table. Prefer target-state APIs; use Animatable only when gestures, interruption, or imperative control require it.
3. Check lifecycle: an alpha animation keeps content composed; AnimatedVisibility removes it after exit. Do not use a fade when unmounting is required.
4. For AnimatedContent, render from the content lambda target and choose a contentKey only when visual identity differs from payload equality. In a swap between distinct items, keep the target value as the identity (the default) or key by a stable item ID; do not collapse different items to a shared presence or branch key. In a review, name any rendered expression that captures outer target state and recommend using the lambda target there. If a test must prove transition identity, check outgoing and incoming content during the overlap; checking only the settled destination misses a shared-identity bug. Read AnimatedContent identity for state-holder details.
5. Keep animated State in layout or draw block modifiers when it changes at frame rate; route deeper diagnosis to Compose performance.
6. Use Navigation Compose transitions for destination swaps it owns, and dedicated libraries for art-based motion.
7. Finish when the API, lifecycle, and content identity match the UI, no simpler API fits, and the relevant behavior is verified.

API choice

Use an AnimationSpec when the default motion is wrong and a distinct label when multiple animations need tooling visibility.

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

For values that must remain synchronized, define them on one transition rather than several independent animate*AsState calls:

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
}

For animated fills, prefer drawBehind { drawRect(color.value) } over a value-form background when the color updates every frame. For an API ambiguity, start with the official Choose an animation API guide; use rememberInfiniteTransition for repeating cycles and SeekableTransitionState for seekable or test-controlled progress.

When not to use this skill

• For side-effect timing or click-launched work, use Compose state and effects.
• For deep state-read or recomposition diagnosis, use Compose performance.