dotLottie vs JSON: which Lottie format to ship
Lottie animations come in two file formats: the original .json and the newer .lottie (dotLottie). They describe the same animations, but they package them very differently — one is a single human-readable text document, the other is a zip container that can hold several animations, themes, and images at once. Choosing wrong costs you either flexibility or file size. Here is how to decide.
What .json actually is
A .json Lottie file is one animation, described as a single JSON document. You can open it in a text editor, search it, diff it in version control, and hand-edit a color or a frame rate. Its structure is the one described in why your Lottie file is 70 MB: a header with canvas size and frame rate, a layers array, and an assets array for referenced images.
The strength of plain JSON is transparency. Anything that can read JSON can read your animation: your build pipeline, your CMS, a quick script that rewrites a color across fifty files. The weakness is that everything lives in one text file. Images embedded as base64 data URLs pay a ~33% encoding overhead, and the whole document has to be parsed as one unit.
What .lottie actually is
A .lottie file is a zip archive with a defined layout: a manifest.json describing what is inside, one or more animation JSON files, and any image assets stored as separate binary entries. Because the images are stored as binary rather than base64 text, the container avoids the encoding overhead — the same animation is meaningfully smaller as a .lottie than as an inlined .json.
The format was designed for shipping, not for editing. You would not normally open a .lottie file in a text editor; you open it with a dotLottie-aware player or tool, which unzips it, reads the manifest, and picks the animation it needs.
Multiple animations and themes
The headline feature of dotLottie is bundling. One .lottie file can contain several animations — for example, the idle, loading, success, and error states of a single UI flow — plus named themes that recolor the animations for light and dark mode. The player loads the bundle once and switches between animations without additional network requests.
With plain JSON, the same set is four separate files, four requests, and four chances to get out of sync. If you ship a family of related animations, dotLottie is the cleaner distribution format.
File size, honestly
For a pure vector animation, the difference between the formats is small: the JSON is already tiny, and the zip container only saves the base64 overhead, which barely applies when there are no embedded images. The win grows with raster content. An animation with embedded PNG frames is noticeably smaller as a .lottie because the PNGs are stored as binary zip entries instead of base64 text.
But neither format compresses the images themselves. A .lottie file full of PNGs is still a file full of PNGs. If size is the problem, the fix is re-encoding the frames, not re-packaging them. The lottie-mini compressor accepts both .json and .lottie input, re-encodes embedded images to WebP, and can output .lottie — so you can take a bloated JSON, shrink it, and ship the smaller container in one step. The sample on the home page, a 70 MB file compressed to about 1.1 MB, is the scale of reduction that re-encoding delivers; re-packaging alone would never get close.
Player and tooling support
Plain JSON is supported by every Lottie player ever written, including lottie-web, iOS, and Android players. dotLottie needs a player that knows how to unzip and read the manifest — the dotLottie players on web, iOS, and Android do, and most modern tooling has caught up, but if you are targeting an older or minimal player, JSON is the safe choice.
On the authoring side, the same split applies. JSON is easy to generate, transform, and inspect with generic tools. dotLottie is easy to ship, but producing it requires a dotLottie-aware exporter or a converter. If your pipeline is a script that edits JSON and pushes it to a CDN, keep JSON as your working format and convert to dotLottie at the end, if at all.
When to use each
- Ship .json when: you have a single animation; you need maximum player compatibility; your pipeline reads or transforms the file as text; you want clean diffs in version control; or you are embedding the animation inline in a page or an email template.
- Ship .lottie when: you have several related animations to distribute together; you need themes (for example light/dark variants); the animation carries embedded images and you want to avoid base64 overhead; or your player already supports dotLottie and you want the smaller download.
A practical workflow
A sensible default for most teams: keep .json as the source of truth in your repository, where it is diffable and editable. At build or publish time, convert to .lottie when you are bundling related animations or shipping images, and run the result through a compressor either way. If you are rendering the animation in React, the embedding code is the same either way — see how to embed Lottie in React — and if you are still deciding between animation formats entirely, Lottie vs GIF vs MP4 covers the wider choice.
Summary
JSON is the editable, universal, single-animation format. dotLottie is the shippable, bundled, multi-animation format that avoids base64 overhead. Neither one compresses your images — that is a separate step. Use JSON while you are working on an animation, use dotLottie when you are distributing a family of them, and compress the raster frames either way.