Create and manage color themes for animations.

Theming

Create animations that support multiple color variations without re-exporting. Use color slots (tokens) and the Theme Manager to build light/dark mode support, brand variations, and dynamic color schemes.

What is Theming?

Theming allows animations to support multiple color schemes.

Theming Overview

Theming System:

• •Color Slots - Named color variables (tokens) referenced by multiple properties
• •Theme Manager - Create and manage multiple color themes
• •Runtime Switching - Change themes without re-exporting animation
• •dotLottie Support - Export with multiple themes in one file

Benefits:

• •Single animation, multiple themes - One file supports light/dark mode
• •No re-export needed - Switch themes at runtime
• •Smaller file sizes - One animation instead of duplicates
• •Easier maintenance - Update theme colors in one place
• •Brand flexibility - Multiple brand color variations

Why Use Theming?

Use Cases:

• •Light and dark mode support
• •Brand color variations (primary, secondary themes)
• •Seasonal or event themes
• •A/B testing color schemes
• •User customization options
• •Platform-specific themes (iOS, Android, Web)

Traditional Approach (Without Theming):

❌ Problems:
- Export animation-light.json
- Export animation-dark.json
- Duplicate files (larger bandwidth)
- Update colors → Re-export both files
- Manage multiple versions

Modern Approach (With Theming):

✅ Benefits:
- Export animation.lottie with light + dark themes
- Single file (smaller bandwidth)
- Update theme colors → No re-export needed
- One version to manage
- Runtime theme switching

How Theming Works

Understanding the technical architecture behind the theming system.

Architecture Overview

The theming system uses an indirection layer between animation properties and actual color values.

System Flow:

Animation Properties → Slot References → Theme Rules → Color Values
       ↓                     ↓                ↓              ↓
   Layer fills         "primary-color"    Light theme:   #2196F3
   Layer strokes                          Dark theme:    #64B5F6
   Gradient stops

Key Concept - Indirection:

• •Instead of properties storing colors directly: fill.color = #2196F3
• •Properties reference slots: fill.referenceId = "primary-color"
• •Slots resolve to theme colors: theme.getColor("primary-color") → #2196F3
• •Change theme → Same slot resolves differently → Animation updates

Why Indirection Matters:

• •Single Source of Truth: One slot, many properties
• •Runtime Switching: Change theme without re-exporting
• •Smaller Files: No animation data duplication
• •Easier Maintenance: Update color once, changes everywhere

Data Flow: Creator to Player

Complete journey from creation to playback.

1. Creation (Lottie Creator):

Designer creates animation
  ↓
Creates color slots ("primary", "bg", "text")
  ↓
Links properties to slots (fills, strokes reference slot IDs)
  ↓
Creates themes (Light: #2196F3, Dark: #64B5F6)
  ↓
Assigns colors to slots in each theme

2. Export (Creator → dotLottie):

User exports as dotLottie
  ↓
Slot references preserved in animation JSON
  {"c": {"k": {"sid": "primary-color", "type": "Color"}}}
  ↓
Theme data extracted to separate files
  themes/light.json: {"id": "primary-color", "value": [0.129, 0.588, 0.953]}
  themes/dark.json: {"id": "primary-color", "value": [0.392, 0.710, 0.965]}
  ↓
Files packaged into .lottie ZIP
  animation.lottie = manifest + animation + themes
  ↓
Color values converted: RGB 0-255 → 0-1

3. Runtime (Player):

Player loads .lottie file
  ↓
Reads manifest.json → Discovers available themes
  ↓
User selects theme (or auto-detected)
  ↓
Player loads theme file (themes/dark.json)
  ↓
Animation renders → Encounters slot reference
  ↓
Player resolves: slot ID → active theme → color value
  "primary-color" → dark theme → [0.392, 0.710, 0.965]
  ↓
Property rendered with resolved color

4. Theme Switching:

User triggers theme switch
  ↓
Player loads new theme file
  ↓
Re-resolves all slot references
  ↓
Canvas re-renders with new colors
  ↓
Seamless transition (no reload)

Technical Components

Three layers work together to enable theming.

1. Slot Layer (Creator):

• •Color Slots: Named identifiers for colors
• •Slot Values: Current color based on active theme
• •Bidirectional References: Properties ↔ Slots
• •Scene Graph Integration: Slots are nodes in animation structure

2. Theme Layer (Creator + dotLottie):

• •Theme Definitions: Collections of slot-to-color mappings
• •DEFAULT_THEME: Fallback for compatibility
• •Theme State Machine: Manages theme operations
• •Export Conversion: Creator format (0-255) → dotLottie format (0-1)

3. Resolution Layer (Player):

• •Slot Resolution: Maps slot IDs to theme color values
• •Runtime Lookup: Property → Slot ID → Theme → Color
• •Theme Switching: Re-resolve slots on theme change
• •Fallback Mechanism: Use default if theme incomplete

Format Comparison

Understanding the difference between internal and export formats.

Creator Internal Format (.creator file):

{
  "colorSlots": [
    {
      "assetId": "primary-color",
      "slotType": 2,
      "type": "SLOT",
      "value": {
        "isAnimated": false,
        "staticValue": { "r": 33, "g": 150, "b": 243, "a": 1 }
      }
    }
  ],
  "themes": {
    "light": {
      "colors": {
        "primary-color": { "r": 33, "g": 150, "b": 243, "a": 1 }
      }
    },
    "dark": {
      "colors": {
        "primary-color": { "r": 100, "g": 181, "b": 246, "a": 1 }
      }
    }
  },
  "activeThemeId": "light"
}

dotLottie Export Format (.lottie file):

animation.lottie (ZIP)
├── manifest.json
│   {"animations": [{"themes": ["light", "dark"], "defaultTheme": "light"}]}
├── animations/main.json
│   {"layers": [{"c": {"k": {"sid": "primary-color", "type": "Color"}}}]}
├── themes/light.json
│   {"id": "light", "rules": [{"id": "primary-color", "type": "Color", "value": [0.129, 0.588, 0.953]}]}
└── themes/dark.json
    {"id": "dark", "rules": [{"id": "primary-color", "type": "Color", "value": [0.392, 0.710, 0.965]}]}

Key Differences:

• •Color Format: Creator uses 0-255, dotLottie uses 0-1
• •Structure: Creator is single JSON, dotLottie is ZIP with multiple files
• •Slot Storage: Creator stores in colorSlots array, dotLottie uses slot references in animation
• •Theme Format: Creator uses simple object, dotLottie uses rule-based format
• •Compression: dotLottie compressed (60-80% smaller)

Technical Capabilities

What the theming system can do.

Supported:

• •✅ Color Slots: RGB/RGBA color theming
• •✅ Multiple Themes: Unlimited theme variations
• •✅ Runtime Switching: Change themes without reload
• •✅ Animated Properties: Slots work with keyframes
• •✅ Property Types: Fills, strokes, gradients
• •✅ dotLottie Export: Compressed multi-theme format
• •✅ Fallback Support: DEFAULT_THEME for compatibility
• •✅ Undo/Redo: Full history for theme operations

Current Limitations:

• •❌ Other Slot Types: Gradients, Images, Scalars (coming soon)
• •❌ Animated Theme Values: Keyframes for slot colors (coming soon)
• •❌ Theme Inheritance: Themes extending other themes (coming soon)
• •❌ Conditional Theming: State-based theme switching (coming soon)
• •❌ JSON Export: Themes require dotLottie format
• •❌ Legacy Players: Require Lottie-web 5.10+ or equivalent

Performance Characteristics

How theming impacts animation performance.

Creation Time:

• •

  Create slot: < 1ms

• •

  Link property: < 1ms

• •

  Create theme: < 1ms

• •

  Update slot color: < 5ms

• •

  Switch active theme: 10-50ms (depends on slot count)

Export Time:

• •Small animation (10 slots, 2 themes): 50-100ms
• •Medium animation (30 slots, 3 themes): 100-200ms
• •Large animation (50+ slots, 4+ themes): 200-500ms

Runtime Performance:

• •Initial load: +2-5ms (load theme file)
• •Theme switch: 5-10ms (re-resolve slots)
• •Rendering: No overhead vs non-themed animations
• •Memory: +2-3 KB per theme (negligible)

Optimization:

• •Batched updates during theme switch
• •Cached theme rule lookups
• •Lazy validation
• •Minimal re-rendering

Architecture Deep Dive

For detailed technical documentation about the theming architecture, see:

Theming Components

Three main components of the theming system.

Color Slots (Tokens)

What are Color Slots?

• •Named color variables that can be referenced by multiple properties
• •Reusable color tokens linked across layers
• •Changing a slot updates all linked properties automatically
• •Work with animated properties

Example:

Color Slot: "Primary Blue" = #2196F3

Linked to:
- Button fill color
- Icon stroke color
- Background gradient stop
- Text color (3 layers)

Change "Primary Blue" to #FF5722
→ All 6 properties update automatically

Benefits:

• •Consistency: Same color across multiple layers
• •Easy updates: Change color once, updates everywhere
• •Theme support: Slots have different values per theme
• •Maintainability: Clearer color management

See Color Slots for complete guide.

Theme Manager

What is Theme Manager?

• •Interface for creating and managing multiple color themes
• •Define theme colors and properties
• •Apply themes to animations
• •Manage light/dark mode variations

Theme Manager Features:

• •Create new themes (light, dark, brand variants)
• •Edit theme colors
• •Apply themes to animation
• •Preview theme changes
• •Export with multiple themes

Example Themes:

Theme: Light
- Primary: #2196F3
- Background: #FFFFFF
- Text: #000000

Theme: Dark
- Primary: #64B5F6
- Background: #121212
- Text: #FFFFFF

See Theme Manager for complete guide.

Runtime Theme Switching

Dynamic Themes:

• •Change themes in player without re-exporting animation
• •Switch between embedded themes at runtime
• •No code changes when theme changes
• •Instant theme updates

How It Works:

1. Export animation with multiple themes (dotLottie)

2. Load animation in player (web, mobile)

3. Player selects theme (light, dark, or custom)

4. Animation renders with selected theme colors

5. Switch theme anytime without reload

Player Support:

• •Lottie-web 5.10+ with dotLottie plugin
• •dotLottie-web, dotLottie-player
• •LottieFiles platform
• •Modern Lottie players

Color Slots System

Reusable color tokens for consistent theming.

How Color Slots Work

Creating Color Slots:

1. Define named color slot ("Primary", "Background", "Accent")

2. Assign color value to slot (#2196F3, #FFFFFF, etc.)

3. Link layer properties to slot

4. Properties reference slot instead of direct color

Linking Properties:

• •Select layer with color property (fill, stroke, gradient)
• •In property panel, link to color slot
• •Property now uses slot value
• •Changes to slot update property automatically

Theme Variations:

• •Each theme defines values for all slots
• •Light theme: "Primary" = #2196F3
• •Dark theme: "Primary" = #64B5F6
• •Switch theme → All slots update → Animation updates

Color Slot Benefits

Consistency:

• •Same color across multiple layers guaranteed
• •No manual synchronization needed
• •One source of truth for each color

Maintainability:

• •Update color once in slot
• •All linked properties update automatically
• •Easier than finding and changing individual properties

Theme Support:

• •Slots enable multi-theme animations
• •Each theme has different slot values
• •Runtime theme switching possible

Animated Properties:

• •Color slots work with keyframe animation
• •Animate slot value over time
• •All linked properties animate together
• •Coordinated color changes

Document Colors

Automatic color palette tracking.

What are Document Colors?

Auto-Generated Palette:

• •Lottie Creator automatically tracks all colors used in animation
• •Recently used colors saved for quick access
• •Appear as clickable swatches in color picker
• •Quick color consistency across project

Document Colors Features:

• •Automatically updated as you work
• •Shows all colors in current animation
• •Click swatch to apply color
• •No manual palette management needed

Location:

• •Color Picker → Document Colors section
• •Shows swatches of all used colors
• •Recently used colors at top
• •Quick access for consistency

Using Document Colors

Quick Color Application:

1. Select layer with color property

2. Open color picker

3. Click document color swatch

4. Color applied instantly

5. Maintains consistency

Color Consistency:

• •Reuse exact colors from animation
• •Avoid color drift (slightly different values)
• •Professional, cohesive appearance
• •No need to remember hex codes

Workflow Integration:

• •Automatically populated
• •No setup required
• •Works with color slots
• •Complements theme system

Light/Dark Mode Support

Create animations that adapt to user preferences.

Multi-Theme Animations

Light and Dark Themes:

• •Create light theme with bright colors
• •Create dark theme with dark colors
• •Export both themes in single dotLottie file
• •Player selects appropriate theme

Theme Switching:

• •User changes system theme (light/dark)
• •App detects theme change
• •Player switches animation theme
• •Seamless transition

Example:

Light Theme:
- Background: #FFFFFF (white)
- Primary: #2196F3 (blue)
- Text: #000000 (black)

Dark Theme:
- Background: #121212 (dark)
- Primary: #64B5F6 (lighter blue)
- Text: #FFFFFF (white)

Both themes in animation.lottie file

Platform Integration

Integrate themes seamlessly across web and mobile platforms:

Use Cases

Application UI:

• •Loading animations adapt to app theme
• •Icons change colors with system theme
• •Consistent with platform appearance
• •Better user experience

Web Applications:

• •Respect user's theme preference
• •Seamless dark mode support
• •No duplicate animation files
• •Smaller bandwidth usage

dotLottie Themes

Export animations with embedded themes.

dotLottie Format

Theme Support:

• •ZIP-based container format (.lottie)
• •Contains animation + multiple themes
• •60-80% smaller than JSON
• •Modern Lottie players only

File Structure:

animation.lottie (ZIP archive)
├── manifest.json        // Metadata, describes themes
├── animations/
│   └── animation.json   // Compressed animation data
├── themes/
│   ├── light.json       // Light theme definitions
│   └── dark.json        // Dark theme definitions
└── states/
    └── machine.json     // State machine (if used)

Manifest Example:

{
  "version": "1.0",
  "animations": [
    {
      "id": "main",
      "themes": ["light", "dark"]
    }
  ]
}

Multiple Themes in One File

Package Themes:

• •Include all theme variations in single .lottie file
• •Light, dark, brand variants together
• •Easier asset management
• •One file to distribute

Benefits:

• •Smaller file size vs multiple JSON files
• •Single download includes all themes
• •Runtime theme selection
• •No duplicate animation data

Compatibility:

• •Lottie-web 5.10+ with dotLottie plugin
• •dotLottie-web, dotLottie-player
• •LottieFiles platform
• •Not supported in older players

See Exporting Themes for complete guide.

Creating Themes

Workflow for theme creation.

Basic Theme Workflow

Primary      → #2196F3 (vibrant blue)
Background   → #FFFFFF (white)
Text         → #000000 (black)
Accent       → #FF5722 (orange)

Primary      → Vibrant colors (#2196F3)
Background   → White or light gray (#FFFFFF)
Text         → Dark colors for contrast (#000000)
Accent       → Complementary vibrant colors

Primary      → Lighter variants (#64B5F6)
Background   → Dark gray or black (#121212)
Text         → Light colors for contrast (#FFFFFF)
Accent       → Lighter, desaturated variants

animation.lottie (exported file)
├── manifest.json (contains theme references)
├── animations/main.json (animation data)
└── themes/
    ├── light.json (light theme definitions)
    └── dark.json (dark theme definitions)

Theme Color Selection

Choosing Theme Colors:

• •

  Light Theme: High contrast, bright backgrounds

  • •Background: White or light gray
  • •Text: Dark gray or black
  • •Primary: Vibrant colors
• •

  Dark Theme: Lower contrast, dark backgrounds

  • •Background: Dark gray or black (#121212 recommended)
  • •Text: Light gray or white
  • •Primary: Lighter, desaturated variants

Color Contrast:

• •Ensure readability in both themes
• •WCAG contrast ratios (4.5:1 for text)
• •Test both themes for accessibility
• •Adjust colors for visibility

Advanced Theming

Brand Variations:

• •Create multiple brand themes
• •Primary brand colors
• •Secondary brand colors
• •Partner or white-label themes

Seasonal Themes:

• •Holiday color schemes
• •Seasonal variations
• •Event-specific themes
• •Limited-time themes

User Customization:

• •Allow users to select themes
• •Custom color schemes
• •Personalization options
• •Saved preferences

Theming Workflows

Common theming patterns.

Web Application Workflow

Light Theme:
- Background: #FFFFFF
- Text: #000000
- Primary: #2196F3

Dark Theme:
- Background: #121212
- Text: #FFFFFF
- Primary: #64B5F6

<div id="lottie-container"></div>
<script src="lottie-web.js"></script>

const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const initialTheme = isDark ? "dark" : "light";

const animation = lottie.loadAnimation({
  container: document.getElementById("lottie-container"),
  path: "/animations/animation.lottie",
  theme: initialTheme,
  loop: true,
  autoplay: true,
});

window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
  const newTheme = e.matches ? "dark" : "light";
  animation.setTheme(newTheme);
});

themeToggleButton.addEventListener("click", () => {
  currentTheme = currentTheme === "dark" ? "light" : "dark";
  animation.setTheme(currentTheme);
  localStorage.setItem("theme", currentTheme);
});

Code Integration:

Mobile App Workflow

Platform Theme Integration:

1. Create themed animation

2. Export with light/dark themes

3. Add to app bundle

4. Detect platform theme (iOS/Android)

5. Load animation with detected theme

6. Update when user changes system theme

7. Seamless integration

Brand Variation Workflow

Multi-Brand Support:

1. Design base animation

2. Define color slots for brand colors

3. Create theme per brand

4. Export with all brand themes

5. Select theme based on context

6. Same animation, different branding

Best Practices

Tips for effective theming.

Plan Color Slots Early

Upfront Planning:

• •Identify which colors should be themeable
• •Create color slots at project start
• •Link properties as you create layers
• •Easier than retrofitting later

Common Slots:

• •Primary (main brand color)
• •Secondary (accent color)
• •Background (background color)
• •Surface (card/panel background)
• •Text (primary text color)
• •Text Secondary (secondary text)
• •Border (dividers, outlines)
• •Error, Warning, Success (status colors)

Test Both Themes

Quality Assurance:

• •Preview animation in both themes
• •Verify contrast and readability
• •Check all color slots used correctly
• •Test on actual devices/browsers
• •Ensure smooth theme switching

Meaningful Slot Names

Clear Naming:

• •Use descriptive names ("Primary Button", not "Color 1")
• •Indicate purpose ("Background Dark", "Text Light")
• •Consistent naming convention
• •Easier to manage and understand

Limit Slot Count

Keep It Simple:

• •Don't create too many slots (hard to manage)
• •Group similar colors
• •Typical range: 5-12 slots
• •More slots = more complexity

Document Theme Usage

Documentation:

• •Document color slots and purpose
• •Specify theme requirements
• •Guide for developers/designers
• •Easier handoff and maintenance

Keyboard Shortcuts

Color Management:

• •No specific theming shortcuts
• •Use standard color picker shortcuts
• •Property panel shortcuts apply

General:

• •Cmd/Ctrl + Z - Undo theme changes
• •Cmd/Ctrl + Y - Redo

See Complete Keyboard Shortcuts for all shortcuts.

Common Issues

Tips for Theming Success

Start Simple

Begin with Basics:

• •Create light/dark themes first
• •Add complexity gradually
• •Test frequently
• •Iterate based on feedback

Use Consistent Colors

Color Consistency:

• •Reuse color slots across animation
• •Don't create duplicate slots
• •Maintain color palette
• •Professional appearance

Plan for Maintenance

Long-Term Thinking:

• •Descriptive slot names
• •Document theme purpose
• •Organize slots logically
• •Easier updates later

Test on Target Platform

Platform Testing:

• •Test themes in actual player
• •Verify theme switching works
• •Check performance
• •Ensure compatibility

Next Steps

Dive deeper into specific theming topics: