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 with new Function instead of eval, which slightly improves security and performance. For untrusted input, however, /light is recommended.
• Economic imports – This package adheres to a modular design philosophy, and offers granular imports so that you don't get any unneeded bloat in your application – provided that you keep on reading.
• Better Canvas rendering – While Canvas rendering isn't as versatile as SVG rendering, it's more performant and more conducive to how visual elements are handled in most browsers. This fork has better better DPR handling and broader feature support for Canvas renderer.
• 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

Here is where reading this whole thing pays off. Remember what I said about modular design? Well, this is that.

| 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

pnpm dev expects a local assets/ directory of sample .json / .lottie files (this repo tracks a symlink to a sibling lottie-fixtures folder). Tests use fixtures under tests/lottie-fixtures/ and do not depend on assets/.

License

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