Theming with dotlottie-js

Theming in dotLottie V2 allows you to package multiple visual styles (e.g., color palettes, property overrides) within a single .lottie file. This enables dynamic alteration of an animation's appearance at runtime without needing separate animation files. dotlottie-js provides the tools to manage and bundle these themes into your .lottie files.

For basic theme management (adding, retrieving, removing), see: Core Concepts: Managing Themes.

For a comprehensive understanding of theming concepts, how to design themeable Lottie animations in tools like After Effects, and how various dotLottie players implement and utilize theme data, please visit the official documentation at dotlottie.io.

dotlottie-js: Packaging Your Themes

The primary role of dotlottie-js in the theming workflow is to:

1. Take your pre-defined theme data (as JSON objects).

2. Package these themes into the .lottie file structure, typically under a t/ directory (e.g., t/theme_id.json).

3. Update the manifest.json file within the .lottie archive to list available themes and their IDs.

The dotLottie player is then responsible for reading this manifest, loading the specified theme JSON, and applying the visual changes to the animation during playback. dotlottie-js itself does not interpret the content of your theme data; it only ensures it's correctly stored and referenced.

Structure of Theme Data

The JSON structure of your theme data is flexible and depends entirely on:

• How your Lottie animation is designed to be themeable.

• The requirements of the dotLottie player you intend to use.

dotlottie-js does not enforce a specific schema for the content of the theme data object you provide. You'll need to consult your animation design workflow and player documentation for the correct data structure.

A conceptual example of what theme data might look like:

{
  "colors": {
    "primary": "#FFFFFF",
    "accent": "#FF0000"
  },
  "imageSubstitutions": {
    "logoAssetId": "new_logo_path.png"
  }
}

Important: The actual structure is determined by your animation and player.

Packaging Themes with dotlottie-js

You use methods on the DotLottie instance to package themes:

1. addTheme(options): Adds a theme definition. The options object includes:

   • id (string, required): A unique identifier for the theme.

   • data (object, required): The theme JSON data.

   • name (string, optional): A human-readable name.

   • zipOptions (object, optional): Compression options for this theme's data. See addTheme() and Managing Themes for more details.

2. Set animation.initialTheme = 'themeId': Optionally set a default theme for an animation when adding it or by retrieving and modifying it. See Managing Animations.

3. await dotlottie.build(): Finalizes the .lottie package. This step writes the theme data to files like themes/<theme_id>.json and updates the manifest. See build().

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

async function packageThemesExample(animationData) {
  // animationData would be your Lottie JSON
  const dotlottie = new DotLottie();

  // Assume animationData is designed to use 'brandColor'
  await dotlottie.addAnimation({
    id: "my_animation",
    data: animationData, // Your actual Lottie animation JSON
    initialTheme: "dark_mode", // Optionally set a default theme
  });

  // Define theme data (structure depends on your animation & player)
  const themeDarkData = { values: { brandColor: "#FFFFFF", strokeWidth: 2 } };
  const themeLightData = { values: { brandColor: "#000000", strokeWidth: 1 } };

  // Add themes
  dotlottie.addTheme({
    id: "dark_mode",
    data: themeDarkData,
    name: "Dark Mode",
    // zipOptions: { level: 9 } // Example: Higher compression for this theme
  });
  dotlottie.addTheme({
    id: "light_mode",
    data: themeLightData,
    name: "Light Mode",
  });

  // Build the .lottie file to include themes in the manifest and package
  await dotlottie.build();

  console.log("Successfully created .lottie with packaged themes.");

  // Now you can export the .lottie file
  // const lottieBuffer = await dotlottie.toArrayBuffer();
  // await dotlottie.download("animation-with-themes.lottie");
}

// Example Lottie data (very minimal)
// const exampleAnimationData = { v: "5.9.6", fr: 30, ip: 0, op: 90, w: 512, h: 512, layers: [] };
// packageThemesExample(exampleAnimationData);

How Players Utilize Packaged Themes

When a dotLottie player loads your .lottie file:

1. It parses the manifest.json.

2. It identifies available themes from the manifest's themes array.

3. If an animation specifies an initialTheme, the player typically applies it automatically.

4. Players usually offer APIs to list available themes and switch between them using their id.

When a theme is applied, the player loads the corresponding theme JSON (e.g., themes/dark_mode.json) and uses its contents to modify the animation's appearance as designed.

Common Use Cases for Theming

• Dark/Light UI Modes: Easily adapt animations to interface brightness.

• Brand Customization: Allow users or systems to apply specific brand colors.

• Dynamic Status Indicators: Change animation colors or elements to reflect states like success, warning, or error.

By packaging themes with dotlottie-js, you create more versatile and adaptable Lottie animations.

Next up: State Machines In-Depth