DEV Community

Fazal Shah
Fazal Shah

Posted on

dotLottie vs Lottie JSON: Which Should You Use in 2025?

Two formats exist for Lottie animations: the original .json (Lottie JSON) and the newer .lottie (dotLottie). They render identically in the browser — but one is dramatically smaller. Here's when to use each, and how to switch.

TL;DR

  • .json — use when maximum tooling compatibility matters (older projects, plugins that don't support dotLottie yet)
  • .lottie — use for everything else. 75% smaller, faster, supports multiple animations per file

What Is Lottie JSON?

.json is the original format, introduced by Airbnb's Bodymovin After Effects plugin in 2015. It's plain text JSON describing every layer, shape, keyframe, and property in the animation.

Example size: A 3-second loading spinner → ~25KB

Because it's plain JSON:

  • Human-readable
  • Universal support across all Lottie libraries
  • Can be edited with a text editor or a tool like IconKing

What Is dotLottie (.lottie)?

.lottie is a ZIP archive (renamed) containing the Lottie JSON plus any assets (images, fonts). It was introduced by LottieFiles in 2022.

Same 3-second spinner: ~7KB (72% smaller)

Additional features over .json:

  • Multiple animations in a single file (scenes)
  • Embedded fonts/images in one container
  • Metadata (author, description, version)
  • Background color and loop settings baked in

Size Comparison

These are real-world examples:

Animation .json .lottie Savings
Loading spinner 24KB 6KB 75%
Success checkmark 18KB 5KB 72%
Hero illustration 145KB 38KB 74%
Icon set (5 icons) 92KB 24KB 74%

The compression is consistent regardless of animation complexity.

Converting Between Formats

IconKing converts .json ↔.lottie in the browser:

  1. Go to iconking.net
  2. Drop your file onto the page
  3. Click the convert button
  4. Download the new format

No account, no upload limit, fully client-side. The converted file is byte-for-byte identical in visual output to the original.

Library Support Comparison

Library .json .lottie
lottie-web ✅ ❌
lottie-react ✅ ❌
vue3-lottie ✅ ❌
@lottiefiles/dotlottie-web ✅ ✅
@lottiefiles/dotlottie-react ✅ ✅
@lottiefiles/dotlottie-vue ✅ ✅
lottie-android ✅ ✅ (v2.0+)
lottie-ios ✅ ✅ (v4.0+)

Key insight: To use .lottie on web, you need to switch from lottie-web/lottie-react to the @lottiefiles/dotlottie-* libraries. The switch is a one-time migration — APIs are similar.

Migrating: lottie-react → dotlottie-react

Before (lottie-react, .json):

npm install lottie-react
Enter fullscreen mode Exit fullscreen mode 
import Lottie from 'lottie-react';
import animData from './animation.json';

<Lottie animationData={animData} loop autoplay />
Enter fullscreen mode Exit fullscreen mode

After (@lottiefiles/dotlottie-react, .lottie):

npm uninstall lottie-react
npm install @lottiefiles/dotlottie-react
Enter fullscreen mode Exit fullscreen mode 
import { DotLottieReact } from '@lottiefiles/dotlottie-react';

<DotLottieReact
  src="/animations/animation.lottie"
  loop
  autoplay
/>
Enter fullscreen mode Exit fullscreen mode

Key differences:

  • animationData prop → src prop (URL string, not JSON object)
  • Place .lottie files in public/animations/ instead of bundling them

Migrating: Vue

Before (vue3-lottie, .json):

<Vue3Lottie :animationData="animData" />
Enter fullscreen mode Exit fullscreen mode

After (@lottiefiles/dotlottie-vue, .lottie):

npm install @lottiefiles/dotlottie-vue
Enter fullscreen mode Exit fullscreen mode 
<DotLottieVue src="/animations/animation.lottie" :loop="true" :autoplay="true" />
Enter fullscreen mode Exit fullscreen mode

Migrating: Vanilla JS

Before (lottie-web, .json):

lottie.loadAnimation({
  container: el,
  animationData: require('./animation.json'),
  renderer: 'svg'
});
Enter fullscreen mode Exit fullscreen mode

After (@lottiefiles/dotlottie-web, .lottie):

npm install @lottiefiles/dotlottie-web
Enter fullscreen mode Exit fullscreen mode 
import { DotLottie } from '@lottiefiles/dotlottie-web';

const dotLottie = new DotLottie({
  canvas: document.getElementById('canvas'),  // Note: requires <canvas>, not <div>
  src: '/animations/animation.lottie',
  loop: true,
  autoplay: true,
});
Enter fullscreen mode Exit fullscreen mode

One important difference: dotlottie-web requires a <canvas> element, not a <div>.

When to Stick With .json

  1. You use lottie-web/lottie-react directly and don't want to swap libraries yet
  2. Designer tools like Adobe After Effects + Bodymovin export .json natively; no friction
  3. Older plugin ecosystem — some CMS plugins (WordPress Lottie plugins) only support .json
  4. Programmatic manipulation — editing colors via addValueCallback on lottie-web works with .json; dotLottie has different APIs for this

When to Use .lottie

  1. New projects — no legacy to worry about
  2. Mobile apps — 75% smaller files = meaningful bandwidth savings on LTE/3G
  3. Multiple animations — bundle a full icon set into one .lottie file
  4. Core Web Vitals — smaller files = better LCP scores
  5. CDN serving — less transfer cost

dotLottie Programmatic API

The @lottiefiles/dotlottie-web API is slightly different from lottie-web:

const dotLottie = new DotLottie({ canvas, src, loop: true, autoplay: true });

// Playback
dotLottie.play();
dotLottie.pause();
dotLottie.stop();
dotLottie.setSpeed(1.5);
dotLottie.setLoop(true);

// Events
dotLottie.addEventListener('play', () => console.log('playing'));
dotLottie.addEventListener('complete', () => console.log('done'));
dotLottie.addEventListener('frame', ({ currentFrame }) => {});

// Cleanup
dotLottie.destroy();
Enter fullscreen mode Exit fullscreen mode

Multiple Animations in One .lottie File

This is the killer feature of dotLottie for icon sets:

const dotLottie = new DotLottie({
  canvas,
  src: '/animations/icons.lottie', // contains 10 icons
  loop: false,
  autoplay: false,
});

// Switch to a specific animation by name
dotLottie.loadAnimation({ animationId: 'icon-success' });
dotLottie.play();
Enter fullscreen mode Exit fullscreen mode

Ship a full animated icon library as a single 30KB file instead of 10 separate 15KB files.

Workflow Recommendation

For new projects:

  1. Get .json from LottieFiles or your designer
  2. Preview and edit colors in IconKing
  3. Convert to .lottie in IconKing
  4. Install @lottiefiles/dotlottie-react (or vue/web)
  5. Use src="/animations/file.lottie" — done

For existing projects:

  1. Keep .json working (don't break things)
  2. Convert each file to .lottie at IconKing
  3. Migrate components one by one from lottie-react → dotlottie-react
  4. Remove lottie-react once fully migrated

Summary

.json .lottie
File size Larger ~75% smaller
Web library lottie-web, lottie-react @lottiefiles/dotlottie-*
Compatibility Universal Growing (all major platforms)
Multiple animations No Yes
Editing tools All Lottie tools IconKing, LottieFiles
Best for Legacy projects, CMS plugins New projects, mobile, performance

If you're starting fresh: use .lottie. Convert existing files at IconKing when you're ready to migrate.

Top comments (0)