compose-animations

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. 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

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

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.

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. 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

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

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.

Documentation

Documentation