# Manage Themes
Learn how to add, retrieve, and manage themes in dotLottie files using dotlottie-js for multiple visual variations.

# Manage Themes

Theming is a V2 feature of the dotLottie format allowing multiple visual variations (e.g., color palettes, property overrides) within a single `.lottie` file. `dotlottie-js` provides an API to manage these themes.

For the full `addTheme()` signature and rule-type reference, see [`DotLottie.addTheme()`](/docs/tools/dotlottie-js/reference/dotlottie-class#addTheme).

## 1. Adding Themes: `dotlottie.addTheme()`

The [`dotlottie.addTheme()`](/docs/tools/dotlottie-js/reference/dotlottie-class#addTheme) method adds a theme definition to the DotLottie instance. It accepts a single argument, an object conforming to the `ThemeOptions` interface.

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

async function main() {
  const dotlottie = new DotLottie();

  // Theme data must conform to { rules: [...] } — each rule's `id`
  // matches a themeable property tagged in the Lottie animation.
  const themeDarkData = {
    rules: [
      { id: "ball_color", type: "Color", value: [0, 1, 0, 1] },
      { id: "bg_color", type: "Color", value: [0, 0, 0, 1] },
    ],
  };

  const themeLightData = {
    rules: [
      { id: "ball_color", type: "Color", value: [0, 0, 0, 1] },
      { id: "bg_color", type: "Color", value: [1, 1, 1, 1] },
    ],
  };

  // Add a theme using the ThemeOptions structure
  dotlottie.addTheme({
    id: "theme_dark", // Required: Unique ID for the theme
    data: themeDarkData, // Required: The theme JSON data ({ rules: [...] })
    name: "Dark Mode", // Optional: Human-readable name
    // zipOptions: { ... } // Optional: Compression options for this theme's data
  });

  dotlottie.addTheme({
    id: "theme_light",
    data: themeLightData,
    name: "Light Mode",
  });

  console.log("Themes added.");

  // Remember to build after adding content
  await dotlottie.build();
}
main();
```

**Key `addTheme` Options (from `ThemeOptions`):**

- `id` (string, required): A unique identifier for the theme. This ID is used to reference the theme in animations and when retrieving it.
- `data` (object, required): A `{ rules: [...] }` object. `dotlottie-js` validates this shape and throws if it doesn't conform — see [`addTheme()`](/docs/tools/dotlottie-js/reference/dotlottie-class#addTheme) for the rule structure.
- `name` (string, optional): A human-readable name for the theme, which can be useful for display purposes in authoring tools or debug menus.
- `zipOptions` (object, optional): Options for compressing the theme data when the `.lottie` file is built. For detailed information on available options, see the [fflate ZipOptions documentation](https://github.com/101arrowz/fflate/blob/master/docs/interfaces/ZipOptions.md).

During `build()`, theme data is written to files like `t/<theme_id>.json` inside the archive and the manifest is updated to list available themes.

## 2. Retrieving Themes

Access added or loaded themes.

### Accessing all themes: `dotlottie.themes`

This property returns an array of `LottieTheme` objects. See [`dotlottie.themes`](/docs/tools/dotlottie-js/reference/dotlottie-class#themes).

```javascript
// Assuming 'dotlottie' instance has themes
const allThemes = dotlottie.themes;
console.log(`Found ${allThemes.length} themes.`);

allThemes.forEach((theme) => {
  console.log(`Theme ID: ${theme.id}, Name: ${theme.name}`);
  // Theme data is directly accessible
  console.log(" Theme Data:", theme.data);
});
```

### Getting a specific theme: `dotlottie.getTheme(themeId)`

Retrieves a specific `LottieTheme` object by its `id`. See [`dotlottie.getTheme()`](/docs/tools/dotlottie-js/reference/dotlottie-class#getTheme).

```javascript
const darkTheme = dotlottie.getTheme("theme_dark");
if (darkTheme) {
  console.log(`Retrieved theme: ${darkTheme.name}`);
  console.log(" Dark Theme Data:", darkTheme.data);
}
```

## 3. Assigning a Default Theme to an Animation

Set the `initialTheme` property on an animation object to specify a default theme.

```javascript
// Assuming 'dotlottie' has animation 'anim_1' and theme 'theme_dark'

async function assignInitialTheme() {
  const animation = await dotlottie.getAnimation("anim_1");

  if (animation) {
    // Assign the theme ID
    animation.initialTheme = "theme_dark"; // See [Manage Animations](/docs/tools/dotlottie-js/how-to-guides/manage-animations)

    console.log(`Initial theme for '${animation.id}' set to: ${animation.initialTheme}`);

    // The change will be reflected in the manifest.json upon the next build().
  }
}

assignInitialTheme();
```

## 4. Removing a Theme: `dotlottie.removeTheme(themeId)`

Remove a theme from the `DotLottie` instance by its `id`. Returns the `DotLottie` instance for method chaining. See [`dotlottie.removeTheme()`](/docs/tools/dotlottie-js/reference/dotlottie-class#removeTheme).

```javascript
// Get current theme count before removing
const initialThemeCount = dotlottie.themes.length;

dotlottie.removeTheme("theme_light");

// Check if the theme count decreased
if (dotlottie.themes.length < initialThemeCount) {
  console.log("Theme 'theme_light' removed.");
} else {
  console.log("Theme 'theme_light' was not found or not removed.");
}

// Remember to build the archive
// await dotlottie.build();
```

Managing themes allows you to create versatile `.lottie` files that can adapt their appearance dynamically.

Next up: [Manage State Machines](/docs/tools/dotlottie-js/how-to-guides/manage-state-machines)