What it does to your file
A Lottie file has two parts: the animation data (layers, shapes and keyframes) and the images. In most heavy files the images are the problem. A splash screen we tested held five PNGs that made up 97% of its 6.4 MB. Compression brought it to 3.2 MB without touching a single keyframe.
- Every image gets several candidate encodings. These are lossless PNG optimisation (oxipng), a 256-colour palette PNG with dithering (the pngquant approach), and JPEG for images with no transparency.
- Each candidate is scored against the original. The score is PSNR over the visible pixels. Transparent areas are skipped, so a mostly empty overlay can't score well just because it is mostly empty.
- The smallest candidate that passes your quality guard wins. If none passes, the image stays lossless. This guard is why soft gradients and skies don't come back banded.
- The JSON gets lossless cleanup. Duplicate images are merged and assets no layer uses are dropped. Editor metadata goes, and the whitespace is minified.
Pick a mode
| Mode | Use it when | Typical saving |
|---|---|---|
| Smart | You want the smallest file that looks the same. This is the default. | 40–80% on image-heavy files |
| Lossless | Every pixel must stay identical, for example for brand assets or legal sign-off. | 10–25% |
| Target size | A store, CMS or bundle sets a hard limit, such as 4 MB. | Whatever it takes, least visible quality first |
Things that catch people out
- File size isn't memory. A 1355×2786 PNG takes 15 MB of RAM once decoded, whether the file is 2 MB or 300 KB. If an animation stutters on low-end Android, reduce the image's pixel dimensions. Compression won't fix that.
- Gzip already helps on the web. Servers send JSON gzipped, but base64 images barely compress further. The download stays big until the images themselves shrink.
- Swapping images by id at runtime? Merging duplicates points layers at one shared asset id. If your app replaces images by asset id (an image asset delegate), turn off Merge duplicate images.
- Layer names matter to code. Dynamic properties (KeyPath on mobile) and expressions find layers by name, so names are kept unless you strip them.
Want to know why the file is heavy first? Open it in the Lottie Inspector. For the full background, read why Lottie files get so big.