Core Concepts: Merging DotLottie Instances

Combine multiple DotLottie instances into a new, single instance using the merge functionality.

This is useful for:

Combining separate .lottie files into one master file.
Creating a composite .lottie from various components (e.g., a base animation + multiple themes).

Basic Merging with `instance.merge()`

The merge() method creates and returns a new DotLottie instance containing the merged content of the instance it's called on plus any other instances passed as arguments. It does not modify the original instances.

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

async function main() {
  // Instance 1: Contains animation A and theme Dark
  const dotlottie1 = new DotLottie();
  await dotlottie1.addAnimation({
    id: "animation_A",
    data: { /* Lottie JSON for A */ v: "5.9.6" }, // Example data
  });
  dotlottie1.addTheme({
    id: "theme_dark",
    data: { /* Dark theme data */ colors: { p: "#fff" } },
    // name: "Dark Theme" // Optional name
    // zipOptions: { ... } // Optional compression options
  });
  // Note: Build is not strictly necessary on source instances before merge,
  // but ensures they are internally consistent if needed elsewhere.

  // Instance 2: Contains animation B and theme Light
  const dotlottie2 = new DotLottie();
  await dotlottie2.addAnimation({
    id: "animation_B",
    data: { /* Lottie JSON for B */ v: "5.9.6" }, // Example data
  });
  dotlottie2.addTheme({
    id: "theme_light",
    data: { /* Light theme data */ colors: { p: "#000" } },
    // name: "Light Theme" // Optional name
  });

  // Instance 3: Contains animation C
  const dotlottie3 = new DotLottie();
  await dotlottie3.addAnimation({
    id: "animation_C",
    data: { /* Lottie JSON for C */ v: "5.9.6" }, // Example data
  });

  try {
    // Merge dotlottie1, dotlottie2, and dotlottie3 into a new instance
    // The call originates from dotlottie1, but it doesn't matter which instance initiates.
    const mergedInstance = dotlottie1.merge(dotlottie2, dotlottie3); // merge() is synchronous

    console.log("Merge successful! Created new merged instance.");

    // The original instances (dotlottie1, dotlottie2, dotlottie3) remain unchanged.

    // The new mergedInstance contains:
    // - animation_A, animation_B, animation_C
    // - theme_dark, theme_light (each with their respective data, optional names, and optional zipOptions)

    console.log(
      "Animations in new merged instance:",
      mergedInstance.animations.map((a) => a.id)
    );
    console.log(
      "Themes in new merged instance:",
      mergedInstance.themes.map((t) => t.id)
    );

    // Build the new merged instance before exporting
    await mergedInstance.build();
    console.log("Merged instance built, ready for export.");
    // const mergedBuffer = await mergedInstance.toArrayBuffer();
    // await mergedInstance.download('merged-animations.lottie');
  } catch (error) {
    // This will likely catch errors from duplicate IDs
    console.error("Merge failed:", error);
  }
}
main();

Key Points:

merge() creates and returns a new DotLottie instance. It does not modify the instance it's called on or the arguments.
It accepts one or more DotLottie instances as arguments (...dotlotties).
The merge operation itself is synchronous, but you must await build() on the returned merged instance before exporting.
Crucially: merge() will throw an error if any duplicate IDs are found across animations, themes, or state machines from the combined set of instances (the calling instance + all arguments).

Handling ID Conflicts

Because merging instances with duplicate IDs (for animations, themes, or state machines) causes an error, you must ensure ID uniqueness across all instances you intend to merge.

Strategies:

Design for Uniqueness: Use unique IDs from the start (e.g., prefix IDs based on their source).
Rename Before Merge: If dealing with existing instances with potential conflicts, you would need to:
- Load each instance.
- Programmatically inspect and rename conflicting animation/theme/state machine IDs within each instance before attempting the merge. This involves:
  - Getting the item (e.g., getAnimation(oldId)).
  - Modifying its id property (and potentially data referencing it).
  - Removing the old item (removeAnimation(oldId)).
  - Adding the item back with the new ID (addAnimation({ id: newId, ... })).
- Then call merge() on the instances with guaranteed unique IDs.

Merging requires careful ID management to avoid errors.

Next up: Exporting .lottie Files

Merging Instances

Core Concepts: Merging DotLottie Instances

Basic Merging with instance.merge()

Handling ID Conflicts

Basic Merging with `instance.merge()`