Core Concepts: The DotLottie Instance

The DotLottie class is the primary gateway to creating, reading, and manipulating dotLottie V2 files. This page covers fundamental operations: instantiating DotLottie, loading existing files, and the build() process.

1. Creating a New DotLottie Instance

To start working with a new .lottie file, create an instance of the DotLottie class.

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

const dotlottie = new DotLottie();

// You now have an empty DotLottie instance, ready to have content added.

Constructor Options

You can pass an optional configuration object to the DotLottie constructor. Key options include:

• generator (string, optional): A string to identify the tool or application generating the .lottie file. This will be written to the manifest.json.

  • Example: My Lottie Editor v1.2

• enableDuplicateImageOptimization (boolean, optional, default: false): When set to true, the library attempts to identify and de-duplicate identical image assets during the build() process to optimize file size.

const dotlottieWithOptions = new DotLottie({
  generator: "MyCoolApp/1.0",
  enableDuplicateImageOptimization: true,
});

2. Loading Existing .lottie Files

Load an existing .lottie file to return a new DotLottie instance using one of the following asynchronous instance methods.

await new DotLottie.fromArrayBuffer(arrayBuffer)

Loads a .lottie file from an ArrayBuffer. Suitable for browser and Node.js environments.

• Browser: Use after fetching a .lottie file or reading a local file.

• Node.js: Use after reading a file into a buffer (e.g., with fs.readFile()).

Automatic V1 to V2 Conversion: If the buffer contains a V1 dotLottie file, fromArrayBuffer automatically detects and converts it internally to a V2 representation. See Format Versions.

// Browser Example: Loading from a File Input

async function handleFileSelect(event) {
  const file = event.target.files[0];
  if (file) {
    const arrayBuffer = await file.arrayBuffer();
    const dl = new DotLottie();
    try {
      // Load the data into the existing instance
      await dl.fromArrayBuffer(arrayBuffer);
      console.log("Successfully loaded .lottie from ArrayBuffer!");
      // Now you can access dl.animations, etc.
    } catch (err) {
      console.error("Failed to load from ArrayBuffer:", err);
    }
  }
}

// Node.js Example: Loading from file system

import fs from "fs/promises";

async function loadFileNode(filePath) {
  try {
    const fileBuffer = await fs.readFile(filePath);
    const arrayBuffer = fileBuffer.buffer.slice(fileBuffer.byteOffset, fileBuffer.byteOffset + fileBuffer.byteLength);

    // Create an instance first
    const dl = new DotLottie();
    // Load the data into the instance
    await dl.fromArrayBuffer(arrayBuffer);
    console.log("Successfully loaded .lottie in Node.js!");
    // Access dl.animations, etc.
  } catch (err) {
    console.error("Node.js: Failed to load file:", err);
  }
}

// loadFileNode('path/to/your/file.lottie');

await new DotLottie.fromURL(url) (Browser Only)

Fetches a .lottie file from a given URL in browser environments and loads it into a new DotLottie instance.

Internally, fromURL fetches the file, gets its ArrayBuffer, and uses the same logic as fromArrayBuffer (including V1 to V2 auto-conversion).

// Browser Example
async function loadFromRemoteURL(fileUrl) {
  try {
    // Load the data from URL into a new instance
    const dl = await new DotLottie.fromURL(fileUrl);
    console.log(`Successfully loaded .lottie from ${fileUrl}`);
    // Access dl.animations, etc.
  } catch (err) {
    console.error(`Failed to load from URL ${fileUrl}:`, err);
  }
}

// const dl = await loadFromRemoteURL('https://example.com/animation.lottie');

3. The build() Method: Finalizing Your .lottie

After creating a new DotLottie instance and adding content, or after loading and modifying an existing file, call await dotlottie.build() before exporting. See DotLottie.build().

// Assuming 'dotlottie' is an instance of DotLottie with content added or loaded

try {
  await dotlottie.build();
  console.log(".lottie file has been built and is ready for export!");
} catch (error) {
  console.error("Error during .lottie build process:", error);
}

Why is build() necessary?

The build() method performs several important finalization tasks:

1. Fetches Remote Data: If animations were added using the url option, build() fetches the Lottie JSON data.

2. Processes Assets: Handles the bundling of assets. See Managing Assets.

3. Generates/Finalizes Manifest: Creates or updates the manifest.json.

4. Runs Internal Plugins: Executes internal processing plugins.

Call await dotlottie.build() before attempting to export. See Exporting.

Once you have a DotLottie instance, manage its contents using the methods detailed in the following sections:

• Managing Animations

• Managing Assets

• Managing Themes

• Managing State Machines

Next up: Managing Animations