DotLottie Class

The core class representing a loaded or built .lottie package. All methods are synchronous.

Import:

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

Static methods

DotLottie.fromFile(path, password?)

Load a .lottie file directly from a filesystem path.

• Parameters:

  • path: string — the path to the .lottie file.

  • password?: string — pass to open a password-protected archive.

• Returns: DotLottie

• Example:

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

DotLottie.fromBytes(data, password?)

Load a .lottie file from raw bytes.

• Parameters:

  • data: Buffer — e.g. the result of fs.readFileSync.

  • password?: string — pass to decrypt a password-protected archive.

• Returns: DotLottie

• Example:

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

Serialization

toBytes(password?)

Serialize the package to a .lottie ZIP Buffer.

• Parameters:

  • password?: string — pass to produce an AES-256 encrypted archive.

• Returns: Buffer

• Example:

  writeFileSync("output.lottie", dl.toBytes());

Animations

addAnimation(id, jsonData, options?)

Add an animation from Lottie JSON. Automatically extracts embedded base64 assets and rewrites their references.

• Parameters:

  • id: string — unique identifier for this animation.

  • jsonData: Buffer | string — the Lottie JSON.

  • options?: AnimationOptions

• Returns: void

removeAnimation(id)

• Parameters: id: string

• Returns: void

• Throws: if id doesn't exist.

getAnimationJson(id)

• Parameters: id: string

• Returns: string | null — the raw Lottie JSON, or null if not found.

animationIds()

• Returns: string[]

See Managing Animations for a walkthrough.

Themes

addTheme(id, name, jsonData)

• Parameters:

  • id: string

  • name: string | null — optional display name.

  • jsonData: Buffer | string

• Returns: void

removeTheme(id)

• Returns: void

• Throws: if id doesn't exist.

getThemeJson(id)

• Returns: string | null

themeIds()

• Returns: string[]

See Managing Themes.

State machines

addStateMachine(id, name, jsonData)

• Parameters:

  • id: string

  • name: string | null — optional display name.

  • jsonData: Buffer | string

• Returns: void

removeStateMachine(id)

• Returns: void

• Throws: if id doesn't exist.

getStateMachineJson(id)

• Returns: string | null

stateMachineIds()

• Returns: string[]

See Managing State Machines.

Assets

All add* methods return the actual filename stored, which may differ from the requested one on a collision — see filename deduplication.

addImage(filename, data) / getImage(filename) / imageFilenames()

• addImage(filename: string, data: Buffer): string

• getImage(filename: string): Buffer | null

• imageFilenames(): string[]

addFont(filename, data) / getFont(filename) / fontFilenames()

• addFont(filename: string, data: Buffer): string

• getFont(filename: string): Buffer | null

• fontFilenames(): string[]

addAudio(filename, data) / getAudio(filename) / audioFilenames()

• addAudio(filename: string, data: Buffer): string

• getAudio(filename: string): Buffer | null

• audioFilenames(): string[]

• Throws: InvalidAudioFormat if filename isn't .mp3.

Example:

const storedName = dl.addImage("logo.png", readFileSync("logo.png"));
console.log(storedName); // 'logo.png' (or 'logo_1.png' if that name was taken)

See Managing Assets.

Query methods

animationsUsingTheme(themeId)

• Returns: string[] — animation IDs referencing the given theme.

animationsUsedByStateMachine(stateMachineId)

• Returns: string[] — unique animation IDs referenced by the state machine's PlaybackState entries.

assetReferences(animationId)

• Returns: AssetReferences — { images: string[], fonts: string[], audio: string[] }.

animationsUsingAsset(filename)

• Returns: string[] — animation IDs that reference the given asset filename.

See Querying Relationships for worked examples.

Manifest

getManifestJson()

• Returns: string — the full manifest as JSON.

setInitial(animationId?, stateMachineId?)

• Parameters:

  • animationId?: string | null

  • stateMachineId?: string | null

• Returns: void

• Pass null to clear either field.

getInitialAnimationId()

• Returns: string | null

getInitialAnimation()

• Returns: string | null — the raw Lottie JSON of the initial animation.

See The Manifest.

Complete example

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

// Build a package from scratch
const builder = new DotLottieBuilder();
builder.generator("my-tool");
builder.addAnimation("hero", JSON.stringify(myLottieJson));
builder.addTheme("dark", "Dark Theme", JSON.stringify({ rules: [] }));
const dl = builder.build();

// Add assets
const storedName = dl.addImage("logo.png", readFileSync("logo.png"));
dl.addAudio("click.mp3", readFileSync("click.mp3"));

// Save to disk
writeFileSync("output.lottie", dl.toBytes());

// Load back and inspect
const loaded = DotLottie.fromFile("output.lottie");
console.log(loaded.animationIds()); // ['hero']
console.log(loaded.imageFilenames()); // ['logo.png']

const imgData = loaded.getImage("logo.png"); // Buffer

Next up: DotLottieBuilder Class