dotLottie Rust

dotLottie Rust

dotlottie-rs is the cross-platform dotLottie runtime written in Rust. It is the engine powering all official dotLottie players — delivering the full dotLottie feature set (theming, state machines, multi-animation, and more) with guaranteed visual consistency across every platform.

It exposes a C API (via cbindgen) for native platforms and wasm-bindgen bindings for WebAssembly, serving as the core of the dotLottie players for Web, Android, iOS, Flutter, and React Native.

flowchart TD
  A[dotLottie-web] --> WASM[WASM / wasm-bindgen]
  B[dotLottie-ios] --> CAPI[C API]
  C[dotLottie-android] --> CAPI
  D[dotLottie-flutter] --> CAPI
  E[dotLottie-react-native] --> CAPI

  WASM --> dotlottiers[dotlottie-rs]
  CAPI --> dotlottiers

  dotlottiers --> Thorvg[Thorvg\Lottie renderer]

Loading

What is dotLottie?

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

Learn more about dotLottie.

Features

• Cross-platform: single Rust codebase targeting Android, iOS, Web, Flutter, React Native, and desktop
• Guaranteed visual consistency: powered by the ThorVG renderer across all platforms
• Theming & slots: runtime color, scalar, text, and vector slot overrides
• State machines: declarative interactivity engine with guards, transitions, and actions
• Multi-animation: playback control over multiple animations within a single .lottie file
• dotLottie format: full support for the .lottie container (ZIP-based, manifest v1 & v2, embedded assets)
• C API: cbindgen-generated header for native integration (Android NDK, iOS, desktop)
• WASM: wasm-bindgen bindings for WebAssembly targets

Available Players

dotlottie-rs is the runtime core used by all official dotLottie framework players:

• dotlottie-web
• dotlottie-android
• dotlottie-ios
• dotlottie-flutter
• dotlottie-react-native

Repository contents

• Crates
• Development
• License

Crates

• dotlottie-rs: The core library for dotLottie native players, including the C API (feature: c_api) and wasm-bindgen bindings (feature: wasm-bindgen-api)
• examples/c_api: Example usage of the native C API

Development

Cross-Platform Release Builds

The following instructions cover building release artifacts for Android, Apple, WASM, Linux, and native platforms using the Makefile-based build system. For Rust development, just use cargo as usual — no special setup is needed.

You will need GNU make installed. Note that Apple platform targets (iOS, macOS, tvOS, visionOS) require a Mac with Xcode. To ensure that your machine has all the necessary tools installed, run the following from the root of the repo:

make setup

This will configure all platforms. You can also setup individual platforms using:

• make android-setup - Setup Android environment (requires Android NDK)
• make apple-setup - Setup Apple environment (requires Xcode)
• make wasm-setup - Setup WASM environment (installs wasm-pack and wasm32-unknown-unknown target)

Performing builds

Builds can be performed for the following groups of targets:

• android - All Android architectures (ARM64, x86_64, x86, ARMv7)
• apple - All Apple platforms (macOS, iOS, tvOS, visionOS, macCatalyst)
• wasm - WebAssembly (software renderer) via wasm-bindgen
• wasm-webgl - WebAssembly with WebGL2 renderer via wasm-bindgen
• wasm-webgpu - WebAssembly with WebGPU renderer via wasm-bindgen
• native - Native library for current platform (C API via cbindgen)
• native-opengl - Native library with OpenGL renderer
• native-webgpu - Native library with WebGPU renderer
• linux - Linux x86_64 and ARM64

For android and apple, builds will be performed for all supported architectures, whereas for wasm, only a single target will be built. These names refer to Makefile targets that can be used to build them. For example, to build all android targets, execute the following:

make android

You can also build specific architectures:

make android-aarch64          # Android ARM64 only
make apple-macos-arm64        # macOS ARM64 only

The default target shows the help menu:

make                          # Shows comprehensive help

Native C-API

The C bindings can be generated by using the following command, which will place the include and library files in release/native:

make native

On Windows, you should use the Makefile.win make file:

make -f Makefile.win native

Examples for using the native interface can be found in the examples directory, which also contains a README with information on getting started.

Other useful targets

• test: Run all tests with single-threaded execution
• clippy: Run Rust linter with strict settings
• clean: Clean all build artifacts and Cargo cache
• list-platforms: Show all supported platforms

For platform-specific cleanup:

• android-clean: Clean Android artifacts
• apple-clean: Clean Apple artifacts
• wasm-clean: Clean WASM artifacts
• native-clean: Clean native artifacts

More information can be found by using the help target:

make help

Release Process

Manually execute the Create Release PR Github Action workflow to create a release PR. This will include all changes since the last release. This repo uses changesets to determine the new release version. The knope tool can be installed locally and used to simply the creation of changeset files.

The release PR should be checked for correctness and then merged. Once that is done, the Release Github Actions workflow will be started automatically to do the work of actually creating the new release and building & uploading the related release artifacts.

Relevant Tools

• For your dotLottie creation and modification needs
• Tools for parsing Lottie animations

License

MIT © LottieFiles