Format Structure

The dotLottie format (.lottie) is a unified container format designed to package and distribute Lottie animations efficiently. It's essentially a zip file with a standardized structure that can contain multiple animations, themes, and interactive states.

For detailed technical specifications of the format, visit dotlottie.io↗.

Basic Structure

A .lottie file typically contains:

my-animation.lottie
├── manifest.json        # Configuration and metadata
├── a/                   # Directory containing animations
│   ├── animation1.json  # Lottie JSON animation file
│   └── animation2.json  # Additional animations
├── i/                   # Optional image assets
│   └── logo.webp
├── t/                   # Optional themes directory
│   ├── light.json       # Theme configuration
│   └── dark.json        # Additional themes
└── s/                   # Optional state machines
    └── button.json      # State machine configuration

Manifest File

The manifest.json file is the heart of a dotLottie file, containing metadata and configuration for the animations. This guide explains the structure and properties of the manifest.

Basic Structure

{
  "version": "2",
  "generator": "dotlottie-js v2.0.0",
  "initial": {
    "animation": "main-animation"
  },
  "animations": [
    {
      "id": "main-animation",
      "initialTheme": "light",
      "background": "#FFFFFF",
      "themes": ["light", "dark"]
    }
  ],
  "themes": [
    {
      "id": "light",
      "name": "Light Theme"
    },
    {
      "id": "dark",
      "name": "Dark Theme"
    }
  ],
  "stateMachines": [
    {
      "id": "button-states",
      "name": "Button States"
    }
  ]
}

Top-Level Properties

Animation Properties

Each animation in the animations array describes an entry in the a/ directory:

Theme Properties

Each theme in the themes array describes an entry in the t/ directory:

Accessing the Manifest

You can access the manifest through the manifest property of the DotLottie instance:

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
});

dotLottie.addEventListener("load", () => {
  // Access manifest properties
  console.log(dotLottie.manifest.animations);
  console.log(dotLottie.manifest.initial);
});

Best Practices

1. Animation IDs

   • Use descriptive, unique IDs

   • Follow a consistent naming convention

   • Only alphanumeric characters, dots, underscores, spaces, and hyphens

2. Themes

   • Use semantic theme names (e.g., light, dark, brand)

   • Scope themes to specific animations using the themes array on the animation object

   • Set initialTheme to specify which theme loads by default

3. Initial Loading

   • Use initial.animation to specify which animation loads first in a multi-animation file

   • Use initial.stateMachine when the file has an interactive state machine that should start immediately

Creating dotLottie Files

To create .lottie files, you can use:

• dotlottie-js↗ library

• Lottie Creator↗ tool

• LottieFiles Platform↗

For detailed format specifications and tooling information, visit dotlottie.io↗.