How to Read a .lottie File

There are two ways to read a .lottie file, and which one you want depends on whether you need to modify it and how large it is.

Option 1: Full load with DotLottie

Use this when you plan to modify the package after reading it, or when the file is small enough that loading everything into memory doesn't matter.

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

const dl = DotLottie.fromFile("package.lottie");
// or: DotLottie.fromBytes(readFileSync('package.lottie'))

dl.animationIds();
dl.getAnimationJson("hero");

Every entry is parsed on load, so subsequent reads and any mutations (addAnimation, removeTheme, etc.) are immediate.

Option 2: Lazy access with DotLottieReader

Use this when you only need a handful of specific entries out of a large archive, or you want to minimize memory use.

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

// Holds a live file handle — nothing but the manifest is read up front
const reader = DotLottieReader.open("large-library.lottie");

console.log(reader.animationIds()); // from the manifest, free
const heroJson = reader.getAnimationJson("hero"); // reads exactly one ZIP entry

DotLottieReader.open() keeps the file handle open and seeks directly to each requested entry — the rest of the archive is never read into memory. This is Node.js-only (there's no filesystem in WASM); in the browser, use fromBytes:

const reader = DotLottieReader.fromBytes(uint8ArrayOfFileContents);
const font = reader.getFont("MyFont.ttf"); // Buffer | null

DotLottieReader is read-only — there's no method to mutate through it or promote it to a DotLottie in place. If you decide partway through that you need to mutate what you've loaded, load the same source again with DotLottie.fromFile/fromBytes instead.

Which to use

Related

• Architecture

• DotLottie API reference

• DotLottieReader API reference