Registry / web-framework / vue-lottie-player

vue-lottie-player

library2.0.2jsnpmunverified

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.

web-framework

npm install vue-lottie-player

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-LOTTIE-PLAYER

vue-lottie-player

web-frameworkjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueLottiePlayer

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

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

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(); }

Debug

Known issues

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

affects: <2.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

vuerequiredPeer dependency for Vue 3 component integration.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/turopoff/vue-lottie-player ↗

packagehttps://www.npmjs.com/package/vue-lottie-player ↗