# How to Merge .lottie Files
Combine multiple .lottie packages into one with DotLottieMerger, and choose a collision strategy for duplicate IDs.

# How to Merge .lottie Files

[`DotLottieMerger`](/docs/tools/dotlottie-io/api/dotlottie-merger-class) combines one or more `.lottie` packages into a base package.

## Basic merge

```javascript
const { DotLottieBuilder, DotLottieMerger, MergeStrategy } = require("@lottiefiles/dotlottie-io");

function build(id) {
  const b = new DotLottieBuilder();
  b.addAnimation(id, JSON.stringify(lottieJson));
  return b.build();
}

const merger = new DotLottieMerger(MergeStrategy.Rename);
const result = merger.merge(build("hero"), [build("hero"), build("outro")]);

console.log(result.animationIds()); // ['hero', 'hero_1', 'outro']
```

`merge()` doesn't modify the inputs — it returns a new `DotLottie` containing the combined content.

## Choosing a collision strategy

Pass the strategy to the constructor (default is `MergeStrategy.Rename`):

| Strategy               | Animations / Themes / State Machines     | Assets                                 |
| ---------------------- | ---------------------------------------- | -------------------------------------- |
| `MergeStrategy.Rename` | Appends `_1`, `_2`, … to the incoming ID | Renames the incoming file the same way |
| `MergeStrategy.Skip`   | Silently drops the incoming item         | Silently drops the incoming file       |
| `MergeStrategy.Fail`   | Throws on any collision                  | Throws on any collision                |

Asset references inside animation JSON are rewritten automatically to point at any renamed files, so a `Rename` merge never leaves a dangling reference.

```javascript
// Stop the merge outright if any IDs collide
const strictMerger = new DotLottieMerger(MergeStrategy.Fail);
strictMerger.merge(base, [incoming]); // throws if `incoming` shares an ID with `base`
```

## Merging real v1 and v2 files

`DotLottieMerger` works regardless of which archive version each input was originally written in — both are normalized to v2 internally before merging:

```javascript
const { DotLottie, DotLottieMerger, MergeStrategy } = require("@lottiefiles/dotlottie-io");
const { readFileSync } = require("node:fs");

const v1 = DotLottie.fromBytes(readFileSync("legacy.lottie")); // v1 archive
const v2 = DotLottie.fromBytes(readFileSync("modern.lottie")); // v2 archive

const merged = new DotLottieMerger(MergeStrategy.Rename).merge(v1, [v2]);
console.log(merged.animationIds());
```

## Related

- [`DotLottieMerger` API reference](/docs/tools/dotlottie-io/api/dotlottie-merger-class)
- [The Manifest](/docs/tools/dotlottie-io/core-concepts/manifest) — for how v1/v2 layouts are normalized