Compottie

<a href="https://lottie.github.io/lottie-spec/1.0/"><img width="144" height="56" alt="image" src="https://lottie.github.io/compliance-buttons/lottie-1.0-light.svg" /></a>

Compose Multiplatform library for rendering Lottie animations

Installation

[!IMPORTANT] Starting from v2.0 Compottie has its own multiplatform rendering engine without any platform delegates. <br>List of supported AE Lottie features can be found here

| Module | Description | |:------------------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | compottie | Main module with rendering engine and JsonString animation spec. | | compottie-lite | The same as compottie, but without expressions support. Has about 2 times smaller binary size. | | | | compottie-dot | Contains dotLottie and ZIP animation spec. | | compottie-network | Contains Url animation spec and asset/font managers (with Ktor3 and local cache with Okio). Allows loading animations and assets from web. | | compottie-network-core | Contains base HttpClient-free implementations for network module. Allows to specify custom HTTP client (Ktor3 or any other). | | compottie-resources | Contains asset and font managers powered by official Compose resources. |

Add as a Gradle dependency

[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" }

[!NOTE] For projects with Android minSdk < 26 dot and network modules require desugaring

Usage

• Basic Usage
• LottieComposition
• Animating/Updating Progress
• LottieAnimatable
• dotLottie (ZIP)
• Images
• Fonts
• URL loading
• Dynamic Properties

Basic Usage

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"
)

Or with the rememberLottiePainter overload that merges rememberLottiePainter and animateLottieCompositionsState()

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

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

LottieComposition

LottieComposition is the parsed version of your Lottie json file. It is stateless and can be cached/reused freely. Call rememberLottieComposition(spec) to create new composition. LottieCompositionSpec is an open interface that lets you select the animation source (string/zip, network/assets, etc.).

For example:

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

val animFromUrl by rememberLottieComposition {
    LottieCompositionSpec.Url("https://example.com/anim.lotie")
}

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

The type returned from rememberLottieComposition is

interface LottieCompositionResult : State<LottieComposition?>

This allows you to use it in two ways:

val composition: LottieComposition? by rememberLottieComposition(spec)

This will return null until the composition is parsed and then will return the LottieComposition object. Use this version in most cases, especially if you don't need any of the extra functionality on LottieCompositionResult.

val compositionResult: LottieCompositionResult = rememberLottieComposition(spec)

LottieCompositionResult lets you:

1. Access the composition via compositionResult.value
2. Access error, isLoading, isComplete, isFailure, and isSuccess properties.
3. Call await() to await the parsed composition from a coroutine.

Animating/Updating Progress

You have the option of handling progress entirely yourself. If you choose to do that, just pass in progress to your LottieAnimation composable.

In most cases, you will want to use either animateLottieCompositionAsState() or LottieAnimatable. These APIs were designed to be analogous to the standard Jetpack Compose APIs. animateLottieCompositionAsState is analogous to animate*AsState and LottieAnimatable is analogous to Animatable.

The decision for whether to use one over the other is similar as well:

• If your animation is very simple or a function of other state properties, use animateLottieCompositionAsState().
• If you need to imperatively call animate or snapTo from something like a LaunchedEffect then use LottieAnimatable.

animateLottieCompositionAsState() returns and LottieAnimatable implements:

interface LottieAnimationState : State<Float>

animateLottieCompositionAsState()

val progress by animateLottieCompositionAsState(composition)

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

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

LottieAnimatable

@Stable
class MyHoistedState {
    val lottieAnimatable = LottieAnimatable()
    val somethingElse by mutableStateOf(0f)
}

val composition by rememberLottieComposition(LottieCompositionSpec.RawRes(R.raw.animation))
val lottieAnimatable = rememberLottieAnimatable()
LaunchedEffect(Unit) {
    lottieAnimatable.animate(
        composition,
        iterations = Compottie.IterateForever,
        clipSpec = LottieClipSpec.Progress(0.5f, 0.75f),
    )
}

dotLottie (ZIP)

dotLottie is an open-source file format that aggregates one or more Lottie files and their associated resources into a single file. They are ZIP archives compressed with the Deflate compression method and carry the file extension of ".lottie".

dotLottie animations are up to 10x smaller in size and can have auto-linked bundled assets (as well as external assets ofc).

compottie-dot module is required to use dotLottie animations in your app. It brings the new type of composition spec - LottieCompositionSpec.DotLottie.

You can also use DotLottie composition spec even without making a .lottie file just by ZIPping your animation with assets using deflate algorithm. The only limitation - animation can't be named as "manife