How to Merge .lottie Files

DotLottieMerger combines one or more .lottie packages into a base package.

Basic merge

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.

// 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:

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());

DotLottieMerger API reference
The Manifest — for how v1/v2 layouts are normalized

How to Merge .lottie Files

How to Merge .lottie Files

Basic merge

Choosing a collision strategy

Merging real v1 and v2 files

Related