Legacy API Reference

This page provides a quick reference for the deprecated lottie-js API and shows the modern @lottiefiles/dotlottie-js equivalents for each method.

⚠️

Warning

This API is deprecated. Use this reference only for maintaining legacy code or planning migrations.

Core Methods

loadAnimation()

Load an animation from a URL or path.

const lottie = require("lottie-js");

lottie.loadAnimation({
  path: "animation.json",
  callback: (animation) => {
    console.log("Loaded");
  },
  error: (err) => {
    console.error(err);
  },
});

Migration Notes:

Replace callbacks with async/await
Use fromURL() instead of loadAnimation()
Create instance before calling methods

Learn more about loading animations

createDotLottie()

Create a new .lottie file with multiple animations.

lottie.createDotLottie({
  animations: [
    {
      id: 'anim1',
      data: animationJson,
      loop: true,
      autoplay: true
    }
  ],
  assets: {
    'image.png': imageBuffer
  },
  callback: (dotLottieBuffer) => {
    fs.writeFileSync('output.lottie', dotLottieBuffer);
  },
  error: (err) => {
    console.error(err);
  }
});

import { DotLottie } from "@lottiefiles/dotlottie-js";

const dotLottie = new DotLottie();

await dotLottie.addAnimation({
  id: "anim1",
  data: animationJson,
  loop: true,
  autoplay: true,
});

await dotLottie.addImage({
  id: "image",
  data: imageBuffer,
});

const arrayBuffer = await dotLottie.build();
await fs.writeFile("output.lottie", Buffer.from(arrayBuffer));

Migration Notes:

Use addAnimation() for each animation
Use addImage() for assets
Call build() to generate the file
Assets now have explicit types (image, font, etc.)

Learn more about creating files

loadFromBuffer()

Load a .lottie file from a buffer.

const buffer = fs.readFileSync('animation.lottie');

lottie.loadFromBuffer({
buffer: buffer,
callback: (dotLottie) => {
console.log('Loaded from buffer');
},
error: (err) => {
console.error(err);
}
});

import { DotLottie } from '@lottiefiles/dotlottie-js';

const buffer = await fs.readFile('animation.lottie');
const dotLottie = new DotLottie();

await dotLottie.fromArrayBuffer(buffer.buffer);
console.log('Loaded from buffer');

Migration Notes:

Use fromArrayBuffer() instead
Pass buffer.buffer for Node.js buffers
Use async/await pattern

Learn more about buffer loading

Manifest Methods

getManifest()

Get the manifest from a .lottie file.

lottie.loadFromBuffer({
  buffer: buffer,
  callback: (dotLottie) => {
    const manifest = dotLottie.getManifest();
    console.log('Version:', manifest.version);
    console.log('Animations:', manifest.animations);
  }
});

const dotLottie = new DotLottie();
await dotLottie.fromArrayBuffer(buffer);

// Direct property access
console.log("Version:", dotLottie.manifest.version);
console.log("Animations:", dotLottie.manifest.animations);

// Or get as JSON
const manifest = dotLottie.getManifest();

Migration Notes:

Access manifest property directly
Or use getManifest() method for JSON
No more nested callbacks

Learn more about manifests

setManifest()

Update the manifest.

lottie.loadFromBuffer({
  buffer: buffer,
  callback: (dotLottie) => {
    const manifest = dotLottie.getManifest();
    manifest.author = "New Author";
    dotLottie.setManifest(manifest);
  }
});

const dotLottie = new DotLottie();
await dotLottie.fromArrayBuffer(buffer);

// Use specific setter methods
dotLottie.setAuthor("New Author");
dotLottie.setVersion("1.0");

// Or update animation properties
await dotLottie.setAnimationLoop("anim1", true);

Migration Notes:

Use specific setter methods
More type-safe than raw manifest editing
Changes are validated

Animation Methods

getAnimations()

Get all animations from a .lottie file.

lottie.loadFromBuffer({
  buffer: buffer,
  callback: (dotLottie) => {
    const animations = dotLottie.getAnimations();
    animations.forEach(anim => {
      console.log('Animation ID:', anim.id);
    });
  }
});

const dotLottie = new DotLottie();
await dotLottie.fromArrayBuffer(buffer);

const animations = dotLottie.manifest.animations;
animations.forEach((anim) => {
  console.log("Animation ID:", anim.id);
});

Migration Notes:

Access via manifest.animations property
Returns metadata, not animation data
To get animation JSON, use getAnimation(id)

getAnimation()

Get a specific animation's data.

lottie.loadFromBuffer({
  buffer: buffer,
  callback: (dotLottie) => {
    const animation = dotLottie.getAnimation('anim1');
    if (animation) {
      console.log('Animation data:', animation.data);
    }
  }
});

const dotLottie = new DotLottie();
await dotLottie.fromArrayBuffer(buffer);

const animationJson = await dotLottie.getAnimation("anim1");
if (animationJson) {
  console.log("Animation data:", animationJson);
}

Migration Notes:

Now returns animation JSON directly
Method is async (returns Promise)
Returns null if animation not found

Learn more about extracting animations

addAnimation()

Add an animation to a .lottie file.

lottie.createDotLottie({
  animations: [
    {
      id: 'anim1',
      data: animationJson,
      loop: true,
      autoplay: false,
      speed: 1
    }
  ],
  callback: (buffer) => {
    // Use buffer
  }
});

const dotLottie = new DotLottie();

await dotLottie.addAnimation({
  id: "anim1",
  data: animationJson, // Or use 'url' for remote animations
  loop: true,
  autoplay: false,
  speed: 1,
});

Migration Notes:

Can use data for inline JSON or url for remote
Each animation added separately
Call build() when done adding

removeAnimation()

Remove an animation.

// Not directly supported
// Had to recreate entire file

const dotLottie = new DotLottie();
await dotLottie.fromArrayBuffer(buffer);

// Remove an animation
await dotLottie.removeAnimation("anim1");

// Rebuild
const newBuffer = await dotLottie.build();

Migration Notes:

Now directly supported
Much simpler than recreating file

Asset Methods

addAsset()

Add assets (images, fonts) to a .lottie file.

lottie.createDotLottie({
  animations: [...],
  assets: {
    'image1.png': imageBuffer,
    'font1.ttf': fontBuffer
  },
  callback: (buffer) => {
    // Use buffer
  }
});

const dotLottie = new DotLottie();

// Add animations first
await dotLottie.addAnimation({...});

// Add images
await dotLottie.addImage({
  id: 'image1',
  data: imageBuffer
});

// Add fonts (if supported)
await dotLottie.addFont({
  id: 'font1',
  data: fontBuffer
});

Migration Notes:

Assets now have explicit types
Use addImage(), addFont(), etc.
Each asset added separately

getAsset()

Get an asset from a .lottie file.

lottie.loadFromBuffer({
  buffer: buffer,
  callback: (dotLottie) => {
    const asset = dotLottie.getAsset('image1.png');
    if (asset) {
      fs.writeFileSync('extracted.png', asset);
    }
  }
});

const dotLottie = new DotLottie();
await dotLottie.fromArrayBuffer(buffer);

const imageBuffer = await dotLottie.getImage("image1");
if (imageBuffer) {
  await fs.writeFile("extracted.png", Buffer.from(imageBuffer));
}

Migration Notes:

Use typed methods: getImage(), getFont()
Returns ArrayBuffer
Method is async

Utility Methods

toBuffer()

Convert to buffer for saving.

lottie.createDotLottie({
  animations: [...],
  callback: (dotLottie) => {
    const buffer = dotLottie.toBuffer();
    fs.writeFileSync('output.lottie', buffer);
  }
});

const dotLottie = new DotLottie();
await dotLottie.addAnimation({...});

const arrayBuffer = await dotLottie.build();
await fs.writeFile('output.lottie', Buffer.from(arrayBuffer));

Migration Notes:

Use build() instead of toBuffer()
Returns ArrayBuffer
Convert to Buffer for Node.js: Buffer.from(arrayBuffer)

validate()

Validate a .lottie file.

lottie.validate({
  buffer: buffer,
  callback: (isValid, errors) => {
    if (isValid) {
      console.log('Valid');
    } else {
      console.error('Errors:', errors);
    }
  }
});

// Validation happens automatically during load
const dotLottie = new DotLottie();

try {
  await dotLottie.fromArrayBuffer(buffer);
  console.log("Valid");
} catch (err) {
  console.error("Validation error:", err.message);
}

Migration Notes:

Validation is automatic
Errors thrown on invalid files
Use try/catch for validation

Configuration Options

Options Comparison

lottie-js Option	dotlottie-js Equivalent	Notes
`path`	`fromURL(url)`	Now a method parameter
`buffer`	`fromArrayBuffer(buffer)`	Now a method parameter
`callback`	`await` / `.then()`	Use promises
`error`	`catch`	Use try/catch
`loop`	`loop`	Same in `addAnimation()`
`autoplay`	`autoplay`	Same in `addAnimation()`
`speed`	`speed`	Same in `addAnimation()`

Error Handling

Error Patterns

lottie.loadAnimation({
  path: 'animation.json',
  callback: (anim) => {
    // Success
  },
  error: (err) => {
    if (err.code === 'ENOENT') {
      console.error('File not found');
    } else if (err.code === 'INVALID_JSON') {
      console.error('Invalid JSON');
    }
  }
});

try {
  const dotLottie = new DotLottie();
  await dotLottie.fromURL("animation.json");
  // Success
} catch (err) {
  if (err.message.includes("not found")) {
    console.error("File not found");
  } else if (err.message.includes("Invalid")) {
    console.error("Invalid JSON");
  }
}

Learn more about error handling

TypeScript Support

Type Definitions

// Minimal types
import lottie from 'lottie-js';

// Most types were 'any'
lottie.loadAnimation({
path: 'animation.json',
callback: (anim: any) => {
console.log(anim);
}
});

// Complete type definitions
import {
  DotLottie,
  type Manifest,
  type Animation
} from '@lottiefiles/dotlottie-js';

const dotLottie = new DotLottie();
await dotLottie.fromURL('animation.json');

// Fully typed
const manifest: Manifest = dotLottie.manifest;
const anim: Animation = manifest.animations[0];

Learn more about TypeScript migration

Quick Reference Table

Task	lottie-js	dotlottie-js
Install	`npm i lottie-js`	`npm i @lottiefiles/dotlottie-js`
Import	`require('lottie-js')`	`import { DotLottie } from '@lottiefiles/dotlottie-js'`
Load URL	`loadAnimation({ path })`	`await dotLottie.fromURL()`
Load Buffer	`loadFromBuffer({ buffer })`	`await dotLottie.fromArrayBuffer()`
Create File	`createDotLottie({ animations })`	`await dotLottie.addAnimation()` + `build()`
Get Manifest	`dotLottie.getManifest()`	`dotLottie.manifest`
Get Animation	`dotLottie.getAnimation(id)`	`await dotLottie.getAnimation(id)`
Add Animation	Include in `animations` array	`await dotLottie.addAnimation()`
Add Asset	Include in `assets` object	`await dotLottie.addImage()`
Save File	`dotLottie.toBuffer()`	`await dotLottie.build()`
Error Handling	`error` callback	`try/catch`

Next Steps

Ready to migrate? Follow the Migration Guide
Learn the new API: Check out dotlottie-js documentation
Need help? Join our Discord community

Additional Resources

Migration Guide - Detailed migration instructions
dotlottie-js API Reference - Complete API documentation
Examples - Code examples and patterns
GitHub Repository - Source code and issues