Vue Lottie Player

Common errors

• TypeError: Cannot read properties of undefined (reading 'play')

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

• [Vue warn]: Failed to resolve component: VueLottiePlayer

  cause The `VueLottiePlayer` component was not imported or globally registered correctly.
  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.

• Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source...

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

Warnings

• breaking Vue 3.4.0 or newer is required. Older Vue 3 versions are not supported due to internal API changes.
  Fix: Ensure your project uses Vue version ^3.4.0 or greater. Update Vue if necessary.
• gotcha 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.
  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.
• gotcha 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.
  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>`.
• gotcha 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.
  Fix: Add `import 'vue-lottie-player/style.css';` to your main application entry file or a global stylesheet.

Install

• npm install vue-lottie-player npm
• yarn add vue-lottie-player yarn
• pnpm add vue-lottie-player pnpm

Imports

• VueLottiePlayer
  wrong:

  import VueLottiePlayer from 'vue-lottie-player';

  correct:

  import { VueLottiePlayer } from 'vue-lottie-player';

  Main component for rendering Lottie animations. It is a named export.
• VueLottiePlayerPlugin

  import { VueLottiePlayerPlugin } from 'vue-lottie-player';

  Plugin for global registration in Vue applications.
• LottieUrlSource

  import type { LottieUrlSource } from 'vue-lottie-player';

  TypeScript type for defining URL-based animation sources.
• style.css

  import 'vue-lottie-player/style.css';

  Required stylesheet for the component to render correctly.

Quickstart

Demonstrates importing the component, stylesheet, and types, then rendering a Lottie animation from a URL with basic controls.

import { ref } from 'vue';
import type { AnimationItem } from 'lottie-web';
import 'vue-lottie-player/style.css';
import type { LottieUrlSource, LottieDataSource, VueLottiePlayerInstance } from 'vue-lottie-player';
import { VueLottiePlayer } from 'vue-lottie-player';

// Assuming you have an animation JSON file at /animations/sample-animation.json
// Or if using local data:
// import demoAnimationData from './assets/demo-animation.json';

const sourceUrl: LottieUrlSource = {
  kind: 'url',
  value: '/animations/sample-animation.json'
};

// Example for local JSON data:
// const sourceData: LottieDataSource = {
//   kind: 'data',
//   value: demoAnimationData
// };

const playerRef = ref<VueLottiePlayerInstance | null>(null);

function onReady(animation: AnimationItem) {
  console.log('Lottie animation is ready:', animation);
  animation.setSpeed(1.5);
}

function playAnimation() {
  playerRef.value?.play();
}

function pauseAnimation() {
  playerRef.value?.pause();
}

function stopAnimation() {
  playerRef.value?.stop();
}