Lottie-Web-Vue

Lottie-web-vue is an Airbnb Lottie-web component for Vue.js projects

📖 Documentation & live demos → garbit.github.io/lottie-web-vue

---

Airbnb's Lottie-web is a library for rendering animations exported from Adobe After Effects using the BodyMovin plugin. This package allows you to easily import animation files (available in .json format) into your Vue 3 project. TypeScript-ready and SSR-safe.

Quick start

npm install lottie-web-vue

<script setup lang="ts">
import { LottieAnimation } from "lottie-web-vue"
import WatermelonJSON from "./assets/watermelon.json"
</script>

<template>
  <LottieAnimation :animation-data="WatermelonJSON" :auto-play="true" :loop="true" />
</template>

Full guides — installation, props, events, playback methods, CDN usage, and interactive examples — live on the documentation site:

• Getting Started
• Props · Events · Methods
• CDN / UMD usage — ⚠️ since 3.0.0 you must load lottie-web before the UMD build
• Migrating from 2.x

Vue 2

Vue 2 projects should use v1.2.1 of the plugin (no longer maintained) — this package targets Vue 3:

npm install lottie-web-vue@1.2.1

Development

Requires Node >= 22 (see .nvmrc — nvm use picks it up). Dependency updates arrive weekly via Dependabot and are gated by the full CI suite.

npm install          # install dependencies
npm run dev          # demo app with hot reload
npm run test         # unit tests (Vitest + @vue/test-utils)
npm run test:watch   # unit tests in watch mode
npm run build        # build the library into dist/
npm run test:pack    # pack the tarball + install it into a throwaway consumer and verify it
npm run test:e2e     # browser E2E: playground app consuming the packed tarball (Playwright)
npm run verify       # everything: lint + typecheck + test + build + test:pack + test:e2e
npm run docs:dev     # documentation site (VitePress) with hot reload
npm run docs:build   # build the documentation site

First E2E run needs a browser: npx playwright install chromium.

The documentation site lives in docs/ and deploys to GitHub Pages automatically on push to main via the docs workflow.

Contributing

PRs welcome! Please make sure npm run verify passes locally. CI runs the same checks (lint, typecheck, unit tests, build, package smoke test, browser E2E) on every pull request.

Releasing (maintainers)

Releases are automated via GitHub Actions and published to npm with provenance:

1. Update the version: npm version 3.x.x --no-git-tag-version, update CHANGELOG.md, commit.
2. Verify locally: npm run verify.
3. Tag and push: git tag v3.x.x && git push --follow-tags.
4. The release workflow re-runs the full verification and publishes to npm. Prerelease tags (e.g. v3.1.0-rc.0) publish under the next dist-tag; stable tags publish as latest.

The workflow fails if the tag doesn't match package.json's version. To test a release end-to-end without touching latest, cut an -rc prerelease first and npm install lottie-web-vue@next in a scratch project.