Compottie

Compottie provides two primary ways to control animation progress, designed to be analogous to Jetpack Compose APIs. Both implement LottieAnimationState (which is a State<Float>).

Use animateLottieCompositionAsState() for simple animations

Use this when your animation is simple or is a direct function of other state properties. It is analogous to animate*AsState.

val progress by animateLottieCompositionAsState(composition)

// With iterations
val progress by animateLottieCompositionAsState(
    composition,
    iterations = Compottie.IterateForever,
)

// With clipping
val progress by animateLottieCompositionAsState(
    composition,
    clipSpec = LottieClipSpec.Progress(0.5f, 0.75f),
)

Use LottieAnimatable for imperative control

Use this when you need to manually trigger animations (e.g., calling animate or snapTo inside a LaunchedEffect). It is analogous to Animatable.

val lottieAnimatable = rememberLottieAnimatable()

LaunchedEffect(composition) {
    lottieAnimatable.animate(
        composition,
        iterations = Compottie.IterateForever,
        clipSpec = LottieClipSpec.Progress(0.5f, 0.75f),
    )
}

// animateLottieCompositionAsState example
val progress by animateLottieCompositionAsState(composition)

// LottieAnimatable example
val lottieAnimatable = rememberLottieAnimatable()
LaunchedEffect(Unit) {
    lottieAnimatable.animate(
        composition,
        iterations = Compottie.IterateForever,
        clipSpec = LottieClipSpec.Progress(0.5f, 0.75f),
    )
}

LottieCompositionSpec is an open interface used to define the source of your animation. Different implementations allow you to load animations from various formats and locations:

• LottieCompositionSpec.JsonString(string): Load from a JSON string.
• LottieCompositionSpec.DotLottie(bytes): Load from dotLottie bytes.
• LottieCompositionSpec.Resource(uri): Load from a CMP resource URI.
• LottieCompositionSpec.Url(url): Load from a web URL.
• LottieCompositionSpec.RawRes(resId): Load from Android raw resources.

Example usage:

val jsonAnim by rememberLottieComposition {
    LottieCompositionSpec.JsonString(Res.readBytes("files/anim.json").decodeToString())
}

val dotLottieAnim by rememberLottieComposition {
    LottieCompositionSpec.DotLottie(Res.readBytes("files/anim.lottie"))
}

val urlAnim by rememberLottieComposition(
    LottieCompositionSpec.Url("https://example.com/anim.lottie")
)

val jsonAnim by rememberLottieComposition {
    LottieCompositionSpec.JsonString(
        Res.readBytes("files/anim.json").decodeToString()
    )
}

val dotLottieAnim by rememberLottieComposition {
    LottieCompositionSpec.DotLottie(
        Res.readBytes("files/anim.lottie")
    )
}

// jsonAnim and dotLottieAnim can both be replaced with

val resAnim by rememberLottieComposition(
    LottieCompositionSpec.Resource(Res.getUri("files/anim.json"))
//    LottieCompositionSpec.Resource(Res.getUri("files/anim.lottie"))
)

val urlAnim by rememberLottieComposition(
    LottieCompositionSpec.Url("https://example.com/anim.lottie")
)

When defining dynamic properties, you can use wildcards to target multiple layers or shapes without specifying exact paths:

• **: Matches any level of depth (recursive wildcard).
• *: Matches exactly one level deep.

This is helpful when you want to apply a change to every layer with a specific name, regardless of where it sits in the hierarchy.

val painter = rememberLottiePainter(
    composition = composition,
    dynamicProperties = rememberLottieDynamicProperties {
        // Targets every layer named 'Shape Layer 4' at any depth
        shapeLayer("**", "Shape Layer 4") {
            transform {
                rotation { current -> current * progress }
            }
            // Targets every fill named 'Fill 4' exactly one level deep
            fill("*", "Fill 4") {
                color { Color.Red }
                alpha { .5f }
            }
        }
    }
)

Compottie is a Compose Multiplatform library for rendering Lottie animations. Choose the module that matches your animation source requirements:

• compottie: Main module with rendering engine and JsonString spec.
• compottie-lite: Same as compottie but without expressions support (smaller binary size).
• compottie-dot: Supports dotLottie and ZIP animation specs.
• compottie-network: Supports Url spec and asset/font managers (uses Ktor3 and Okio).
• compottie-network-core: Base implementation for network module to allow custom HTTP clients.
• compottie-resources: Supports Resource spec using CMP resources.

Note: For Android projects with minSdk < 26, the dot and network modules require desugaring.

[versions]
compottie="<version>"

[libraries]
compottie = { module = "io.github.alexzhirkevich:compottie", version.ref = "compottie" }
compottie-lite = { module = "io.github.alexzhirkevich:compottie-lite", version.ref = "compottie" }
compottie-dot = { module = "io.github.alexzhirkevich:compottie-dot", version.ref = "compottie" }
compottie-network = { module = "io.github.alexzhirkevich:compottie-network", version.ref = "compottie" }
compottie-resources = { module = "io.github.alexzhirkevich:compottie-resources", version.ref = "compottie" }

Dynamic properties allow you to modify animation properties (like color, size, position, or rotation) while the animation is running. This is useful for implementing themes (day/night mode), localizing text, or reacting to user gestures.

To use them, create a dynamicProperties object using rememberLottieDynamicProperties and pass it to rememberLottiePainter.

Common use cases include:

• Changing colors for app themes.
• Localizing animation text.
• Controlling specific layer progress (e.g., for download progress).
• Responding to gestures by changing size or position.

val painter = rememberLottiePainter(
    composition = composition,
    dynamicProperties = rememberLottieDynamicProperties {
        shapeLayer("Precomposition 1", "Shape Layer 4") {
            transform {
                rotation { current -> current * progress }
            }
            fill("Group 1", "Fill 4") {
                color { Color.Red }
                alpha { .5f }
            }
        }
    }
)

To render a Lottie animation, you need to load a LottieComposition using a LottieCompositionSpec and then provide the progress to a painter.

Using Image composable

Use rememberLottieComposition to load the animation and animateLottieCompositionAsState to manage the progress state.

val composition by rememberLottieComposition {
    LottieCompositionSpec.JsonString(
        Res.readBytes("files/anim.json").decodeToString()
    )
}
val progress by animateLottieCompositionAsState(composition)

Image(
    painter = rememberLottiePainter(
        composition = composition,
        progress = { progress },
    ),
    contentDescription = "Lottie animation"
)

Using Lottie composable

The Lottie composable is a higher-level component that supports state machines. It requires the compottie-resources dependency if using LottieCompositionSpec.Resource.

val composition by rememberLottieComposition(
    LottieCompositionSpec.Resource(Res.getUri("files/anim.json"))
)

Lottie(
    painter = rememberLottiePainter(
        composition = composition,
        iterations = Compottie.IterateForever
    ),
    contentDescription = "Lottie animation"
)

You can modify animation properties (colors, transforms, opacity, etc.) at runtime using rememberLottieDynamicProperties. This is useful for theming, localization, or responding to gestures.

Wildcards

You can use wildcards to target layers or groups:

• **: Any level deep wildcard.
• *: One level deep wildcard.

Performance Note

Property building blocks (like rotation, color, or alpha) are called on every animation frame. If these operations are computationally expensive or involve allocations, cache them if they do not depend on the current progress.

val painter = rememberLottiePainter(
    composition = composition,
    dynamicProperties = rememberLottieDynamicProperties {
        shapeLayer("Precomposition 1", "Shape Layer 4") {
            transform {
                rotation { current -> current * progress }
            }
            fill("Group 1", "Fill 4") {
                color { Color.Red }
                alpha { .5f }
            }
            group("Group 4") {
                ellipse("Ellipse 1") {
                    // configure size, position of the ellipse named "Ellipse 1"
                }
                stroke("Ellipse 1 Stroke") {
                    // configure stroke named "Ellipse 1 Stroke" in the same group
                }
            }
        }
    }
)