vite-plugin-lottie

1.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin that enables import of Lottie JSON animation files as parsed animation data. Current version 1.0.1 (released 2023). Bundles Lottie files into the application by transforming imports with the `?lottie` query suffix. Designed exclusively for Vite, requires Lottie-web as runtime dependency. Provides TypeScript type declarations for the query suffix. Differentiates from other Lottie loaders by being a minimal, zero-config Vite plugin without additional bundler configuration.

Common errors

error Cannot find module './animation.json?lottie' or its corresponding type declarations. ↓

cause TypeScript does not know about the ?lottie query suffix without type augmentation.

fix

Add /// <reference types="vite-plugin-lottie/client" /> in a .d.ts file or in your tsconfig's include.

error Failed to load import './animation.json' from 'src/App.vue'. Unexpected token '}' in JSON at position... ↓

cause Importing a .json file without the ?lottie query, causing Vite to treat it as plain JSON.

fix

Change import to './animation.json?lottie'.

error Lottie is not defined ↓

cause Missing lottie-web runtime dependency; the plugin does not include Lottie player.

fix

Install lottie-web: npm install lottie-web

Warnings

gotcha You must append ?lottie to the import path, otherwise Vite will try to parse JSON as JavaScript and fail. ↓

fix Use import animationData from './animation.json?lottie'

gotcha The plugin only transforms imports with ?lottie query; regular JSON imports are unaffected. ↓

fix Ensure all Lottie file imports end with ?lottie

deprecated Plugin does not bundle lottie-web itself; you must install lottie-web separately. ↓

fix Install lottie-web as a regular dependency: npm install lottie-web

gotcha TypeScript users must add triple-slash reference to enable type checking for ?lottie imports. ↓

fix Add /// <reference types="vite-plugin-lottie/client" /> in a .d.ts file or tsconfig include.

Install

npm install vite-plugin-lottie

yarn add vite-plugin-lottie

pnpm add vite-plugin-lottie

Imports

lottie

wrong

import lottie from 'vite-plugin-lottie'

correct

import { lottie } from 'vite-plugin-lottie'

Named export, not default.

animationData

wrong

import animationData from './animation.json'

correct

import animationData from './animation.json?lottie'

Must append ?lottie query to trigger the plugin.

vite-plugin-lottie/client
wrong
```
import 'vite-plugin-lottie/client'
```
correct
```
/// <reference types="vite-plugin-lottie/client" />
```
Triple-slash directive for TypeScript type augmentation; not a runtime import.

Quickstart

Setup Vite plugin in config and use ?lottie import in Vue component to load animation.

// vite.config.ts
import { defineConfig } from 'vite'
import { lottie } from 'vite-plugin-lottie'

export default defineConfig({
  plugins: [lottie()],
})

// App.vue
<script setup lang="ts">
import Lottie from 'lottie-web'
import animationData from './animation.json?lottie'
import { onMounted } from 'vue'

onMounted(() => {
  Lottie.loadAnimation({
    container: document.getElementById('lottie-container'),
    renderer: 'svg',
    loop: true,
    autoplay: true,
    animationData: animationData
  })
})
</script>

<template>
  <div id="lottie-container" style="width: 200px; height: 200px;"></div>
</template>