# DotLottieMerger Class
API reference for the DotLottieMerger class and MergeStrategy enum in dotlottie-io.

# `DotLottieMerger` Class

Merges one or more `.lottie` packages into a base package, with configurable collision handling.

**Import:**

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

## Constructor

### `new DotLottieMerger(strategy?)`

- **Parameters:**
  - `strategy?`: [`MergeStrategy`](#mergestrategy) — defaults to `MergeStrategy.Rename`.
- **Returns:** `DotLottieMerger`

## Merging

### `merge(base, others)`

- **Parameters:**
  - `base`: [`DotLottie`](/docs/tools/dotlottie-io/api/dotlottie-class)
  - `others`: `DotLottie[]`
- **Returns:** `DotLottie` — a new package containing the combined content. Neither `base` nor any entry in `others` is modified.

## `MergeStrategy`

An exported enum used by both `DotLottieMerger` and [`DotLottieBuilder.mergeStrategy()`](/docs/tools/dotlottie-io/api/dotlottie-builder-class#mergestrategystrategy).

```javascript
MergeStrategy.Rename; // appends _1, _2, … on collision (default)
MergeStrategy.Skip; // silently drops the incoming item on collision
MergeStrategy.Fail; // throws on any collision
```

**Collision behavior:**

| Strategy               | Animations / Themes / State Machines     | Assets (images, fonts, audio)    |
| ---------------------- | ---------------------------------------- | -------------------------------- |
| `MergeStrategy.Rename` | Appends `_1`, `_2`, … to the incoming ID | Same — renames the incoming file |
| `MergeStrategy.Skip`   | Silently drops the incoming item         | Silently drops the incoming file |
| `MergeStrategy.Fail`   | Throws on any collision                  | Throws on any collision          |

Asset path references inside animation JSON are automatically rewritten to point at renamed files.

## Example

```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']
```

See [How to Merge .lottie Files](/docs/tools/dotlottie-io/guides/merging-lottie-files) for a full walkthrough, including a real v1+v2 merge.

Next up: [Types](/docs/tools/dotlottie-io/api/types)