{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

SuspendAnimationKt

public final class SuspendAnimationKt


Summary

Public methods

static final void
animate(
    float initialValue,
    float targetValue,
    float initialVelocity,
    @NonNull AnimationSpec<@NonNull Float> animationSpec,
    @NonNull Function2<@NonNull Float, @NonNull FloatUnit> block
)

Target based animation that animates from the given initialValue towards the targetValue, with an optional initialVelocity.

static final void
<T extends Object, V extends AnimationVector> animate(
    @NonNull TwoWayConverter<@NonNull T, @NonNull V> typeConverter,
    @NonNull T initialValue,
    @NonNull T targetValue,
    T initialVelocity,
    @NonNull AnimationSpec<@NonNull T> animationSpec,
    @NonNull Function2<@NonNull value, @NonNull velocity, Unit> block
)

Target based animation for animating any data type T, so long as T can be converted to an AnimationVector using typeConverter.

static final void
animateDecay(
    float initialValue,
    float initialVelocity,
    @NonNull FloatDecayAnimationSpec animationSpec,
    @NonNull Function2<@NonNull Float, @NonNull FloatUnit> block
)

Decay animation that slows down from the given initialVelocity starting at initialValue until the velocity reaches 0.

static final void
<T extends Object, V extends AnimationVector> animateDecay(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull DecayAnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Decay animation that slows down from the current velocity and value captured in AnimationState until the velocity reaches 0.

static final void
<T extends Object, V extends AnimationVector> animateTo(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull T targetValue,
    @NonNull AnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Target based animation that takes the value and velocity from the AnimationState as the starting condition, and animate to the targetValue, using the animationSpec.

Public methods

animate

public static final void animate(
    float initialValue,
    float targetValue,
    float initialVelocity,
    @NonNull AnimationSpec<@NonNull Float> animationSpec,
    @NonNull Function2<@NonNull Float, @NonNull FloatUnit> block
)

Target based animation that animates from the given initialValue towards the targetValue, with an optional initialVelocity. By default, a spring will be used for the animation. An alternative animationSpec can be provided to replace the default spring.

This is a convenient method for Float animation. If there's a need to access more info related to the animation such as start time, target, etc, consider using AnimationState.animateTo. To animate non-Float data types, consider the animate overload/variant for generic types.

import androidx.compose.animation.core.RepeatMode
import androidx.compose.animation.core.animate
import androidx.compose.animation.core.infiniteRepeatable
import androidx.compose.animation.core.tween
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.Icon
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.graphicsLayer

@Composable
fun InfiniteAnimationDemo() {
    // Create a mutable state for alpha, and update it in the animation.
    val alpha = remember { mutableStateOf(1f) }
    LaunchedEffect(Unit) {
        // Animate from 1f to 0f using an infinitely repeating animation
        animate(
            initialValue = 1f,
            targetValue = 0f,
            animationSpec = infiniteRepeatable(
                animation = tween(1000),
                repeatMode = RepeatMode.Reverse
            )
        ) { value, /* velocity */ _ ->
            // Update alpha mutable state with the current animation value
            alpha.value = value
        }
    }
    Box(Modifier.fillMaxSize()) {
        Icon(
            Icons.Filled.Favorite,
            contentDescription = null,
            modifier = Modifier.align(Alignment.Center)
                .graphicsLayer(
                    scaleX = 3.0f,
                    scaleY = 3.0f,
                    alpha = alpha.value
                ),
            tint = Color.Red
        )
    }
}
Parameters
float initialVelocity

The velocity to use for the animation. 0f by default.

@NonNull AnimationSpec<@NonNull Float> animationSpec

The animation configuration that will be used. spring by default.

@NonNull Function2<@NonNull Float, @NonNull FloatUnit> block

Will be invoked on every frame with the current value and velocity of the animation for that frame.

See also
animateTo

animate

public static final void <T extends Object, V extends AnimationVector> animate(
    @NonNull TwoWayConverter<@NonNull T, @NonNull V> typeConverter,
    @NonNull T initialValue,
    @NonNull T targetValue,
    T initialVelocity,
    @NonNull AnimationSpec<@NonNull T> animationSpec,
    @NonNull Function2<@NonNull value, @NonNull velocity, Unit> block
)

Target based animation for animating any data type T, so long as T can be converted to an AnimationVector using typeConverter. The animation will start from the initialValue and animate to the targetValue value. The initialVelocity will be derived from an all-0 AnimationVector unless specified. animationSpec can be provided to create a specific look and feel for the animation. By default, a spring will be used.

This is a convenient method for target-based animation. If there's a need to access more info related to the animation such as start time, target, etc, consider using AnimationState.animateTo.

See also
animateTo

animateDecay

public static final void animateDecay(
    float initialValue,
    float initialVelocity,
    @NonNull FloatDecayAnimationSpec animationSpec,
    @NonNull Function2<@NonNull Float, @NonNull FloatUnit> block
)

Decay animation that slows down from the given initialVelocity starting at initialValue until the velocity reaches 0. This is often used after a fling gesture.

This is a convenient method for decay animation. If there's a need to access more info related to the animation such as start time, target, etc, consider using AnimationState.animateDecay.

Parameters
@NonNull FloatDecayAnimationSpec animationSpec

Defines the decay animation that will be used for this animation. Some options for this animationSpec include: splineBasedDecay and exponentialDecay.

@NonNull Function2<@NonNull Float, @NonNull FloatUnit> block

Will be invoked on each animation frame with up-to-date value and velocity.

See also
animateDecay

animateDecay

public static final void <T extends Object, V extends AnimationVector> animateDecay(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull DecayAnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Decay animation that slows down from the current velocity and value captured in AnimationState until the velocity reaches 0. During the animation, the given AnimationState will be updated with the up-to-date value/velocity, frame time, etc. This is often used to animate the result of a fling gesture.

Parameters
@NonNull DecayAnimationSpec<@NonNull T> animationSpec

Defines the decay animation that will be used for this animation. Some options for animationSpec include: splineBasedDecay and exponentialDecay.

boolean sequentialAnimation

Indicates whether the animation should use the AnimationState.lastFrameTimeNanos as the starting time (if true), or start in a new frame. By default, sequentialAnimation is false, to start the animation in a few frame. In cases where an on-going animation is interrupted and a new animation is started to carry over the momentum, using the interruption time (captured in AnimationState.lastFrameTimeNanos) creates a smoother animation.

@ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block

will be invoked on every frame during the animation, and the AnimationScope will be checked against cancellation before the animation continues. To cancel the animation from the block, simply call AnimationScope.cancelAnimation. After AnimationScope.cancelAnimation is called, block will not be invoked again. The animation loop will exit after the block returns. All the animation related info can be accessed via AnimationScope.

animateTo

public static final void <T extends Object, V extends AnimationVector> animateTo(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull T targetValue,
    @NonNull AnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Target based animation that takes the value and velocity from the AnimationState as the starting condition, and animate to the targetValue, using the animationSpec. During the animation, the given AnimationState will be updated with the up-to-date value/velocity, frame time, etc.

import androidx.compose.animation.core.AnimationState
import androidx.compose.animation.core.Spring
import androidx.compose.animation.core.animate
import androidx.compose.animation.core.animateTo
import androidx.compose.animation.core.isFinished
import androidx.compose.animation.core.spring
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember

@Composable
fun simpleAnimate(
    target: Float,
): Float {
    // Create an AnimationState to be updated by the animation.
    val animationState = remember { AnimationState(target) }

    // Launch the suspend animation into the composition's CoroutineContext, and pass
    // `target` to LaunchedEffect so that when`target` changes the old animation job is
    // canceled, and a new animation is created with a new target.
    LaunchedEffect(target) {
        // This starts an animation that updates the animationState on each frame
        animationState.animateTo(
            targetValue = target,
            // Use a low stiffness spring. This can be replaced with any type of `AnimationSpec`
            animationSpec = spring(stiffness = Spring.StiffnessLow),
            // If the previous animation was interrupted (i.e. not finished), configure the
            // animation as a sequential animation to continue from the time the animation was
            // interrupted.
            sequentialAnimation = !animationState.isFinished
        )
        // When the function above returns, the animation has finished.
    }
    // Return the value updated by the animation.
    return animationState.value
}
Parameters
@NonNull T targetValue

The target value that the animation will animate to.

@NonNull AnimationSpec<@NonNull T> animationSpec

The animation configuration that will be used. spring by default.

boolean sequentialAnimation

Indicates whether the animation should use the AnimationState.lastFrameTimeNanos as the starting time (if true), or start in a new frame. By default, sequentialAnimation is false, to start the animation in a few frame. In cases where an on-going animation is interrupted and a new animation is started to carry over the momentum, using the interruption time (captured in AnimationState.lastFrameTimeNanos) creates a smoother animation.

@ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block

Will be invoked on every frame, and the AnimationScope will be checked against cancellation before the animation continues. To cancel the animation from the block, simply call AnimationScope.cancelAnimation. After AnimationScope.cancelAnimation is called, block will not be invoked again. The animation loop will exit after the block returns. All the animation related info can be accessed via AnimationScope.