Skip to content

dotLottie Grid Notes

LottieFiles' WebAssembly-powered player for `.lottie` archives and Lottie JSON animations, with official wrappers for React, Vue, Svelte and plain web canvas.

Grid NotesVersion 0.13.xMotionChecked 2026-11-04
Setup & agent config

Install and prerequisites

What your agent should install or configure before writing code with this pack.
Terminal
npm install @lottiefiles/dotlottie-react
Packages:@lottiefiles/dotlottie-react@lottiefiles/dotlottie-web

Requires React 16.8+ for @lottiefiles/dotlottie-react. The player renders into a <canvas> via a WebAssembly core.

Framework setup

Production-ready wiring for React 19, Next.js App Router and Tailwind CSS v4.

Client-only React player with pause and reduced-motion control

Keep DotLottieReact in a client component, check prefers-reduced-motion, and capture dotLottieRefCallback so users can pause looping animations.

components/lottie-figure.tsx
"use client";

import { useState } from "react";
import { DotLottieReact, type DotLottie } from "@lottiefiles/dotlottie-react";

export function LottieFigure({ src, label }: { src: string; label: string }) {
  const [player, setPlayer] = useState<DotLottie | null>(null);
  const [paused, setPaused] = useState(false);

  const toggle = () => {
    if (!player) return;
    if (paused) player.play();
    else player.pause();
    setPaused(!paused);
  };

  return (
    <figure aria-label={label} className="relative">
      <DotLottieReact src={src} loop autoplay dotLottieRefCallback={setPlayer} />
      <button type="button" onClick={toggle} className="text-xs underline">
        {paused ? "Play animation" : "Pause animation"}
      </button>
    </figure>
  );
}

Gotchas for agents

Real-world traps — version mismatches, licence boundaries, main-thread stalls and CSS layer rules — that trip AI agents up.
  1. WebAssembly loading and CSP

    @lottiefiles/dotlottie-web loads a .wasm binary at runtime. If your Content Security Policy restricts connect-src or wasm-unsafe-eval, host the WASM file locally and configure DotLottie.setWasmUrl('/dotlottie-player.wasm') before mounting.

  2. SSR and Next.js hydration

    DotLottieReact uses browser <canvas> and OffscreenCanvas APIs. Always mark wrapper components with "use client" and give the container explicit dimensions (aspect-ratio or fixed height) so the page does not shift (CLS) when the .lottie file finishes loading.

  3. Prefer .lottie over raw JSON

    .lottie archives bundle and compress animations, images and state machines into a fraction of the size of raw Lottie .json files.

Accessibility and reduced motion

How to keep animations and interactive components accessible across keyboard, screen readers and prefers-reduced-motion.

Reduced motion

Check window.matchMedia('(prefers-reduced-motion: reduce)').matches before setting autoplay={true}; when reduced motion is active, pass autoplay={false} and render a static representative frame.

Keyboard and screen readers

Because DotLottieReact renders to a <canvas>, screen readers see no internal text. Mark purely decorative animations aria-hidden="true", or wrap informative ones in <figure role="img" aria-label="..."> and provide a visible Pause button for any loop over 5 seconds.