@aarsteinmedia/lottie-web

AM Lottie Web

A TypeScript fork of Airbnb's lottie-web, maintained for the Aarstein Media dotLottie player ecosystem.

Why this fork exists

• Safer expressions — After Effects expressions are evaluated without eval, which improves security and performance.
• SSR-friendly — Browser and Web API usage is guarded for Node and server rendering.
• Better errors — Failures surface through typed events instead of failing silently.

This package is primarily built for @aarsteinmedia/dotlottie-player and @aarsteinmedia/dotlottie-react. Other use cases are supported, but inherited from upstream lottie-web behavior.

Installation

pnpm add @aarsteinmedia/lottie-web

If you use the dotLottie entry point, install the peer dependency as well:

pnpm add fflate

Entry points

Import	Description
@aarsteinmedia/lottie-web	Full build: SVG + canvas renderers, effects, and expressions
@aarsteinmedia/lottie-web/light	SVG renderer only, no expressions
@aarsteinmedia/lottie-web/svg	SVG renderer with expressions
@aarsteinmedia/lottie-web/canvas	Canvas renderer with expressions
@aarsteinmedia/lottie-web/utils	Shared helpers and enums
@aarsteinmedia/lottie-web/dotlottie	dotLottie archive utilities

Basic usage

import lottie, { loadAnimation } from '@aarsteinmedia/lottie-web'
import type { AnimationItem } from '@aarsteinmedia/lottie-web'
import { PlayerEvent } from '@aarsteinmedia/lottie-web/utils'

const container = document.getElementById('animation')

const animation: AnimationItem = loadAnimation({
  container,
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: '/animations/hero.json',
})

animation.addEventListener(PlayerEvent.Complete, () => {
  console.log('Animation finished')
})

// Later
animation.destroy()

Inline animation data

import animationData from './animation.json'

const animation = loadAnimation({
  container: document.getElementById('animation'),
  renderer: 'svg',
  animationData,
  autoplay: false,
})

SVG-only bundle (smaller)

import lottie from '@aarsteinmedia/lottie-web/svg'

Events

AnimationItem extends a small event emitter. Common events include:

Event	When it fires
DOMLoaded	Animation is ready to play
enterFrame	Each rendered frame
complete	Playback reached the end
loopComplete	A loop iteration finished
configError	Invalid configuration or data
renderFrameError	A frame failed to render
destroy	Animation is being torn down

Import event names from @aarsteinmedia/lottie-web/utils:

import { PlayerEvent } from '@aarsteinmedia/lottie-web/utils'

animation.addEventListener(PlayerEvent.RenderFrameError, (event) => {
  console.error(event?.nativeError)
})

Development

pnpm install
pnpm dev        # preview player with live reload
pnpm lint       # eslint
pnpm test       # vitest
pnpm prod       # typecheck + production build
pnpm check      # lint, test, build, and verify version injection

Sample Lottie JSON files live in assets/ and are used by the preview app and test suite.

License

GPL-2.0-or-later. See upstream lottie-web licensing implications if you distribute combined or derivative works.