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().

1. Adding Themes: dotlottie.addTheme()

The dotlottie.addTheme() method adds a theme definition to the DotLottie instance. It accepts a single argument, an object conforming to the ThemeOptions interface.

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() 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.

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.

// 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().

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.

// 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().

// 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

Last updated: August 6, 2026 at 11:58 AMEdit this page
Previous

Manage Assets

Next

Manage State Machines