Compose Multiplatform port of Lottie, enabling use of animations across various platforms with seamless integration, mirroring usage patterns detailed in the original Lottie documentation.
Compose Multiplatform library for rendering Lottie animations
[!IMPORTANT] Starting from v2.0 Compottie has its own multiplatform rendering engine without any platform delegates.
List of supported AE Lottie features can be found here
Compatibility table
| Compose Multiplatform |
|---|
Add as a Gradle dependency
[versions]
compottie="<version>"
[libraries]
compottie = { module = "io.github.alexzhirkevich:compottie", version.ref = "compottie" }
compottie-lite = { module = , version.ref = }
= { module = , version.ref = }
= { module = , version.ref = }
= { module = , version.ref = }
[!NOTE] For projects with Android minSdk < 26
dotandnetworkmodules require desugaring
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().
Resource spec requires the compottie-resources dependency. Unlike Image the Lottie composable additionally supports .
val composition by rememberLottieComposition(
LottieCompositionSpec.Resource(Res.getUri("files/anim.json"))
)
Lottie(
painter = rememberLottiePainter(
composition = composition,
iterations = Compottie.IterateForever
),
contentDescription = "Lottie animation"
)
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 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"))
)
urlAnim rememberLottieComposition(
LottieCompositionSpec.Url()
)
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:
compositionResult.valueerror, isLoading, isComplete, isFailure, and isSuccess properties.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:
animateLottieCompositionAsState().animate or snapTo from something like a LaunchedEffect then use LottieAnimatable.animateLottieCompositionAsState() returns and LottieAnimatable implements:
interface LottieAnimationState : State<Float>
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),
)
@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 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 "manifest.json" and should contain exactly one .json file.
The DotLottie composition spec works both with dotLottie and simple ZIP files.
For dotLottie files you can specify the animation to run if archive contains multiple animations
fun LottieCompositionSpec.Companion.DotLottie(
archive: ByteArray,
animationId: String?
) : LottieCompositionSpec
dotLottie files support themes. Designers can include multiple animation styles to the single .lottie file.
To select an animation theme you can use the theme parameter of the rememberLottiePainter function.
val painter = rememberLottiePainter(
composition = dotLottieComposition,
progress = progress,
theme = "night"
)
dotLottie files support state machines.
Designers can include a set of states, transitions between those states, the conditions and actions
that should occur during state transitions.
It makes the animation interactive out of the box.
To display a state machine you should use the LottieAnimatable with the Lottie composable.
val animatable = rememberLottieAnimatable()
Lottie(
painter = rememberLottiePainter(
composition = dotLottieComposition,
progress = animatable::value
),
stateMachine = rememberLottieStateMachine(
id = "state_machine_id",
composition = dotLottieComposition,
animatable = animatable
),
contentDescription = "Interactive animation"
)
Images should be avoided whenever possible. They are much larger, less performant, and can lead to pixelation. Whenever possible, try and make your animation consist solely of vectors. However, Lottie does support images in one of 4 ways:
LottieCompositionSpec.DotLottie (requires module) or downloaded via the internet and loaded via ;LottieAssetsManager should be passed to rememberLottieComposition to load external resources.
compottie-resources provides ready-to-use implementation that loads assets from compose-resources:
val painter = rememberLottiePainter(
composition = composition,
assetsManager = rememberResourcesAssetsManager(
directory = "files", // by default
readBytes = Res::readBytes
)
)
Text can be drawn in 2 ways: using fonts and using glyphs (when characters are baked to the animation as lottie shapes)
LottieFontManager should be passed to rememberLottiePainter to use custom fonts.
compottie-resources provides ready-to-use implementation that loads fonts from compose-resources:
val painter = rememberLottiePainter(
composition = composition,
fontManager = rememberResourcesFontManager { fontSpec ->
when (fontSpec.family) {
"Comic Neue" -> Res.font.ComicNeue
else -> null // default font will be used
}
}
)
To load images remotely compottie-network module should be added as a dependensy.
This module brings an additional composition spec called LottieCompositionSpec.Url
fun LottieCompositionSpec.Companion.Url(
url : String,
format: LottieAnimationFormat,
client: HttpClient,
request : NetworkRequest,
cacheStrategy: LottieCacheStrategy,
)
that can be used to load JSON and dotLottie animations from the Internet.
LottieAnimationFormat is used to determine wheither animation is a JSON or dotLottie. If you left it Undefined,
composition spec will automatically detect is this a JSON or dotLottie file.
Ktor HTTP client can be provided with client parameter.
Caching strategy can be set with cacheStrategy parameter. By default animations are cached in the
device temp directory.
The network module also brings the NetworkAssetsManager that have similar parameters and can be used to load image assets.
If you are using Url composition spec then specifying NetworkAssetsManager is redundant.
Url composition spec automatically prepares url assets
Lottie allows you to update animation properties at runtime. Some reasons you may want to do this are:
Dynamic properties are created with rememberLottieDynamicProperties
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") {
}
}
}
}
)
You can also use wildcards for declaring dynamic properties, where ** is any level deep wildcard
and * is one level deep.
val painter = rememberLottiePainter(
composition = composition,
dynamicProperties = rememberLottieDynamicProperties {
// for each layer named 'Shape Layer 4' on any level deep
shapeLayer("**", "Shape Layer 4") {
// for each fill named 'Fill 4' on the 2nd level deep
fill("*", "Fill 4") {
color { Color.Red }
alpha { .5f }
}
}
}
)
Note, that final property building blocks (such as rotations, color, alpha) are called on EACH ANIMATION FRAME and should be cached if they don't rely on progress and have allocations or hard computations.
More info about dynamic properties for those who is not familiar with AE / Lottie format 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 Resource animation spec, asset and font managers backed by CMP resources. |
| Compottie |
|---|
| 1.12 | |
| 1.11 | |
| 1.10 |
await() to await the parsed composition from a coroutine.compottie-dotLottieCompositionSpec.UrlLottieAssetsManager;Surfaced from shared tags and platforms — no rankings paid for.