vue3-lottie
v4.0.0
Published
Readme
Vue 3 Lottie
Add Lottie animations to your Vue 3 or Nuxt 3 application.
vue3-lottie was created to help developers add Lottie animations to their Vue 3 applications. In my search for a simple way to add Lottie animations to my Vue application I found a suprising lack of maintained solutions. vue3-lottie is a vue wrapper around the lottie-web library with a few additional features.
Demos
View the live demos here: https://vue3-lottie.vercel.app
Upgrade to v4.x
v4 adds a light build (vue3-lottie/light) that avoids the eval warning from lottie-web; see Light build below. The public API is unchanged from v3; see the v4 migration guide.
Coming from 2.x? The dist/style.css import has been removed; see the v3 migration guide.
Installation and Usage
Vue 3
- You can install
vue3-lottieoveryarnornpm.lottie-webis a dependency ofvue3-lottieand should be automatically installed when you installvue3-lottie.
If you are using npm:
npm install vue3-lottie@latest --saveIf you are using yarn:
yarn add vue3-lottie@latest- Register the component in your Vue 3 application.
The most common use case is to register the component globally.
// main.js
import { createApp } from 'vue'
import Vue3Lottie from 'vue3-lottie'
createApp(App).use(Vue3Lottie).mount('#app')If you get an error with TS, try use(Vue3Lottie, { name: "Vue3Lottie" })
To define global components for Volar type-checking you will need to add:
// components.d.ts
declare module '@vue/runtime-core' {
export interface GlobalComponents {
LottieAnimation: (typeof import('vue3-lottie'))['Vue3Lottie']
}
}
export {}If needed rename component to use:
app.use(Vue3Lottie, { name: 'LottieAnimation' }) // use in template <LottieAnimation />namestring (default: 'Vue3Lottie') - set custom component name
Alternatively you can also import the component locally.
import { Vue3Lottie } from 'vue3-lottie'
export default {
components: {
Vue3Lottie,
},
}You can then use the component in your template
<template>
<Vue3Lottie :animationData="AstronautJSON" :height="200" :width="200" />
</template>
<script>
import { Vue3Lottie } from 'vue3-lottie'
import AstronautJSON from './astronaut.json'
export default {
components: {
Vue3Lottie,
},
data() {
return {
AstronautJSON,
}
},
}
</script>Nuxt 3
This is still experimental. Will be updated soon.
- You can install
vue3-lottieoveryarnornpm.lottie-webis a dependency ofvue3-lottieand should be automatically installed when you installvue3-lottie.
If you are using npm:
npm install vue3-lottie@latest --saveIf you are using yarn:
yarn add vue3-lottie@latest- Create a folder called
pluginsat the root of your project. - Create a file named
Vue3Lottie.client.tsinside the plugins directory. - Add the following code to the
Vue3Lottie.client.tsfile.
import { Vue3Lottie } from 'vue3-lottie'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.component('Vue3Lottie')
})If you get an error with TS, try component(Vue3Lottie, { name: "Vue3Lottie" })
This should register as a global component that you can call anywhere in your app under the tag.
I would recommend using a <client-only> parent tag to ensure that the animation only loads in on the client side.
<client-only>
<Vue3Lottie
animationLink="https://assets10.lottiefiles.com/packages/lf20_soCRuE.json"
:height="200"
:width="200"
/>
</client-only>Light build (no eval)
The default entry uses the full lottie-web player, which evaluates After Effects expressions with eval. Bundlers such as Vite/Rollup will warn about this:
Use of eval in "node_modules/lottie-web/build/player/lottie.js" is strongly discouraged...If your animations don't use expressions, import from vue3-lottie/light instead. It uses lottie-web's light player: no eval, and a smaller bundle. The API is the same. More details in the docs.
import Vue3Lottie from 'vue3-lottie/light'
// or
import { Vue3Lottie } from 'vue3-lottie/light'Limitations of the light build:
- Only the
svgrenderer is supported. - Expressions in the animation are not evaluated, so properties driven by them won't animate as intended.
Props and options
More detailed explanations are provided in the documentation.
| Prop | Type | Default Value | Description |
| ---------------- | ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ |
| animationData | Object | {} | The lottie animation data provided as a JSON object |
| animationLink | String | '' | A URL link to the Lottie animation data (eg: Lottie Animation URL on lottiefiles.com) |
| width | Number or String | "100%" | Width of the lottie animation container (Numbers correspond to pixel values) |
| height | Number or String | "100%" | Height of the lottie animation container (Numbers correspond to pixel values) |
| speed | Number | "1" | Speed of the lottie animation |
| direction | String | "forward" | Animation play direction |
| loop | Number or Boolean | true | The number of instances that the lottie animation should run (true is infinite) |
| autoPlay | Boolean | true | Start animation on component load |
| delay | Number | 0 | Delay the animation play state by some milliseconds |
| pauseAnimation | Boolean | false | Prop to pass reactive variables so that you can control animation pause and play |
| pauseOnHover | Boolean | false | Whether to pause the animation on hover |
| playOnHover | Boolean | false | Whether to play the animation when you hover |
| backgroundColor | String | transparent | Background color of the container |
| noMargin | Boolean | false | Prevent the lottie from auto centering in the container. This gives you better control on placement within your UI |
| scale | Number | 1 | Scale the animation (might cause blurriness) |
| assetsPath | String | "" | URL to the image asset you need to use in your Lottie animation |
| renderer | String | "svg" | Set the renderer |
| rendererSettings | Object | {} | Options for if you want to use an existing canvas to draw (can be ignored on most cases) |
Events
A few events are emitted from the component. Look at the Demos for examples.
- onComplete
- If your animation has a finite amount of loops you can use this event to know when the animation has completed.
- onLoopComplete
- If your animation has a finite amount of loops you can use this event to know when the animation has completed a loop.
- onEnterFrame
- This event is fired every frame of the animation. There will be 60 events fired per second if your lottie animation runs at 60fps.
- onSegmentStart
- This event is fired when the animation enters a segment.
- onAnimationLoaded
- This event is fired when the animation has loaded. This should let you know when you can start referencing the methods for the component.
Methods
You can control the animation with the following methods. These methods can be called by assigning a ref value to the vue3-lottie component. Look at the Demos for examples.
- play
- Plays the animation
- pause
- Pauses the animation
- stop
- Stops the animation. This will also reset the animation to the first frame. Look at the demo for some examples.
- destroy
- You can call this method to destroy the animation. It will remove the animation from the DOM.
- setSpeed(speed)
- You can call this method to change the speed of your animation.
- setDirection(direction)
- You can call this method to change the direction of your animation.
- getDuration(inFrames)
- You can call this method to get the duration of your animation.
- goToAndStop(frameNumber, isFrames)
- You can call this method to go to a specific frame of your animation. The animation will be stopped at the end of this call.
- goToAndPlay(frameNumber, isFrames)
- You can call this method to go to a specific frame of your animation. The animation will be played from this frame.
- playSegments(segments, forceFlag)
- You can call this method to play a specific segment of your animation.
- setSubFrame(subFrame)
- You can call this method to set the subframe value.
- updateDocumentData(documentData, index)
- This method updates text on text layers. Refer to the official docs for how to use this method.
