Compose: animations
Core principle
Pick the smallest API that expresses the motion and its lifecycle.
Procedure
- 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.
- Choose the matching API from the table. Prefer target-state APIs; use
Animatable only when gestures, interruption, or imperative control require it.
- Check lifecycle: an alpha animation keeps content composed;
AnimatedVisibility removes it after exit. Do not use a fade when unmounting is required.
- 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.
- Keep animated
State in layout or draw block modifiers when it changes at frame rate; route deeper diagnosis to Compose performance.
- Use Navigation Compose transitions for destination swaps it owns, and dedicated libraries for art-based motion.
- Finish when the API, lifecycle, and content identity match the UI, no simpler API fits, and the relevant behavior is verified.
API choice
| Need |
Prefer |
| Show/hide a subtree with enter/exit semantics |
AnimatedVisibility |
| One value follows state |
animate*AsState |
| Several values follow one boolean, enum, or sealed state |
rememberTransition plus child animations |
| Child size changes |
Modifier.animateContentSize() |
| Different composable trees fill one region |
AnimatedContent, or Crossfade for the simple case |
| Drag, fling, interruption, or imperative control |
Animatable |
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
1---2name: compose-animations3description: "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."4metadata:5 source: https://skillmd.com/skills/tuyv/compose-animations6---78# Compose: animations910## Core principle1112Pick the smallest API that expresses the motion and its lifecycle.1314## Procedure15161. 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.172. Choose the matching API from the table. Prefer target-state APIs; use `Animatable` only when gestures, interruption, or imperative control require it.183. Check lifecycle: an alpha animation keeps content composed; `AnimatedVisibility` removes it after exit. Do not use a fade when unmounting is required.194. For `AnimatedContent`, render from the content lambda target and choose a20 `contentKey` only when visual identity differs from payload equality. In a21 swap between distinct items, keep the target value as the identity (the22 default) or key by a stable item ID; do not collapse different items to a23 shared presence or branch key. In a review, name any rendered expression that24 captures outer target state and25 recommend using the lambda target there. If a test must prove transition26 identity, check outgoing and incoming content during the overlap; checking27 only the settled destination misses a shared-identity bug. Read28 [AnimatedContent identity](references/animated-content.md) for state-holder29 details.305. Keep animated `State` in layout or draw block modifiers when it changes at frame rate; route deeper diagnosis to [Compose performance](../compose-performance/SKILL.md).316. Use Navigation Compose transitions for destination swaps it owns, and dedicated libraries for art-based motion.327. Finish when the API, lifecycle, and content identity match the UI, no simpler API fits, and the relevant behavior is verified.3334## API choice3536| Need | Prefer |37|---|---|38| Show/hide a subtree with enter/exit semantics | [`AnimatedVisibility`](https://developer.android.com/develop/ui/compose/animation/composables-modifiers#animatedvisibility) |39| One value follows state | `animate*AsState` |40| Several values follow one boolean, enum, or sealed state | `rememberTransition` plus child animations |41| Child size changes | `Modifier.animateContentSize()` |42| Different composable trees fill one region | `AnimatedContent`, or `Crossfade` for the simple case |43| Drag, fling, interruption, or imperative control | [`Animatable`](https://developer.android.com/reference/kotlin/androidx/compose/animation/core/Animatable) |4445Use an `AnimationSpec` when the default motion is wrong and a distinct `label` when multiple animations need tooling visibility.4647```kotlin48val width by animateDpAsState(49 targetValue = if (expanded) 200.dp else 56.dp,50 animationSpec = spring(dampingRatio = 0.7f),51 label = "fabWidth",52)53```5455For values that must remain synchronized, define them on one transition rather than several independent `animate*AsState` calls:5657```kotlin58val transition = rememberTransition(targetState = phase, label = "phase")59val alpha by transition.animateFloat(label = "alpha") { target ->60 if (target == Phase.Visible) 1f else 0f61}62val offset by transition.animateDp(label = "offset") { target ->63 if (target == Phase.Visible) 0.dp else 24.dp64}65```6667For 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](https://developer.android.com/develop/ui/compose/animation/choose-api) guide; use [`rememberInfiniteTransition`](https://developer.android.com/reference/kotlin/androidx/compose/animation/core/rememberInfiniteTransition) for repeating cycles and [`SeekableTransitionState`](https://developer.android.com/reference/kotlin/androidx/compose/animation/core/SeekableTransitionState) for seekable or test-controlled progress.6869## When not to use this skill7071- For side-effect timing or click-launched work, use [Compose state and effects](../compose-state-and-effects/SKILL.md).72- For deep state-read or recomposition diagnosis, use [Compose performance](../compose-performance/SKILL.md).