dotLottie Format V1 vs V2
Compare dotLottie format V1 and V2. Learn how dotlottie-js handles versions with DotLottie and DotLottieV1 classes, for modern and legacy needs.
Format Versions: V1 vs. V2 & Library Handling
The dotLottie format has evolved, with version 2 (V2) introducing significant enhancements over version 1 (V1). Understanding these differences and how dotlottie-js handles them is important for effective use of the library.
dotLottie File Format: V1 vs. V2
Here are the key distinctions at the file format level:
| Feature | dotLottie V1 | dotLottie V2 |
| Manifest | manifest.json is simpler. | manifest.json is more structured and includes explicit sections for themes and state machines. Can also include more detailed metadata. |
| Theming | Not natively supported. | Supported. Themes (e.g., color palettes, property overrides) can be defined in separate JSON files (e.g., in a themes/ directory) and referenced in the manifest. |
| State Machines | Not natively supported. | Supported. State machines for interactive animations can be defined in separate JSON files (e.g., in a statemachines/ directory) and referenced in the manifest. |
| Directory Structure | Primarily animations/ and images/. | More comprehensive, often including a/ for (animations), i/ (images), u/ (audio), t/ (themes), and s/ (state machines) directories as needed. See Format Overview. |
| Asset Referencing | Basic path-based referencing. | More robust referencing, facilitating complex interactions with themes and states. |
| Extensibility | Limited. | Designed for better extensibility and future features. |
In essence, V2 is the current standard and offers a much richer feature set, especially for creating interactive and themable Lottie experiences.
dotlottie-js Library Handling of Versions
dotlottie-js is designed with a V2-first approach but provides compatibility with V1 files.
1. DotLottie Class (V2 Focus)
The main
DotLottieclass is designed primarily for the V2 format and its features (themes, state machines).When loading data (
fromArrayBuffer,fromURL), it automatically detects V1.lottiefiles and upgrades them internally to a V2 structure.This means even if you load a V1 file, you interact with it using the V2 API (e.g., accessing
dotlottie.animations).Adding V2 features (like themes or state machines) to an instance loaded from a V1 file will result in a V2 file upon export.
Recommendation: For new projects and to leverage the full capabilities of dotLottie, using
new DotLottie()is strongly recommended.
2. DotLottieV1 Class
If you explicitly need to create or work strictly with the V1 format without automatic conversion or V2 features, use the
DotLottieV1class.new DotLottieV1()creates an instance that adheres to the V1 structure.
3. makeDotLottie() Utility
The
makeDotLottie()utility function is also exported. SeemakeDotLottie().This is a generic factory function. To create a
DotLottieV1instance, you must pass the version argument:makeDotLottie('v1').Passing
'v2'creates aDotLottie(V2) instance:makeDotLottie('v2'). Theversionargument is required.
In Summary:
Default to
new DotLottie(): It provides the most modern, feature-rich experience and handles V1 files gracefully by upgrading them internally.Use
new DotLottieV1()ormakeDotLottie('v1')only if: You have a specific requirement to generate a V1 format file and do not need V2 features.
Understanding these differences helps choose the right tool for your task.