Migration Guide (from pre-1.0.0)

This guide is for users migrating from dotlottie-js versions prior to 1.0.0 to versions 1.0.0 and above.

Significant changes were introduced around the 1.0.0 release, primarily to:

• Fully embrace the dotLottie V2 specification, including support for themes and state machines.

• Introduce a more robust and consistent API centered around the DotLottie class (for V2) and DotLottieV1 class (for V1 interaction).

• Streamline the library structure and export strategy.

Key Changes and How to Adapt

1. Class-Based Approach: DotLottie (V2 Focus) & DotLottieV1

• Previously: Development might have relied more on standalone functions or potentially different class structures.

• Now: The primary interaction is through the DotLottie class (for V2 features and handling V1/V2 loading) and the DotLottieV1 class (specifically for V1 creation).

1.1. Automatic V1 to V2 Conversion on Load

A key aspect of the modern DotLottie class is its ability to handle older V1 format files gracefully. When you load an ArrayBuffer from a V1 .lottie file using methods like new DotLottie().fromArrayBuffer() or new DotLottie().fromURL() on a DotLottie (V2) instance, the library automatically converts the V1 data internally into a V2-compatible structure.

import { DotLottie } from "@dotlottie/dotlottie-js";

// Assume 'v1ArrayBuffer' contains the ArrayBuffer of a V1 .lottie file
async function loadV1File(v1ArrayBuffer) {
  const dotlottie = new DotLottie().fromArrayBuffer(v1ArrayBuffer);
  // The 'dotlottie' instance now holds the data in a V2 structure
  // and can be interacted with using the V2 API.
  // Exporting this instance will result in a V2 .lottie file.
}

This means you can generally use the standard DotLottie class to load most .lottie files, and the library takes care of the underlying version handling for loading purposes. Exporting will always produce a V2 file from a DotLottie instance.

2. Creation

new DotLottie() Preferred for V2, new DotLottieV1() or makeDotLottie('v1') for V1

• Previously: Older utilities might have been the primary way to create V1 instances.

• Now:

  • For V2 features (themes, state machines) or loading unknown files, use: new DotLottie(). See DotLottie.

  • To explicitly create a V1 instance, you can use either:

    • new DotLottieV1(): Offers class-based methods for configuration. See DotLottieV1.

    • makeDotLottie('v1'): A factory function that returns a DotLottieV1 instance when passed the version argument 'v1'. See makeDotLottie().

  import { DotLottie, DotLottieV1, makeDotLottie } from "@dotlottie/dotlottie-js";
  
  // V2 Approach (Recommended for new projects / V2 features)
  const dlV2 = new DotLottie();
  dlV2.addAnimation({
    id: "anim",
    data: {
      /* ... */
    },
  });
  dlV2.addTheme({
    id: "dark",
    data: {
      /* ... */
    },
  });
  
  // Explicit V1 Creation (Option A: Class)
  const dlV1_class = new DotLottieV1();
  dlV1_class.addAnimation({
    id: "anim_v1",
    data: {
      /* ... */
    },
  });
  
  // Explicit V1 Creation (Option B: Utility Function)
  const dlV1_util = makeDotLottie("v1");
  dlV1_util.addAnimation({
    id: "anim_v1_alt",
    data: {
      /* ... */
    },
  });

If you encounter specific issues, refer to the library's GitHub repository for examples or consider opening an issue.

Next up: Understanding the dotLottie Format Overview