# Managing Animations
How to add, remove, and read Lottie animations in a .lottie package with dotlottie-io.

# Managing Animations

Each animation in a `.lottie` package corresponds to one Lottie JSON document, identified by a unique string ID.

## Adding an animation

```javascript
dotlottie.addAnimation("hero", JSON.stringify(heroLottieJson));
```

`jsonData` can be a `Buffer` or a JSON string. Both `DotLottie` and `DotLottieBuilder` expose this method with the same signature.

### `AnimationOptions`

An optional third argument configures the animation's manifest entry:

```typescript
interface AnimationOptions {
  name?: string; // display name in the manifest
  initialTheme?: string; // ID of the theme applied by default
  background?: string; // background colour hint
  themes?: string[]; // IDs of themes associated with this animation
}
```

```javascript
dotlottie.addAnimation("hero", heroBuffer, {
  name: "Hero Animation",
  initialTheme: "dark",
  themes: ["dark", "light"],
});
```

{/* to verify: playback config lives in the player */}

Note what's **not** here: there are no playback-related fields (`autoplay`, `loop`, `speed`, `direction`, etc.). Playback configuration lives in the player, not the file — this matches dotLottie's V2 manifest schema.

## Automatic asset extraction

If the Lottie JSON passed to `addAnimation` contains embedded base64 assets (images, fonts, audio) in its `assets` array, they're automatically extracted into the package's asset directories and the JSON's references are rewritten to point at the stored files. You don't need to call `addImage`/`addFont`/`addAudio` separately for assets that are already embedded in the animation — see [Managing Assets](/docs/tools/dotlottie-io/core-concepts/assets).

## Removing an animation

```javascript
dotlottie.removeAnimation("hero");
```

Throws if the ID doesn't exist.

## Reading animations

```javascript
const json = dotlottie.getAnimationJson("hero"); // string, or null if not found
const ids = dotlottie.animationIds(); // string[]
```

`getAnimationJson` returns the raw Lottie JSON as a string — parse it with `JSON.parse()` when you need to inspect or modify individual fields.

Next up: [Managing Assets](/docs/tools/dotlottie-io/core-concepts/assets)