# Merge Instances
Learn how to combine multiple DotLottie instances into a single file using the merge functionality in dotlottie-js.

# Merge 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()`](/docs/tools/dotlottie-js/reference/dotlottie-class#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.

```javascript
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: { rules: [{ id: "bg_color", type: "Color", value: [0, 0, 0, 1] }] }, // { rules: [...] }, see Managing Themes
    // 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: { rules: [{ id: "bg_color", type: "Color", value: [1, 1, 1, 1] }] },
    // 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:**

1. **Design for Uniqueness:** Use unique IDs from the start (e.g., prefix IDs based on their source).
2. **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](/docs/tools/dotlottie-js/how-to-guides/export-a-lottie-file)