Quick Start: Creating and Exporting a `.lottie` File

This guide provides a basic example of creating a new .lottie file using dotlottie-js, adding an animation, and exporting or downloading it.

It focuses on the V2 DotLottie class, the primary interface for the library.

Prerequisites

Ensure you have installed dotlottie-js as described in the Installation guide.

You'll also need a Lottie animation JSON file.

Example: Creating and Downloading (Browser)

This example demonstrates creating a .lottie file and triggering a download in a browser environment.

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

async function createAndDownloadDotLottie() {
  try {
    // 1. Create a new DotLottie instance
    // See: Core Concepts: The DotLottie Instance / API DotLottie
    const dotlottie = new DotLottie();

    // 2. Add an animation
    // See: Core Concepts: Managing Animations / API DotLottie
    // Replace with your actual Lottie JSON data or URL
    // Option A: From a URL (library will fetch it during build)
    dotlottie.addAnimation({
      id: "animation_1",
      url: "https://assets.lottiefiles.com/packages/lf20_jW54t3.json", // Example LottieFiles animation
      name: "My First Animation",
    });

    // Option B: From a Lottie JSON object (if you already have it loaded)
    /*
    const lottieJsonData = {
      v: '5.9.6',
      fr: 60,
      ip: 0,
      op: 180,
      w: 512,
      h: 512,
      nm: 'My Animation',
      ddd: 0,
      assets: [],
      layers: [] // ... your animation layers ...
    };
    dotlottie.addAnimation({
      id: 'animation_2',
      data: lottieJsonData,
      name: 'My Second Animation From Data'
    });
    */

    // 3. Build the dotLottie archive
    // See: Core Concepts: The DotLottie Instance / API DotLottie
    // This step fetches animations if URLs were provided, processes assets, and creates the manifest.
    await dotlottie.build();

    // 4. Download the .lottie file
    // See: Core Concepts: Exporting / API DotLottie
    await dotlottie.download("my-animation.lottie");

    console.log("Successfully created and initiated download for my-animation.lottie");
  } catch (error) {
    console.error("Error creating or downloading .lottie file:", error);
  }
}

// Call the function (e.g., on a button click)
// createAndDownloadDotLottie();

Explanation:

new DotLottie(): Instantiates the main DotLottie class.
addAnimation(options): Adds an animation. Requires a unique id. Provide animation data via data (Lottie JSON object) or url. See Managing Animations.
build(): Finalizes the .lottie package (fetches URLs, processes assets, generates manifest). See The DotLottie Instance.
download(fileName): Triggers a browser download. See Exporting.

Example: Creating and Exporting as ArrayBuffer (Node.js / Browser)

For Node.js or when raw data is needed in the browser (e.g., sending to a server).

import { DotLottie } from "@dotlottie/dotlottie-js"; // in browser or Node.js

// Node.js specific: to save to a file, use the 'fs' module
// const fs = require('fs/promises'); // Or import fs from 'fs/promises';

async function createAndExportDotLottie() {
  try {
    const dotlottie = new DotLottie();

    // Add your animation (using URL or data as shown above)
    dotlottie.addAnimation({
      id: "animation_node",
      url: "https://assets.lottiefiles.com/packages/lf20_VeqS4d.json", // Another example animation
      name: "Node JS Animation",
    });

    await dotlottie.build();

    // Export to ArrayBuffer
    // See: Core Concepts: Exporting / API DotLottie
    const arrayBuffer = await dotlottie.toArrayBuffer();

    console.log(`Successfully created .lottie as ArrayBuffer. Size: ${arrayBuffer.byteLength} bytes`);

    // In Node.js, you could now save this buffer to a file:
    /*
    try {
      await fs.writeFile('my-node-animation.lottie', Buffer.from(arrayBuffer));
      console.log('File saved as my-node-animation.lottie');
    } catch (saveError) {
      console.error('Error saving file:', saveError);
    }
    */

    // In the browser, you could send this arrayBuffer to a server, etc.
    return arrayBuffer;
  } catch (error) {
    console.error("Error creating or exporting .lottie file:", error);
  }
}

// Example usage:
// createAndExportDotLottie().then(buffer => {
//   if (buffer) {
//     // Do something with the buffer
//   }
// });

Key differences for Node.js/ArrayBuffer export:

toArrayBuffer(): Use this method instead of download() to get the raw ArrayBuffer. See Exporting.
Saving (Node.js): The example includes commented-out code showing how to use the fs module to save the ArrayBuffer to a file (requires converting to a Node.js Buffer).

These examples cover the fundamental workflow. You can add multiple animations, themes, and state machines before the build() step.

Next up: Quick Start: Loading and Reading a dotLottie file

Quick Start Creating dotLottie Files

Quick Start: Creating and Exporting a .lottie File

Prerequisites

Example: Creating and Downloading (Browser)

Example: Creating and Exporting as ArrayBuffer (Node.js / Browser)

Quick Start: Creating and Exporting a `.lottie` File