dotlottie-js: Programmatic dotLottie File Creation and Manipulation

Introduction

dotlottie-js is a comprehensive JavaScript library for programmatically creating, reading, manipulating, and exporting dotLottie (.lottie) files. Designed for both browser and Node.js environments, it provides developers with the tools to build sophisticated animation workflows, tooling, and content management systems that work with Lottie animations.

What is dotLottie?

Before understanding dotlottie-js, it's essential to understand the dotLottie (.lottie) format—an open-source, zipped archive format optimized for packaging Lottie animations. Think of it as a specialized ZIP container that bundles:

Multiple Lottie animations (JSON files)
Image assets (PNG, JPEG) used by animations
Audio assets for synchronized sound
Metadata (author, version, generator information)
Advanced V2 features like Theming and State Machines

Benefits include smaller file sizes through compression, simplified asset management, and enhanced capabilities beyond standard Lottie JSON files. Learn more at dotlottie.io.

Role in the Lottie Ecosystem

dotlottie-js occupies a specific position in the Lottie ecosystem:

┌─────────────────────────────────────────────────────────────┐
│                    Lottie Ecosystem                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Creation/Design        Animation Tools                    │
│  └─ After Effects       (e.g., LottieFiles)                │
│                                                             │
│  ┌────────────────┐    ┌──────────────────┐               │
│  │  dotlottie-js  │───▶│  .lottie files   │               │
│  │  (Builder)     │    │  (Container)     │               │
│  └────────────────┘    └──────────────────┘               │
│         │                       │                          │
│         │                       ▼                          │
│  ┌────────────────┐    ┌──────────────────┐               │
│  │  relottie      │    │ dotLottie Players│               │
│  │  (Processor)   │    │  (Playback)      │               │
│  └────────────────┘    └──────────────────┘               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

dotlottie-js: Creates and manipulates .lottie archives
Players: Render and play .lottie files (web, mobile, frameworks)
relottie: Processes and transforms Lottie JSON using AST-based plugins

Key Capabilities & Features

Core Operations

Create dotLottie Archives: Bundle multiple animations, images, and resources into a single .lottie file
Load and Parse Files: Read .lottie files from URLs, ArrayBuffers, or file systems
Manipulate Content: Add, remove, or modify animations, themes, and state machines
Manage Assets: Handle image and audio assets with automatic path resolution
Export Multiple Formats: Output as ArrayBuffer, Blob, Base64, or trigger browser downloads
Version Management: Work with and convert between V1 and V2 dotLottie structures

Advanced Features (V2)

Theming: Package multiple visual styles (color palettes, property overrides) in a single file
State Machines: Define interactive behaviors and animation control logic
Multi-Animation Support: Organize related animations with manifest-based selection
Metadata Management: Embed author, version, description, and custom metadata

Platform Support

Environment	Support	Notes
Browser	✅ Full	All features including `download()` method
Node.js	✅ Full	Use `toArrayBuffer()` with `fs` module for file I/O
Edge Functions	✅ Partial	Check runtime limitations for file I/O
Webpack/Vite	✅ Full	Standard module bundler support

Architecture & How It Works

Internal Structure

┌─────────────────────────────────────────────────────────┐
│              dotlottie-js Architecture                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐                                      │
│  │  DotLottie   │  Main API Class                      │
│  │   Instance   │                                      │
│  └──────┬───────┘                                      │
│         │                                               │
│         ├─▶ Animation Manager   (add/remove/get)      │
│         ├─▶ Theme Manager        (V2 features)        │
│         ├─▶ State Machine Mgr    (V2 features)        │
│         ├─▶ Asset Manager        (images/audio)       │
│         ├─▶ Manifest Builder     (metadata)           │
│         └─▶ ZIP Archiver         (compression)        │
│                                                         │
│  Build Process:                                        │
│  1. Validate configuration                            │
│  2. Fetch remote resources (if URLs provided)         │
│  3. Process and embed assets                          │
│  4. Generate manifest.json                            │
│  5. Create ZIP archive structure                      │
│  6. Compress and output                               │
│                                                         │
└─────────────────────────────────────────────────────────┘

Build Workflow

Instantiate: Create a DotLottie instance
Configure: Add animations, themes, state machines, and assets
Build: Call build() to fetch resources and compile the archive
Export: Use download(), toArrayBuffer(), toBlob(), or toBase64()

Feature Matrix

Feature	dotlottie-js	Players	relottie
Create .lottie files	✅ Primary	❌	❌
Modify .lottie files	✅ Primary	❌	⚠️ Indirect
Bundle animations	✅	❌	❌
Manage assets	✅	❌	❌
Add theming	✅	❌	❌
Add state machines	✅	❌	❌
Play animations	❌	✅ Primary	❌
Transform JSON	⚠️ Limited	❌	✅ Primary
AST processing	❌	❌	✅ Primary
Optimize animations	⚠️ Via assets	❌	✅
Browser runtime	✅	✅	✅
Node.js runtime	✅	❌ Most	✅

Quick Start

Installation

Install using your preferred package manager:

# npm
npm install @dotlottie/dotlottie-js

# pnpm
pnpm add @dotlottie/dotlottie-js

# yarn
yarn add @dotlottie/dotlottie-js

Basic Usage: Create and Download

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

async function createAnimation() {
  // 1. Create instance
  const dotlottie = new DotLottie();

  // 2. Add animation from URL
  dotlottie.addAnimation({
    id: "animation_1",
    url: "https://assets.lottiefiles.com/packages/lf20_jW54t3.json",
    name: "My Animation",
  });

  // 3. Build the archive
  await dotlottie.build();

  // 4. Download (browser) or export
  await dotlottie.download("my-animation.lottie");
}

Node.js: Export to File System

import { DotLottie } from "@dotlottie/dotlottie-js";
import { writeFile } from "fs/promises";

async function createAnimationNode() {
  const dotlottie = new DotLottie();

  // Add animation from local JSON object
  const animationData = {
    v: "5.9.6",
    fr: 60,
    ip: 0,
    op: 180,
    w: 512,
    h: 512,
    layers: [],
  };

  dotlottie.addAnimation({
    id: "animation_1",
    data: animationData,
  });

  await dotlottie.build();

  // Export as ArrayBuffer and save
  const arrayBuffer = await dotlottie.toArrayBuffer();
  await writeFile("output.lottie", Buffer.from(arrayBuffer));
}

Common Use Cases

1. Animation Authoring Tools

Build tools that allow designers to configure and export .lottie files:

const dotlottie = new DotLottie();

// Add multiple animations
dotlottie.addAnimation({
  id: "idle",
  data: idleAnimation,
});

dotlottie.addAnimation({
  id: "hover",
  data: hoverAnimation,
});

// Add theme for dark mode
dotlottie.addTheme({
  id: "dark",
  data: {
    colors: {
      primary: "#FFFFFF",
      accent: "#00AAFF",
    },
  },
});

await dotlottie.build();
await dotlottie.download("button-animation.lottie");

2. Server-Side Dynamic Generation

Generate customized animations on-demand:

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

async function generateUserAnimation(userId, brandColors) {
  const dotlottie = new DotLottie();

  // Fetch base animation
  dotlottie.addAnimation({
    id: "base",
    url: "https://cdn.example.com/base-animation.json",
  });

  // Add user-specific theme
  dotlottie.addTheme({
    id: "user_theme",
    data: {
      colors: brandColors,
    },
  });

  await dotlottie.build();
  return await dotlottie.toArrayBuffer();
}

3. Build Pipeline Automation

Automate animation bundling in CI/CD:

import { DotLottie } from "@dotlottie/dotlottie-js";
import { readFile, writeFile } from "fs/promises";
import { glob } from "glob";

async function bundleAnimations() {
  const dotlottie = new DotLottie();
  const animationFiles = await glob("src/animations/*.json");

  for (const file of animationFiles) {
    const data = JSON.parse(await readFile(file, "utf-8"));
    const id = file.match(/([^/]+)\.json$/)[1];

    dotlottie.addAnimation({
      id,
      data,
    });
  }

  await dotlottie.build();
  const buffer = await dotlottie.toArrayBuffer();
  await writeFile("dist/animations.lottie", Buffer.from(buffer));
}

4. Interactive Animation Builder

Create animations with state machine interactivity:

const dotlottie = new DotLottie();

dotlottie.addAnimation({
  id: "button_animation",
  data: buttonAnimationData,
});

// Add state machine for interaction
dotlottie.addStateMachine({
  id: "button_states",
  data: {
    descriptor: {
      id: "button_interaction",
      initial: "idle",
    },
    states: {
      idle: {
        animationId: "button_animation",
        segment: [0, 30],
        on: [{ event: "onMouseEnter", transitionTo: "hover" }],
      },
      hover: {
        animationId: "button_animation",
        segment: [30, 60],
        on: [
          { event: "onMouseLeave", transitionTo: "idle" },
          { event: "onClick", transitionTo: "clicked" },
        ],
      },
      clicked: {
        animationId: "button_animation",
        segment: [60, 90],
        on: [{ event: "onComplete", transitionTo: "idle" }],
      },
    },
  },
});

await dotlottie.build();

Tool Comparison

When to Use dotlottie-js

✅ Use dotlottie-js when you need to:

Create .lottie files programmatically
Bundle multiple animations into a single file
Add themes or state machines to animations
Build animation authoring tools
Generate customized animations server-side
Automate animation packaging in build pipelines
Manage assets alongside animations

❌ Don't use dotlottie-js when you:

Only need to play animations (use Players instead)
Need to transform/optimize Lottie JSON structure (use relottie)
Want to analyze animation features (use relottie)

dotlottie-js vs. Players

Aspect	dotlottie-js	Players
Purpose	Create/manipulate archives	Render/play animations
Output	`.lottie` files	Visual playback
Runtime	Build-time or server-side	Client-side (browser/mobile)
Use case	Tooling, automation	End-user experience
Asset handling	Bundle and manage	Load and render

Example workflow: Use dotlottie-js to create a .lottie file with themes, then use a Player to render it with runtime theme switching.

dotlottie-js vs. relottie

Aspect	dotlottie-js	relottie
Focus	`.lottie` container format	Lottie JSON transformation
Approach	File packaging	AST processing
Strength	Multi-animation bundles	Deep JSON manipulation
Plugin system	No	Yes (unified.js)
Asset management	Full support	Not applicable
Use case	Create archives	Transform animations

Example workflow: Use relottie to optimize/transform individual Lottie JSON files, then use dotlottie-js to bundle them with themes into a .lottie archive.

Combined Workflow

For enterprise applications, you might use all three:

// 1. Transform animations with relottie
import { relottie } from "@lottiefiles/relottie";
import relottieParse from "@lottiefiles/relottie-parse";
import relottieStringify from "@lottiefiles/relottie-stringify";
import optimizePlugin from "@lottiefiles/some-optimize-plugin";

const optimized = await relottie()
  .use(relottieParse)
  .use(optimizePlugin)
  .use(relottieStringify)
  .process(lottieJsonString);

// 2. Package with dotlottie-js
import { DotLottie } from "@dotlottie/dotlottie-js";

const dotlottie = new DotLottie();
dotlottie.addAnimation({
  id: "optimized",
  data: JSON.parse(optimized.value),
});

await dotlottie.build();
const dotlottieFile = await dotlottie.toArrayBuffer();

// 3. Play with a Player (in browser)
// <dotlottie-player src="path/to/file.lottie"></dotlottie-player>

Who Should Use dotlottie-js?

Primary Audiences

Developers building:

Animation authoring platforms (web apps, Figma plugins, desktop tools)
Content Management Systems (CMS) with animation support
Digital Asset Management (DAM) systems
Marketing automation platforms with dynamic content
Design systems with themeable animations
CI/CD pipelines with animation processing

Use case indicators:

Need to create .lottie files from code
Managing multiple animations as a package
Adding themes or interactivity to animations
Server-side animation generation
Automated animation workflows

Not Recommended For

Simple animation playback: Use dedicated Players instead
Runtime animation transformation: Use relottie for JSON manipulation
Design/creation: Use After Effects or design tools directly

API Overview

The library centers around the DotLottie class:

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

const dotlottie = new DotLottie({
  version: 2, // V1 or V2 format
  author: "Your Name",
  description: "Animation package",
});

Core Methods

Method	Purpose	Environment
`addAnimation(options)`	Add Lottie animation	Both
`addTheme(options)`	Add visual theme (V2)	Both
`addStateMachine(options)`	Add interactivity (V2)	Both
`addImage(options)`	Add image asset	Both
`build()`	Compile archive	Both
`download(filename)`	Trigger download	Browser only
`toArrayBuffer()`	Get raw binary	Both
`toBlob()`	Get Blob	Browser only
`toBase64()`	Get Base64 string	Both
`fromArrayBuffer(buffer)`	Load existing file	Both

Code Example: Complete Workflow

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

async function completeExample() {
  // Create with metadata
  const dotlottie = new DotLottie({
    version: 2,
    author: "Design Team",
    description: "Product animations with dark mode",
  });

  // Add animations
  dotlottie.addAnimation({
    id: "loading",
    url: "https://example.com/loading.json",
    name: "Loading Spinner",
  });

  dotlottie.addAnimation({
    id: "success",
    data: successAnimationData,
    name: "Success Checkmark",
  });

  // Add light and dark themes
  dotlottie.addTheme({
    id: "light",
    data: { colors: { primary: "#000000" } },
  });

  dotlottie.addTheme({
    id: "dark",
    data: { colors: { primary: "#FFFFFF" } },
  });

  // Add image asset
  dotlottie.addImage({
    id: "logo",
    url: "https://example.com/logo.png",
  });

  // Build and export
  await dotlottie.build();

  // Choose export method based on environment
  if (typeof window !== "undefined") {
    // Browser: download
    await dotlottie.download("animations.lottie");
  } else {
    // Node.js: save to file
    const buffer = await dotlottie.toArrayBuffer();
    await writeFile("animations.lottie", Buffer.from(buffer));
  }
}

Performance Considerations

Best Practices

Reuse instances: Create one DotLottie instance per archive
Build once: Call build() only after all content is added
Optimize animations: Use relottie to optimize JSON before bundling
Lazy load: For large archives, load animations on-demand from URLs
Compression: The format automatically compresses; no additional steps needed

Memory Management

Large files: Use streams when available (Node.js)
Multiple archives: Clear references after export
Asset handling: Images are automatically embedded and compressed

Next Steps

Getting Started

Installation: Set up dotlottie-js in your project
Quick Start: Creating: Create your first .lottie file
Quick Start: Loading: Load and modify existing files

Core Concepts

DotLottie Instance: Understanding the main class
Managing Animations: Add, remove, and configure animations
Managing Assets: Work with images and audio
Exporting: Output in various formats

Advanced Topics

Theming: Create multi-theme animations
State Machines: Add interactivity
Format Versions: V1 vs V2 comparison

Reference

API Reference: Complete API documentation
Platform Notes: Browser and Node.js specifics
Migration Guide: Upgrade from older versions

Ecosystem

dotlottie.io: Official format specification
dotLottie Players: Render .lottie files
relottie: Transform Lottie JSON