Core Concepts: Managing Animations

Animations are the cornerstone of a .lottie file. The DotLottie class provides methods to add, retrieve, update, and remove Lottie animations within the dotLottie archive.

1. Adding Animations: `dotlottie.addAnimation()`

The dotlottie.addAnimation() method adds a new Lottie animation to the DotLottie instance. It returns the DotLottie instance for method chaining.

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

const dotlottie = new DotLottie();

function addMyAnimation() {
  try {
    dotlottie.addAnimation({
      id: "animation_1", // Required: Unique identifier for this animation
      // Option 1: Provide Lottie JSON data directly
      data: {
        /* ... your Lottie JSON object ... */ v: "5.9.6",
        fr: 60,
        ip: 0,
        op: 180,
        w: 512,
        h: 512,
        nm: "My Animation",
        ddd: 0,
        assets: [],
        layers: [],
      },
      // Option 2: Provide a URL to the Lottie JSON file (will be fetched during build())
      // url: 'https://assets.lottiefiles.com/packages/lf20_jW54t3.json',

      // Optional properties for this animation:
      name: "My Cool Animation", // User-friendly name
      initialTheme: "theme_dark_id", // Optional: ID of the initial theme for this animation
      background: "#000000", // Optional: Background color string
      themes: ["theme_dark_id", "theme_light_id"], // Optional: Array of theme IDs applicable
      defaultActiveAnimation: true, // Optional: Should this be the default animation to play?
      // zipOptions: { level: 6 }     // Optional: Compression options for fflate
    });
    console.log(`Animation "animation_1" added`);

    // Remember to call build() before exporting
    // await dotlottie.build();
  } catch (error) {
    console.error("Error adding animation:", error);
  }
}

// addMyAnimation();

`addAnimation()` Options:

id (string, required): A unique identifier for this animation within the dotLottie archive. This ID is used to reference the animation in the manifest, for setting an initial animation, or by state machines.
data (object, optional): The actual Lottie JSON animation data as a JavaScript object. Use this if you have the JSON readily available. You must provide either data or url.
url (string, optional): A URL pointing to the Lottie JSON file. If provided, dotlottie-js will fetch this URL during the await dotlottie.build() step. You must provide either data or url.
name (string, optional): A human-readable name for the animation.
initialTheme (string, optional): The ID of a theme to be initially applied to this animation by a player. This theme should be defined in the dotLottie manifest.
background (string, optional): A background color for the animation, typically a hex color string (e.g., "#FFFFFF").
themes (array of strings, optional): An array of theme IDs that are specifically associated with or applicable to this animation. These themes should be defined elsewhere in the dotLottie manifest.
defaultActiveAnimation (boolean, optional, default: false): If true, this animation is suggested to be the default active animation when the .lottie file is loaded by a player.
zipOptions (object, optional): Options passed to the fflate library for compressing the animation data. This can include settings like compression level. Refer to the fflate ZipOptions documentation for more details.

You can add multiple animations to a single DotLottie instance. Each must have a unique id.

2. Retrieving Animations

Once animations are added (or loaded), access them using these properties and methods.

Accessing all animations: `dotlottie.animations`

This property returns an array of objects representing all animations currently held.

// Assuming 'dotlottie' instance has animations loaded or added
const allAnimations = dotlottie.animations;
allAnimations.forEach((anim) => {
  // Access manifest properties directly
  console.log(`ID: ${anim.id}, Name: ${anim.name}, Loop: ${anim.loop}`);
});

Getting a specific animation: `dotlottie.getAnimation(animationId)`

This asynchronous method retrieves a specific animation object by its id, returning the object or undefined.

async function getAnimation() {
  const specificAnimation = await dotlottie.getAnimation("animation_1");
  if (specificAnimation) {
    console.log(`Found animation: ${specificAnimation.id}`);
    // Access its properties like id, name, loop, speed, etc.
    console.log(`Loop setting: ${specificAnimation.loop}`);

    // To get the raw Lottie JSON data associated with it:
    const lottieJson = await specificAnimation.toJSON();
    console.log("Animation data:", lottieJson);
  } else {
    console.log("Animation not found.");
  }
}

Each animation object has properties corresponding to the options set during addAnimation (e.g., id, loop) and an async toJSON() method to retrieve the Lottie JSON object.

3. Updating Animation Properties

Update the manifest properties of an animation after it has been added or loaded by modifying the properties on the object returned by getAnimation.

async function updateAnimation() {
  const animationToUpdate = await dotlottie.getAnimation("animation_1");
  if (animationToUpdate) {
    // Update manifest properties directly on the retrieved object
    animationToUpdate.loop = true;
    animationToUpdate.speed = 0.5;
    console.log(`Updated animation properties for: ${animationToUpdate.id}`);

    // Note: To modify the underlying Lottie JSON data itself (e.g., change frame rate)
    // you would typically:
    // 1. Get the current data: const currentData = await animationToUpdate.toJSON();
    // 2. Modify the 'currentData' object.
    // 3. Remove the old animation: dotlottie.removeAnimation("animation_1");
    // 4. Add the animation again with the modified data:
    //    dotlottie.addAnimation({ id: "animation_1", data: currentData, /* other props */ });
    // Alternatively, create a new DotLottie instance with the updated data.
  }
}

Changes to these properties will be reflected in the manifest.json when dotlottie.build() is called.

4. Removing Animations: `dotlottie.removeAnimation(animationId)`

Remove an animation using the removeAnimation method with the animation's id.

dotlottie.removeAnimation("animation_1");
console.log('Animation "animation_1" was removed.');

This method returns the DotLottie instance for method chaining.

Managing animations is key to building rich .lottie files. Remember that after changes (add, update, remove), call await dotlottie.build() before exporting.

Next up: Managing Assets (Images & Audio)

Animations

Core Concepts: Managing Animations

1. Adding Animations: dotlottie.addAnimation()

addAnimation() Options: