Understanding dotLottie (.lottie): Format Internals and When to Use It

A .lottie file is, literally, a ZIP archive with a specific internal structure — you can rename one to .zip and open it with any archive tool to see exactly what's inside.

What's inside the archive

animation.lottie  (a zip archive)
├── manifest.json        // metadata: animation ids, active animation, version
├── animations/
│   ├── animation1.json   // a standard Lottie JSON, one per bundled animation
│   └── animation2.json
└── images/
    ├── image_0.png       // raster assets referenced by the animations
    └── image_1.webp

The manifest.json lists every animation bundled in the file along with which one should play by default, plus optional metadata like custom "themes" for some players. This part of the spec is still evolving, so exactly what a given player supports beyond the core animation data is worth checking against that player's documentation rather than assuming.

Why it's often smaller than the equivalent JSON

Raw Lottie JSON has no way to reference an external file, so any embedded raster image (a photo, a texture, a complex gradient baked to a bitmap) has to be base64-encoded and inlined directly into the JSON string. Base64 encoding itself inflates binary data by roughly a third, and JSON string escaping adds a little more on top. In a .lottie file, that same image sits in the images/ folder as its original binary, compressed with normal ZIP/DEFLATE compression instead — no base64 tax at all. For animations with no embedded images, the size difference between .lottie and plain JSON is much smaller, since there's no binary asset overhead to save on in the first place.

Bundling multiple animations in one file

Because manifest.json can list more than one entry under animations/, a single .lottie file can hold several related animations — for example, the "idle," "success," and "error" states of a button — and a player like @lottiefiles/dotlottie-web can switch between them by id at runtime. That means shipping one file and one network request instead of several separate JSON files for what is conceptually a single animated component.

When to use dotLottie vs. raw JSON

• Use dotLottie when your animation embeds raster images, when you need to bundle multiple related animations/states into one asset, or when you want a single binary file to manage instead of several JSON files.
• Use raw JSON for pure vector animations with no embedded images (there's little size benefit to gain), when you need maximum compatibility with older or simpler Lottie renderers that don't understand the container format, or when you want the animation data to be human-readable and diffable in version control — a .lottie file has to be unzipped before you can inspect or diff it.

Inspecting a .lottie file yourself

unzip animation.lottie -d animation-contents/
cat animation-contents/manifest.json