`DotLottieReader` Class

A lightweight, read-only view over a .lottie archive. Only the manifest is parsed on construction — every other entry is read on demand when you call a getter.

Import:

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

Static constructors

`DotLottieReader.open(path, password?)`

Open a .lottie file from a filesystem path. Only the manifest is read; the file handle stays open and getters seek directly to the requested entry without reading the whole file into memory.

Parameters:
- path: string
- password?: string — pass to open a password-protected archive. Note: when a password is provided, the file is read fully into memory — the low-memory guarantee only applies to unencrypted archives.
Returns: DotLottieReader
Availability: Node.js only — there's no filesystem in the WASM build.

`DotLottieReader.fromBytes(data, password?)`

Load from a Buffer/Uint8Array. Only the manifest is parsed on construction; each getter re-reads the ZIP central directory and decompresses only the requested entry.

Parameters:
- data: Buffer (Node.js) or Uint8Array (Browser)
- password?: string — pass to decrypt a password-protected archive.
Returns: DotLottieReader
Availability: Node.js and Browser.

Manifest (no ZIP reads after construction)

reader.getManifestJson(): string
reader.animationIds(): string[]
reader.themeIds(): string[]
reader.stateMachineIds(): string[]

These are served directly from the manifest parsed at construction time.

On-demand entry getters

Each method reads exactly one ZIP entry and returns null if the entry isn't present.

reader.getAnimationJson(id: string): string | null
reader.getThemeJson(id: string): string | null
reader.getStateMachineJson(id: string): string | null
reader.getImage(filename: string): Buffer | null
reader.getFont(filename: string): Buffer | null
reader.getAudio(filename: string): Buffer | null

Both v1 (animations/, images/, audio/) and v2 (a/, i/, u/) path layouts are supported transparently.

Manifest helpers

reader.getInitialAnimationId(): string | null
reader.getInitialAnimation(): string | null // reads one ZIP entry

Query methods

reader.animationsUsingTheme(themeId: string): string[]           // manifest only, no ZIP I/O
reader.animationsUsedByStateMachine(stateMachineId: string): string[]  // one ZIP entry
reader.assetReferences(animationId: string): AssetReferences     // one ZIP entry
reader.animationsUsingAsset(filename: string): string[]          // O(n) — reads every animation entry

If you need animationsUsingAsset repeatedly, load the file with DotLottie instead, since it parses everything once up front.

Example

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

// From a file path — file handle stays open, nothing else is read yet
const reader = DotLottieReader.open("package.lottie");
console.log(reader.animationIds()); // from manifest, free
console.log(reader.stateMachineIds()); // from manifest, free

// Only this entry is decompressed and returned
const animJson = reader.getAnimationJson("hero");
if (animJson) {
  console.log(JSON.parse(animJson).nm);
}

// From a buffer — useful when you already have the bytes in memory
const reader2 = DotLottieReader.fromBytes(readFileSync("package.lottie"));
const font = reader2.getFont("MyFont.ttf"); // Buffer | null

See How to Read a .lottie File for guidance on when to reach for DotLottieReader instead of DotLottie.

Next up: DotLottieMerger Class

DotLottieReader Class