The dotLottie Format

The dotLottie Format

dotLottie (.lottie) is an enhanced container format for Lottie animations that addresses several limitations of the original JSON format. It’s essentially a ZIP archive that can contain:

  • Multiple animations: Package several related animations in a single file
  • Images and assets: Embed all required images directly in the file
  • Manifest file: Metadata about the animations, including IDs, names, and themes
  • Optimized storage: Compressed format reduces file sizes even further

Benefits of dotLottie

  • Self-contained: All assets are bundled together, no external dependencies
  • Better organization: Multiple animations and themes in one package
  • Smaller file sizes: ZIP compression reduces overall file size
  • Version control friendly: Binary format is more efficient than large JSON files
  • Multi-animation support: Perfect for animation sets like icons or loading states

File Structure

A .lottie file is a ZIP archive with this typical structure:

animation.lottie
├─ manifest.json            # Required: Metadata file describing the package
├─ a/                       # Required: Directory containing Lottie JSON animations
│  ├─ animation_1.json      # Example animation file
│  └─ animation_2.json      # Another animation file
├─ i/                       # Optional: Directory for image assets
│  ├─ img_1.webp            # Example image asset
│  └─ img_2.png             # Another image asset
├─ s/                       # Optional: Directory for state machine files
│  ├─ state_machine_1.json  # Example state machine file
│  └─ state_machine_2.json  # Another state machine file
├─ t/                       # Optional: Directory for theme files
│  ├─ theme_1.json          # Example theme file
│  └─ theme_2.json          # Another theme file
└─ f/                       # Optional: Directory for font assets
   ├─ BrandFont-Bold.ttf    # Example font file
   └─ BrandFont-Regular.woff2 # Another font file

Check dotlottie.io/spec/2.0 for more details about the format.

Example Manifest

{
  "version": "1.0",
  "author": "Designer Name",
  "generator": "dotLottie",
  "animations": [
    {
      "id": "animation1",
      "speed": 1,
      "themeColor": "#ffffff",
      "loop": true
    }
  ]
}

Creating dotLottie Files

You can create dotLottie files using:

Using dotLottie with Lottie4J

Lottie4J supports loading dotLottie files directly. The library handles decompression and asset extraction automatically:

File file = new File("src/test/resources/dot/demo-3.lottie");

// Get the first animation in the .lottie package
Animation animation = LottieFileLoader.load(File);

// Load as a DotLottie object for more advanced features
DotLottie dot = LottieFileLoader.loadDotLottie(file);
System.out.println("Animations in package: " +
    (dot.animations() == null ? 0 : dot.animations().size()));

When to Use dotLottie

Use dotLottie when you need:

  • Animations with external image assets
  • Multiple related animations in one package
  • Smaller file sizes for web delivery
  • Better organization for complex animation projects
  • Theme support (light/dark mode variations)

For simple vector-only animations, standard Lottie JSON files are sufficient.