Theming
Learn how to add, retrieve, and manage themes in dotLottie files using dotlottie-js for multiple visual variations.
Core Concepts: Managing 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.
See also: Advanced Theming
What are Themes in dotLottie?
A Theme in dotLottie typically consists of a JSON object mapping themeable properties to new values. When a player applies a theme, it dynamically updates the animation's appearance.
This allows for:
Dark/Light Modes: Easily switch animation colors.
Branding Variations: Apply different brand colors.
State-Based Styles: Change appearance based on application state.
dotlottie-js allows you to bundle these theme JSON objects into the .lottie file.
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();
// Example Theme Data (structure depends on your animation and player)
const themeDarkData = {
colors: {
primary: "#FFFFFF",
secondary: "#AAAAAA",
},
};
const themeLightData = {
colors: {
primary: "#000000",
secondary: "#333333",
},
};
// 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
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(); See the DotLottie Instance page for details.
}
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): The JSON object containing the actual theme data. The structure of this object depends on how your Lottie player and animations are set up to consume theme information.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.lottiefile is built. For detailed information on available options, see the fflate ZipOptions documentation.
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 [Managing Animations](/docs/tools/dotlottie-js/core-concepts/managing-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: Managing State Machines