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:

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 DotLottie class is designed primarily for the V2 format and its features (themes, state machines).

• When loading data (fromArrayBuffer, fromURL), it automatically detects V1 .lottie files 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 DotLottieV1 class.

• new DotLottieV1() creates an instance that adheres to the V1 structure.

3. makeDotLottie() Utility

• The makeDotLottie() utility function is also exported. See makeDotLottie().

• This is a generic factory function. To create a DotLottieV1 instance, you must pass the version argument: makeDotLottie('v1').

• Passing 'v2' creates a DotLottie (V2) instance: makeDotLottie('v2'). The version argument 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() or makeDotLottie('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.

manifest.json Reference

Every .lottie file contains a manifest.json at its root describing the contents:

• version: Format version (e.g., "2" for V2).

• generator: Tool/library used to produce the file (e.g., "@dotlottie/dotlottie-js@x.y.z").

• animations: Array listing Lottie animations. Each entry includes an id and can have name, initialTheme, etc. See Manage Animations. Animation JSON is stored at a/<animation_id>.json.

• themes (Optional, V2+): Array listing theme definitions. See Manage Themes. Theme data is stored at t/<theme_id>.json.

• stateMachines (Optional, V2+): Array listing state machine definitions. See Manage State Machines. State machine data is stored at s/<state_machine_id>.json.

• activeAnimationId (Optional): ID of the default animation to play.

• author, description, keywords, custom data fields.

Next up: Create and Export a .lottie File