# Manage Animations
Learn to add, retrieve, update, and remove Lottie animations within your dotLottie files using dotlottie-js.

# Manage 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.

```javascript
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](https://github.com/101arrowz/fflate/blob/master/docs/interfaces/ZipOptions.md) 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.

```javascript
// 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`.

```javascript
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`.

```javascript
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`.

```javascript
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)](/docs/tools/dotlottie-js/how-to-guides/manage-assets)