{"id":15910,"library":"vue-lottie-player","title":"Vue Lottie Player","description":"Vue Lottie Player is a type-safe Vue 3 component and plugin for integrating Lottie animations into web applications, built as a wrapper around the `lottie-web` library. The current stable version is 2.0.2. This library prioritizes security and performance by offering a default 'light-player' build that is CSP-friendly and avoids `unsafe-eval`, alongside an opt-in '/full' entry for animations requiring After Effects expressions. It provides a robust API for both URL- and JSON-based animation sources, imperative ref controls for direct playback manipulation, and straightforward integration with Nuxt 3. Its key differentiators include built-in TypeScript types, a focus on CSP compliance, and a clear separation between a lean default build and a feature-rich full build.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/turopoff/vue-lottie-player","tags":["javascript","vuejs","lottie","vue-lottie","lottie-vue","lottie-web","web-lottie","lottie-player","player-lottie","typescript"],"install":[{"cmd":"npm install vue-lottie-player","lang":"bash","label":"npm"},{"cmd":"yarn add vue-lottie-player","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-lottie-player","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue 3 component integration.","package":"vue","optional":false}],"imports":[{"note":"Main component for rendering Lottie animations. It is a named export.","wrong":"import VueLottiePlayer from 'vue-lottie-player';","symbol":"VueLottiePlayer","correct":"import { VueLottiePlayer } from 'vue-lottie-player';"},{"note":"Plugin for global registration in Vue applications.","symbol":"VueLottiePlayerPlugin","correct":"import { VueLottiePlayerPlugin } from 'vue-lottie-player';"},{"note":"TypeScript type for defining URL-based animation sources.","symbol":"LottieUrlSource","correct":"import type { LottieUrlSource } from 'vue-lottie-player';"},{"note":"Required stylesheet for the component to render correctly.","symbol":"style.css","correct":"import 'vue-lottie-player/style.css';"}],"quickstart":{"code":"import { ref } from 'vue';\nimport type { AnimationItem } from 'lottie-web';\nimport 'vue-lottie-player/style.css';\nimport type { LottieUrlSource, LottieDataSource, VueLottiePlayerInstance } from 'vue-lottie-player';\nimport { VueLottiePlayer } from 'vue-lottie-player';\n\n// Assuming you have an animation JSON file at /animations/sample-animation.json\n// Or if using local data:\n// import demoAnimationData from './assets/demo-animation.json';\n\nconst sourceUrl: LottieUrlSource = {\n  kind: 'url',\n  value: '/animations/sample-animation.json'\n};\n\n// Example for local JSON data:\n// const sourceData: LottieDataSource = {\n//   kind: 'data',\n//   value: demoAnimationData\n// };\n\nconst playerRef = ref<VueLottiePlayerInstance | null>(null);\n\nfunction onReady(animation: AnimationItem) {\n  console.log('Lottie animation is ready:', animation);\n  animation.setSpeed(1.5);\n}\n\nfunction playAnimation() {\n  playerRef.value?.play();\n}\n\nfunction pauseAnimation() {\n  playerRef.value?.pause();\n}\n\nfunction stopAnimation() {\n  playerRef.value?.stop();\n}\n","lang":"typescript","description":"Demonstrates importing the component, stylesheet, and types, then rendering a Lottie animation from a URL with basic controls."},"warnings":[{"fix":"Ensure your project uses Vue version ^3.4.0 or greater. Update Vue if necessary.","message":"Vue 3.4.0 or newer is required. Older Vue 3 versions are not supported due to internal API changes.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"For animations requiring After Effects expressions, import from the `/full` entry point: `import { VueLottiePlayer } from 'vue-lottie-player/full';`. Be aware that this build may violate strict CSP policies.","message":"The default build avoids `unsafe-eval` for CSP compliance, which means animations relying on After Effects expressions might not render correctly or at all. This is by design for security.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Create a client-side Nuxt plugin (e.g., `plugins/vue-lottie-player.client.ts`) and wrap component usage in `pages/*.vue` with `<ClientOnly>...</ClientOnly>`.","message":"When using `vue-lottie-player` in Nuxt 3, it must be registered as a client-side plugin and the component rendered within `<ClientOnly>` tags. `lottie-web` relies on browser APIs and cannot be run during SSR.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `import 'vue-lottie-player/style.css';` to your main application entry file or a global stylesheet.","message":"The component requires a stylesheet to be imported once in your application for proper rendering. Failing to do so may result in invisible or incorrectly sized players.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the Lottie player ref is initialized (`ref<VueLottiePlayerInstance | null>(null)`) and that methods are called only after the component is mounted or the `@ready` event has fired. Check that `player.value` is not null before calling methods.","cause":"Attempting to call imperative methods (play, pause, stop) on the Lottie player instance before it has fully initialized or if the ref is not correctly bound.","error":"TypeError: Cannot read properties of undefined (reading 'play')"},{"fix":"If using as a component, ensure `import { VueLottiePlayer } from 'vue-lottie-player';` is present in your script. If intended for global use, ensure `createApp(App).use(VueLottiePlayerPlugin).mount('#app');` is configured.","cause":"The `VueLottiePlayer` component was not imported or globally registered correctly.","error":"[Vue warn]: Failed to resolve component: VueLottiePlayer"},{"fix":"If your animation requires expressions, switch to the full build: `import { VueLottiePlayer } from 'vue-lottie-player/full';`. Otherwise, simplify your Lottie animation to avoid expressions.","cause":"This CSP error occurs when trying to play an animation that uses After Effects expressions with the default 'light-player' build, which disallows `unsafe-eval`.","error":"Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source..."}],"ecosystem":"npm"}