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

SingleValueAnimationKt

public final class SingleValueAnimationKt


Summary

Public methods

static final @NonNull Animatable<@NonNull Color, @NonNull AnimationVector4D>
Animatable(@NonNull Color initialValue)

This Animatable function creates a Color value holder that automatically animates its value when the value is changed via animateTo.

static final @NonNull State<@NonNull Color>
@Composable
animateColorAsState(
    @NonNull Color targetValue,
    @NonNull AnimationSpec<@NonNull Color> animationSpec,
    @NonNull String label,
    Function1<@NonNull ColorUnit> finishedListener
)

Fire-and-forget animation function for Color.

Public methods

Animatable

public static final @NonNull Animatable<@NonNull Color, @NonNull AnimationVector4DAnimatable(@NonNull Color initialValue)

This Animatable function creates a Color value holder that automatically animates its value when the value is changed via animateTo. Animatable supports value change during an ongoing value change animation. When that happens, a new animation will transition Animatable from its current value (i.e. value at the point of interruption) to the new target. This ensures that the value change is always continuous using animateTo. If spring animation (i.e. default animation) is used with animateTo, the velocity change will be guaranteed to be continuous as well.

Unlike AnimationState, Animatable ensures mutual exclusiveness on its animation. To do so, when a new animation is started via animateTo (or animateDecay), any ongoing animation job will be cancelled via a kotlinx.coroutines.CancellationException.

Animatable also supports animating data types other than Color, such as Floats and generic types. See androidx.compose.animation.core.Animatable for other variants.

import androidx.compose.animation.Animatable
import androidx.compose.animation.core.AnimationSpec
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.ui.graphics.Color

@Composable
fun animate(
    targetValue: Color,
    animationSpec: AnimationSpec<Color>,
    onFinished: (Color) -> Unit
): Color {
    // Creates an Animatable of Color, and remembers it.
    val color = remember { Animatable(targetValue) }
    val finishedListener = rememberUpdatedState(onFinished)
    // Launches a new coroutine whenever the target value or animation spec has changed. This
    // automatically cancels the previous job/animation.
    LaunchedEffect(targetValue, animationSpec) {
        color.animateTo(targetValue, animationSpec)
        // Invokes finished listener. This line will not be executed if the job gets canceled
        // halfway through an animation.
        finishedListener.value(targetValue)
    }
    return color.value
}
Parameters
@NonNull Color initialValue

initial value of the Animatable

animateColorAsState

@Composable
public static final @NonNull State<@NonNull ColoranimateColorAsState(
    @NonNull Color targetValue,
    @NonNull AnimationSpec<@NonNull Color> animationSpec,
    @NonNull String label,
    Function1<@NonNull ColorUnit> finishedListener
)

Fire-and-forget animation function for Color. This Composable function is overloaded for different parameter types such as Dp, Float, Int, Size, Offset, etc. When the provided targetValue is changed, the animation will run automatically. If there is already an animation in-flight when targetValue changes, the on-going animation will adjust course to animate towards the new target value.

animateColorAsState returns a State object. The value of the state object will continuously be updated by the animation until the animation finishes.

Note, animateColorAsState cannot be canceled/stopped without removing this composable function from the tree. See Animatable for cancelable animations.

import androidx.compose.animation.animateColorAsState
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.material.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color

@Composable
fun ColorAnimation(primary: Boolean) {
    // Animates to primary or secondary color, depending on whether [primary] is true
    // [animateState] returns the current animation value in a State<Color> in this example. We
    // use the State<Color> object as a property delegate here.
    val color: Color by animateColorAsState(
        if (primary) MaterialTheme.colors.primary else MaterialTheme.colors.secondary
    )
    Box(modifier = Modifier.background(color))
}
Parameters
@NonNull Color targetValue

Target value of the animation

@NonNull AnimationSpec<@NonNull Color> animationSpec

The animation that will be used to change the value through time, spring by default

@NonNull String label

An optional label to differentiate from other animations in Android Studio.

Function1<@NonNull ColorUnit> finishedListener

An optional listener to get notified when the animation is finished.