Nuxt Lottie

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

Since this module is listed in the Nuxt Modules directory, you can easily add it to your project using the following command:

npx nuxi module add lottie

That's it ✨ Now you can use the <Lottie> component in your Vue files. That prompt will automatically install the module and add it to your nuxt.config.ts file.

Manual Installation

If you prefer manual installation, you can 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

Then 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
    autoFolderCreation: true, // Optional: Auto create lottie folder (default: true)
    enableLogs: true // Optional: Enable console logs from module (default: true)
  }
})

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.

Note: If you're not going to use auto imports or prefer to manage folders manually, you can disable automatic folder creation by setting autoFolderCreation: false in your module options.

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

Usage

There are 3 ways to use component:

• 1: Using name prop with automatic imports of Lottie JSON files
• 2: Using data prop with provided Lottie JSON object
• 3: Using link prop with Lottie JSON link from CDN or any other source

Priority is given to the name prop, then data prop, and finally link prop.

1. Using name prop with automatic imports of JSON files

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

1.2 Use the <Lottie> Component

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

<template>
  <!-- Using a top-level animation -->
  <Lottie name="rocket" />

  <!-- Using a nested animation -->
  <Lottie name="nested/spaceship" />
</template>

2. Using data prop with JSON object

<template>
  <Lottie :data="HelloJSON"  />
</template>

<script setup lang="ts">
import HelloJSON from './hello.json'
</script>

3. Using link prop with link to JSON file

<template>
  <Lottie link="https://assets10.lottiefiles.com/packages/lf20_soCRuE.json"  />
</template>

Programmatic Control

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

Additionally, you can import the type of the Lottie component for better TypeScript support.

<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'
import type { Lottie } from 'nuxt-lottie'

const awesomeLottie = ref<Lottie | null>(null)

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

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

Module Options

You can configure the module behavior in your nuxt.config.ts file:

<Lottie> Props:

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.

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

This software is licensed under the MIT License | @volkanakkus | Special thanks to @megasanjay 💚