Understanding the dotLottie Format: Overview

It's beneficial to understand the dotLottie format itself before diving into dotlottie-js.

What is dotLottie (.lottie)?

The dotLottie (.lottie) format is an open-source, zipped archive format specifically designed to package Lottie animations and their associated assets. Think of it as a specialized container that optimizes Lottie animations for distribution and use, much like a .zip file but with a defined internal structure and purpose.

Key Benefits of using the .lottie format:

• Aggregation: Bundle multiple Lottie animations into a single file.

• Asset Management: Include external assets (images, audio) directly within the archive. See Managing Assets.

• Compression: Zipped format leads to smaller files and faster downloads.

• Enhanced Features (V2): The V2 specification introduces advanced capabilities such as:

  • Theming: Define multiple visual styles within a single file.

  • State Machines: Implement interactivity to control animation playback.

• Standardization: Provides a consistent way to package and share Lottie animations.

You can find more information and the official specification for the dotLottie format at dotlottie.io.

Inside a .lottie File

A .lottie file is essentially a ZIP archive. Renaming a .lottie file to .zip allows extraction and exploration of its internal structure. The structure is conventional, especially for V2 files:

• manifest.json (Required): The heart of the file, describing the contents:

  • version: Format version (e.g., "2" for V2). See Format Versions.

  • generator: Tool/library used (e.g., "@dotlottie/dotlottie-js@x.y.z").

  • animations: Array listing Lottie animations. Each entry includes an id and can have name, initialTheme, etc. See Managing Animations.

    • Animation JSON typically at animations/<animation_id>.json.

  • themes (Optional, V2+): Array listing theme definitions. See Managing Themes.

    • Theme data typically at themes/<theme_id>.json.

  • stateMachines (Optional, V2+): Array listing state machine definitions. See Managing State Machines.

    • State machine data typically at states/<state_machine_id>.json.

  • activeAnimationId (Optional): ID of the default animation to play.

  • author, description, keywords, custom data fields.

• a/ directory (V2 Convention): Contains individual Lottie JSON animation files.

• i/ directory (Optional, V2 Convention): Contains image assets.

• u/ directory (Optional, V2 Convention): Contains audio assets.

• t/ directory (Optional, V2 Convention): Contains theme JSON files.

• s/ directory (Optional, V2 Convention): Contains state machine JSON files.

Note: The V1 format had a slightly different structure. dotlottie-js handles loading V1 files but primarily operates using the V2 structure. See Format Versions.

Understanding this structure helps in debugging and appreciating how dotlottie-js organizes the data.

Next up: Format Versions: V1 vs V2