Quick Start: Loading a .lottie File

DotLottie can load an existing .lottie file directly from a filesystem path or from raw bytes.

From a file path

const { DotLottie } = require("@lottiefiles/dotlottie-io");

const dl = DotLottie.fromFile("package.lottie");

console.log(dl.animationIds());
console.log(dl.getManifestJson());

From bytes

Useful when you already have the file's contents in memory (for example, from an upload):

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

const dl = DotLottie.fromBytes(readFileSync("package.lottie"));
console.log(dl.animationIds());

Both calls are synchronous and return a fully-loaded, mutable DotLottie instance — there's no separate build() step required for reading.

Reading an animation's JSON

const heroJson = dl.getAnimationJson("hero");
if (heroJson) {
  const parsed = JSON.parse(heroJson);
  console.log(parsed.nm, parsed.fr);
}

getAnimationJson (and the equivalent methods for themes, state machines, images, fonts, and audio) return null if the ID or filename isn't found — they never throw for a missing entry.

v1 and v2 files

dotlottie-io reads both dotLottie v1 and v2 archive layouts transparently — you don't need to check the version before loading. See The Manifest for how the two layouts differ.

Loading large files without reading everything

If you only need a handful of entries from a large .lottie file, DotLottieReader reads the manifest only and fetches other entries on demand — see Reading a .lottie File for when to reach for it instead of DotLottie.

Next up: Architecture