Nuxt Lottie

Easily integrate Lottie animations into your Nuxt project.

• Compatibility: Nuxt >= 3

✨  Release Notes

Features

• 🗂️ Automatic Imports
• 🎨 Nested Folder Support
• 🛠️ Programmatic Control
• 💚 Nuxt 4 Ready

Quick Setup

1. Install nuxt-lottie

Add nuxt-lottie to your project using your preferred package manager.

# Using yarn
yarn add nuxt-lottie

# Using npm
npm install nuxt-lottie

# Using pnpm
pnpm add nuxt-lottie

2. Add nuxt-lottie to nuxt.config.ts

Add the module to the modules section of your nuxt.config.ts file.

export default defineNuxtConfig({
  modules: [
    'nuxt-lottie'
  ],
  lottie: {
    componentName: 'Lottie', // Optional: Customize the component name
    lottieFolder: '/assets/lottie' // Optional: Customize the Lottie folder path
  }
})

3. Verify Folder Structure

After installation, ensure that the assets/lottie folder exists. If it doesn't, the module will automatically create it for you. You can change the folder path using the lottieFolder option in the nuxt.config.ts file.

your-project/
├── assets/
│   └── lottie/
│       └── README.md
├── nuxt.config.ts
└── ...

Usage

1. Add Lottie Animations

Place your .json animation files inside the assets/lottie folder. You can organize them into nested folders as needed.

assets/
└── lottie/
    ├── rocket.json
    └── nested/
        └── spaceship.json

2. Use the <Lottie> Component

Import and use the <Lottie> component in your Vue files.

<template>
  <!-- Using a top-level animation -->
  <Lottie name="rocket" loop autoplay style="width:200px" />

  <!-- Using a nested animation -->
  <Lottie name="nested/spaceship" loop autoplay style="width:200px" />
</template>

3. Programmatic Control

You can control the animation using methods exposed by the <Lottie> component. Use ref to access these methods.

<template>
  <Lottie ref="awesomeLottie" name="awesome" />
  <button @click="playAnimation">Play Animation</button>
  <button @click="pauseAnimation">Pause Animation</button>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const awesomeLottie = ref(null)

const playAnimation = () => {
  awesomeLottie.value?.play()
}

const pauseAnimation = () => {
  awesomeLottie.value?.pause()
}
</script>

Props and options

More detailed explanations are provided in the documentation.

Prop	Type	Default Value	Description
name	String	null	The name of the animation file without the .json extension. Supports nested paths (e.g., "folder/animation").
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.

• 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 <Lottie> component.

• 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.

Development

# Clone the repository
git clone https://github.com/volkanakkus/nuxt-lottie.git
cd nuxt-lottie

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run build

# Develop the docs
npm run dev:docs

---

Thanks to @megasanjay for vue3-lottie. This module is a wrapper around it, enhancing it with automatic asset management and simplified usage within Nuxt 3 projects.

Every download of this module will also support the original creator, as it is a dependency of this module. 🙏

This software is licensed under the MIT License | @volkanakkus 💚