lottie-web vs vue3-lottie

Rendering Lottie Animations in Web Applications

lottie-web and vue3-lottie are both libraries used to render Lottie animations in web applications, but they serve different architectural needs. lottie-web is the official, framework-agnostic library from Airbnb that provides low-level control over Lottie animations using a canvas, SVG, or HTML renderer. It works directly with JSON-based animation files exported from Adobe After Effects via the Bodymovin plugin. vue3-lottie, on the other hand, is a Vue 3–specific wrapper around lottie-web that simplifies integration into Vue components by exposing reactive props and lifecycle management tailored to the Vue reactivity system.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package	Downloads	Stars	Size	Issues	Publish	License
Package	Downloads	Stars	Size	Issues	Publish	License
lottie-web	0	31,836	25.4 MB	847	a year ago	MIT
vue3-lottie	0	429	42.7 kB	16	2 years ago	MIT

lottie-web vs vue3-lottie: Rendering Lottie Animations in Modern Web Apps

Both lottie-web and vue3-lottie enable you to embed rich, scalable vector animations from Lottie JSON files into your web projects. However, they differ significantly in scope, control, and integration style. Let’s break down how they compare in real-world development scenarios.

🧱 Core Architecture: Low-Level Engine vs Vue Component Wrapper

lottie-web is the official, standalone JavaScript library maintained by the Lottie team. It renders animations using SVG, Canvas, or HTML, and gives you full programmatic control over playback, events, and rendering settings.

// lottie-web: Manual setup in vanilla JS
import lottie from 'lottie-web';

const anim = lottie.loadAnimation({
  container: document.getElementById('anim'),
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: '/animations/rocket.json'
});

// Later, control playback
anim.pause();
anim.setSpeed(2);

vue3-lottie is a thin Vue 3 component that wraps lottie-web. It exposes animation properties as reactive props and handles instance lifecycle (creation, destruction) automatically within Vue’s component model.

<!-- vue3-lottie: Declarative usage in Vue 3 -->
<template>
  <Vue3Lottie
    :animationData="rocketAnim"
    :loop="true"
    :autoplay="true"
    :speed="2"
  />
</template>

<script setup>
import { Vue3Lottie } from 'vue3-lottie';
import rocketAnim from '@/assets/rocket.json';
</script>

💡 Note: vue3-lottie internally uses lottie-web — it doesn’t reimplement the renderer. It’s purely a convenience layer for Vue.

⚙️ Control and Customization: Direct API vs Prop-Based Interface

lottie-web gives you access to the full animation instance, including methods like goToAndStop(), setDirection(), destroy(), and event listeners (enterFrame, complete, etc.). This is essential for complex interactions.

// lottie-web: Advanced control
const anim = lottie.loadAnimation({ /* ... */ });

anim.addEventListener('complete', () => {
  console.log('Animation finished');
});

anim.goToAndStop(30, true); // Frame 30

vue3-lottie abstracts the instance away. While it supports common props like speed, loop, and autoplay, it does not expose the raw lottie instance or low-level methods by default. To access the instance, you must use a template ref and call .getLottie():

<template>
  <Vue3Lottie ref="lottieRef" :animationData="animData" />
</template>

<script setup>
import { ref, onMounted } from 'vue';

const lottieRef = ref(null);

onMounted(() => {
  const instance = lottieRef.value.getLottie();
  instance.addEventListener('complete', () => {
    console.log('Done!');
  });
});
</script>

This extra step adds indirection and may feel cumbersome if you frequently need direct control.

🧹 Lifecycle Management: Manual Cleanup vs Automatic

lottie-web requires you to manually destroy animations to prevent memory leaks, especially in SPAs where components mount/unmount frequently.

// lottie-web: Must call destroy()
const anim = lottie.loadAnimation({ /* ... */ });

// In a React useEffect cleanup or similar
return () => anim.destroy();

vue3-lottie handles this automatically. When the Vue component unmounts, it calls destroy() on the underlying animation instance, reducing the risk of leaks without developer intervention.

<!-- No manual cleanup needed — handled by Vue3Lottie's onBeforeUnmount -->
<Vue3Lottie :animationData="data" />

This is a major DX win in Vue apps, especially for junior developers or rapid prototyping.

📦 Bundle Impact and Dependencies

lottie-web is a self-contained dependency. You import only what you need (e.g., the player build).

vue3-lottie depends on lottie-web as a peer dependency, so you still pull in the full lottie-web bundle. The wrapper itself is small, but there’s no bundle savings — you’re adding a layer on top of the same core library.

If you’re already using lottie-web elsewhere in your app, vue3-lottie introduces no additional runtime cost beyond its component logic. But if you only need basic Vue integration, the wrapper is lightweight enough to justify its convenience.

🛠️ Error Handling and Debugging

Both libraries inherit the same error behavior from lottie-web. Invalid JSON, missing containers, or unsupported features will throw errors or log warnings to the console.

However, lottie-web lets you catch errors immediately during loadAnimation(), while vue3-lottie may delay error visibility until the component mounts, which can make debugging less immediate in complex Vue trees.

🔄 Reactivity and Dynamic Updates

lottie-web requires manual updates when animation properties change:

// Update speed dynamically
anim.setSpeed(newSpeed);

vue3-lottie uses Vue’s reactivity system. When you change a prop like :speed, it automatically calls the corresponding setter on the instance:

<Vue3Lottie :animationData="anim" :speed="reactiveSpeed" />
<!-- Changing reactiveSpeed updates the animation instantly -->

This declarative sync is one of the strongest reasons to use vue3-lottie in Vue apps — it eliminates boilerplate for common state-driven animation controls.

🧪 Testing and Mocking

In unit tests, lottie-web is easier to mock because it’s a plain function call. You can stub lottie.loadAnimation directly.

With vue3-lottie, you often need to mock the entire component or rely on Vue Test Utils to shallow-mount and inspect refs, which adds complexity.

✅ When to Use Which?

Scenario	Recommended Package
Building a Vue 3 app with simple, declarative animations	`vue3-lottie`
Need fine-grained control (frame-by-frame, custom events, dynamic path changes)	`lottie-web`
Working outside Vue (React, Svelte, vanilla JS)	`lottie-web`
Rapid prototyping in Vue with minimal setup	`vue3-lottie`
Performance-critical animations requiring custom renderers	`lottie-web`

💡 Final Recommendation

Use vue3-lottie if you’re in a Vue 3 codebase and your animation needs are straightforward — play, pause, speed control, and lifecycle safety out of the box. It keeps your components clean and leverages Vue’s strengths.

Reach for lottie-web directly when you need deeper integration, are not using Vue, or require capabilities beyond what the wrapper exposes. It’s the foundation — everything else builds on it.

Remember: vue3-lottie is a helper, not a replacement. Understanding lottie-web’s API will make you more effective even when using the Vue wrapper.

How to Choose: lottie-web vs vue3-lottie

lottie-web:
Choose lottie-web if you need maximum control over animation rendering, are working in a framework-agnostic environment (e.g., vanilla JS, React, Svelte), or require advanced features like custom renderers, dynamic property manipulation, or precise performance tuning. It’s ideal for teams that prioritize flexibility and direct access to the underlying animation engine without abstraction layers.
vue3-lottie:
Choose vue3-lottie if you’re building a Vue 3 application and want a declarative, component-based API that integrates seamlessly with Vue’s reactivity and lifecycle. It reduces boilerplate by handling instance creation, cleanup, and prop synchronization automatically, making it well-suited for standard use cases where you simply need to display and control Lottie animations with minimal setup.

Popular Comparisons

lottie-web

vue3-lottie

README for lottie-web

Lottie for Web, Android, iOS, React Native, and Windows

Lottie is a mobile library for Web, and iOS that parses Adobe After Effects animations exported as json with Bodymovin and renders them natively on mobile!

For the first time, designers can create and ship beautiful animations without an engineer painstakingly recreating it by hand. They say a picture is worth 1,000 words so here are 13,000:

View documentation, FAQ, help, examples, and more at airbnb.io/lottie

Example1

Example2

Example3

Community

Example4

Plugin installation

Option 1 (Recommended):

Download it from from aescripts + aeplugins: https://aescripts.com/bodymovin/

Option 2:

Or get it from the adobe store https://exchange.adobe.com/creativecloud.details.12557.html CC 2014 and up.

Other installation options:

Option 3:

download the ZIP from the repo.
Extract content and get the .zxp file from '/build/extension'
Use the ZXP installer from aescripts.com.

Option 4:

Close After Effects
Extract the zipped file on build/extension/bodymovin.zxp to the adobe CEP folder:
WINDOWS:
C:\Program Files (x86)\Common Files\Adobe\CEP\extensions or
C:\<username>\AppData\Roaming\Adobe\CEP\extensions
MAC:
/Library/Application\ Support/Adobe/CEP/extensions/bodymovin
(you can open the terminal and type:
$ cp -R YOURUNZIPEDFOLDERPATH/extension /Library/Application\ Support/Adobe/CEP/extensions/bodymovin
then type:
$ ls /Library/Application\ Support/Adobe/CEP/extensions/bodymovin
to make sure it was copied correctly type)
Edit the registry key:
WINDOWS:
open the registry key HKEY_CURRENT_USER/Software/Adobe/CSXS.6 and add a key named PlayerDebugMode, of type String, and value 1.
MAC:
open the file ~/Library/Preferences/com.adobe.CSXS.6.plist and add a row with key PlayerDebugMode, of type String, and value 1.

Option 5:

Install the zxp manually following the instructions here: https://helpx.adobe.com/x-productkb/global/installingextensionsandaddons.html Skip directly to "Install third-party extensions"

Option 6:

Install with Homebrew-adobe:

brew tap danielbayley/adobe
brew cask install lottie

After installing

Windows: Go to Edit > Preferences > Scripting & Expressions... > and check on "Allow Scripts to Write Files and Access Network"
Mac: Go to Adobe After Effects > Preferences > Scripting & Expressions... > and check on "Allow Scripts to Write Files and Access Network"

Old Versions

Windows: Go to Edit > Preferences > General > and check on "Allow Scripts to Write Files and Access Network"
Mac: Go to Adobe After Effects > Preferences > General > and check on "Allow Scripts to Write Files and Access Network"

HTML player installation

# with npm
npm install lottie-web

# with bower
bower install bodymovin

Or you can use the script file from here: https://cdnjs.com/libraries/bodymovin Or get it directly from the AE plugin clicking on Get Player

Demo

See a basic implementation here.

Examples

See examples on codepen.

How it works

Here's a video tutorial explaining how to export a basic animation and load it in an html page

After Effects

Open your AE project and select the bodymovin extension on Window > Extensions > bodymovin
A Panel will open with a Compositions tab listing all of your Project Compositions.
Select the composition you want to export.
Select a Destination Folder.
Click Render
look for the exported json file (if you had images or AI layers on your animation, there will be an images folder with the exported files)

HTML

get the lottie.js file from the build/player/ folder for the latest build
include the .js file on your html (remember to gzip it for production)

<script src="js/lottie.js" type="text/javascript"></script>

You can call lottie.loadAnimation() to start an animation. It takes an object as a unique param with:

animationData: an Object with the exported animation data. Note: If your animation contains repeaters and you plan to call loadAnimation multiple times with the same animation, please deep clone the object before passing it (see #1159 and #2151.)
path: the relative path to the animation object. (animationData and path are mutually exclusive)
loop: true / false / number
autoplay: true / false it will start playing as soon as it is ready
name: animation name for future reference
renderer: 'svg' / 'canvas' / 'html' to set the renderer
container: the dom element on which to render the animation

It returns the animation instance you can control with play, pause, setSpeed, etc.

lottie.loadAnimation({
  container: element, // the dom element that will contain the animation
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: 'data.json' // the path to the animation json
});

Composition Settings:

Check this wiki page for an explanation for each setting. https://github.com/airbnb/lottie-web/wiki/Composition-Settings

Usage

Animation instances have these main methods:

play

stop

pause

setSpeed(speed)

speed: 1 is normal speed.

goToAndStop(value, isFrame)

value: numeric value.
isFrame: defines if first argument is a time based value or a frame based (default false).

goToAndPlay(value, isFrame)

value: numeric value.
isFrame: defines if first argument is a time based value or a frame based (default false).

setDirection(direction)

direction: 1 is forward, -1 is reverse.

playSegments(segments, forceFlag)

segments: array. Can contain 2 numeric values that will be used as first and last frame of the animation. Or can contain a sequence of arrays each with 2 numeric values.
forceFlag: boolean. If set to false, it will wait until the current segment is complete. If true, it will update values immediately.

setSubframe(useSubFrames)

useSubFrames: If false, it will respect the original AE fps. If true, it will update on every requestAnimationFrame with intermediate values. Default is true.

destroy()

getDuration(inFrames)

inFrames: If true, returns duration in frames, if false, in seconds.

Additional methods:

updateDocumentData -- updates a text layer's data More Info

Lottie has several global methods that will affect all animations:

lottie.play() -- with 1 optional parameter name to target a specific animation
lottie.stop() -- with 1 optional parameter name to target a specific animation
lottie.goToAndStop(value, isFrame, name) -- Moves an animation with the specified name playback to the defined time. If name is omitted, moves all animation instances.
lottie.setSpeed() -- first argument speed (1 is normal speed) -- with 1 optional parameter name to target a specific animation
lottie.setDirection() -- first argument direction (1 is normal direction.) -- with 1 optional parameter name to target a specific animation
lottie.searchAnimations() -- looks for elements with class "lottie" or "bodymovin"
lottie.loadAnimation() -- Explained above. returns an animation instance to control individually.
lottie.destroy(name) -- Destroys an animation with the specified name. If name is omitted, destroys all animation instances. The DOM element will be emptied.
lottie.registerAnimation() -- you can register an element directly with registerAnimation. It must have the "data-animation-path" attribute pointing at the data.json url
lottie.getRegisteredAnimations() -- returns all animations instances
lottie.setQuality() -- default 'high', set 'high','medium','low', or a number > 1 to improve player performance. In some animations as low as 2 won't show any difference.
lottie.setLocationHref() -- Sets the relative location from where svg elements with ids are referenced. It's useful when you experience mask issues in Safari.
lottie.freeze() -- Freezes all playing animations or animations that will be loaded
lottie.unfreeze() -- Unfreezes all animations
lottie.inBrowser() -- true if the library is being run in a browser
lottie.resize() -- Resizes all animation instances

Events

onComplete
onLoopComplete
onEnterFrame
onSegmentStart

you can also use addEventListener with the following events:

complete
loopComplete
drawnFrame
enterFrame
segmentStart
config_ready (when initial config is done)
data_ready (when all parts of the animation have been loaded)
data_failed (when part of the animation can not be loaded)
loaded_images (when all image loads have either succeeded or errored)
DOMLoaded (when elements have been added to the DOM)
destroy

Other loading options

if you want to use an existing canvas to draw, you can pass an extra object: 'rendererSettings' with the following configuration:

lottie.loadAnimation({
  container: element, // the dom element
  renderer: 'svg',
  loop: true,
  autoplay: true,
  animationData: animationData, // the animation data
  // ...or if your animation contains repeaters:
  // animationData: cloneDeep(animationData), // e.g. lodash.clonedeep
  rendererSettings: {
    context: canvasContext, // the canvas context, only support "2d" context
    preserveAspectRatio: 'xMinYMin slice', // Supports the same options as the svg element's preserveAspectRatio property
    title: 'Accessible Title', // Adds SVG title element for accessible animation title
    description: 'Accessible description.', // Adds SVG desc element for accessible long description of animation
    clearCanvas: false,
    progressiveLoad: false, // Boolean, only svg renderer, loads dom elements when needed. Might speed up initialization for large number of elements.
    hideOnTransparent: true, //Boolean, only svg renderer, hides elements when opacity reaches 0 (defaults to true)
    className: 'some-css-class-name',
    id: 'some-id',
  }
});

Doing this you will have to handle the canvas clearing after each frame
Another way to load animations is adding specific attributes to a dom element. You have to include a div and set it's class to "lottie". If you do it before page load, it will automatically search for all tags with the class "lottie". Or you can call lottie.searchAnimations() after page load and it will search all elements with the class "lottie".

Add the data.json to a folder relative to the html
Create a div that will contain the animation.
Required
- A class called "lottie"
- A "data-animation-path" attribute with relative path to the data.json
Optional
- A "data-anim-loop" attribute
- A "data-name" attribute to specify a name to target play controls specifically

Example

 <div style="width:1067px;height:600px"  class="lottie" data-animation-path="animation/" data-anim-loop="true" data-name="ninja"></div>

Preview

You can preview or take an svg snapshot of the animation to use as poster. After you render your animation, you can take a snapshot of any frame in the animation and save it to your disk. I recommend to pass the svg through an svg optimizer like https://jakearchibald.github.io/svgomg/ and play around with their settings.

Recommendations

Files

If you have any images or AI layers that you haven't converted to shapes (I recommend that you convert them, so they get exported as vectors, right click each layer and do: "Create shapes from Vector Layers"), they will be saved to an images folder relative to the destination json folder. Beware not to overwrite an existing folder on that same location.

Performance

This is real time rendering. Although it is pretty optimized, it always helps if you keep your AE project to what is necessary
More optimizations are on their way, but try not to use huge shapes in AE only to mask a small part of it.
Too many nodes will also affect performance.

Help

If you have any animations that don't work or want me to export them, don't hesitate to write.
I'm really interested in seeing what kind of problems the plugin has.
my email is hernantorrisi@gmail.com

AE Feature Support

The script supports precomps, shapes, solids, images, null objects, texts
It supports masks and inverted masks. Maybe other modes will come but it has a huge performance hit.
It supports time remapping
The script supports shapes, rectangles, ellipses and stars.
Expressions. Check the wiki page for more info.
Not supported: image sequences, videos and audio are not supported
No negative layer stretching! No idea why, but stretching a layer messes with all the data.

Development

npm install or bower install first npm start

Notes

If you want to modify the parser or the player, there are some gulp commands that can simplify the task
look at the great animations exported on codepen See examples on codepen.
gzipping the animation jsons and the player have a huge reduction on the filesize. I recommend doing it if you use it for a project.

Issues

For missing mask in Safari browser, please call lottie.setLocationHref(locationHref) before animation is generated. It usually caused by usage of base tag in html. (see above for description of setLocationHref)

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]