DEV Community: Fazal Shah

How Lottie Animations Affect Core Web Vitals (And How to Fix Issues)

Fazal Shah — Mon, 08 Jun 2026 20:03:22 +0000

Lottie animations can hurt or help your Core Web Vitals depending on how you implement them. Here's what to measure, what to fix, and what's a non-issue.

The Three Risks

Lottie can impact three CWV metrics:

LCP (Largest Contentful Paint) — if a large Lottie animation is the hero element
CLS (Cumulative Layout Shift) — if the container doesn't have defined dimensions
INP (Interaction to Next Paint) — if too many animations are competing for CPU

TL;DR — none of these are inherent to Lottie. They're all implementation problems with known fixes.

LCP: Hero Animations

If your hero section is a Lottie animation, it may be the LCP element.

Problem: .json files are large and parse-heavy. A 150KB Lottie JSON blocks your LCP.

Fix 1: Convert to .lottie format

The same animation as .lottie is typically 30–40KB. Convert at IconKing. This is the single highest-impact change for Lottie performance.

# Before: hero.json = 145KB
# After: hero.lottie = 38KB

Fix 2: Preload the animation file

<link rel="preload" href="/animations/hero.lottie" as="fetch" crossorigin>

Fix 3: Don't make Lottie your LCP element

Place text content as the LCP element, with Lottie as a supporting illustration. A headline renders instantly; a Lottie file doesn't.

CLS: Undefined Container Dimensions

If you don't specify width and height, the container collapses to zero, then jumps to full size when Lottie loads. That's a CLS hit.

Problem:

// CLS: container has no dimensions
<DotLottieReact src="/hero.lottie" loop autoplay />

Fix:

// No CLS: dimensions defined
<DotLottieReact
  src="/hero.lottie"
  loop
  autoplay
  style={{ width: 400, height: 400 }}
/>

Or via CSS with aspect-ratio:

.lottie-container {
  width: 100%;
  aspect-ratio: 1 / 1;
  max-width: 400px;
}

Always define dimensions. This is the most common Lottie CLS cause.

INP: Too Many Concurrent Animations

Running 8+ Lottie animations simultaneously — common on product listing pages — blocks the main thread during input handling.

Fix: Intersection Observer

const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      const anim = animationMap.get(entry.target);
      if (!anim) return;
      entry.isIntersecting ? anim.play() : anim.pause();
    });
  },
  { threshold: 0.1 }
);

document.querySelectorAll('[data-lottie]').forEach(el => {
  observer.observe(el);
});

Only run animations that are visible. Pause everything else.

Measurement

Use Lighthouse before and after any Lottie optimization:

npx lighthouse https://yoursite.com --output json | grep -E "lcp|cls|inp"

Or use PageSpeed Insights to compare mobile vs desktop CWV scores.

A well-implemented Lottie animation (correct dimensions, .lottie format, lazy-loaded) should add zero CWV penalty.

Quick Checklist

[ ] All animations use .lottie format (convert at IconKing)
[ ] All containers have explicit width and height (no CLS)
[ ] Hero animation is not the LCP element (or is preloaded)
[ ] Animations off-screen are paused via IntersectionObserver
[ ] Max 6–8 animations active simultaneously on mobile
[ ] Animations destroyed when components unmount

Summary

The .lottie format is the most impactful single change — 75% file size reduction means better LCP and lower parse time. Explicit dimensions eliminate CLS. IntersectionObserver handles INP on animation-heavy pages. All three fixes together typically improve Lighthouse scores by 5–15 points on pages with hero animations.

Testing and Documenting Lottie Animations in Storybook

Fazal Shah — Mon, 08 Jun 2026 20:02:38 +0000

Lottie animations are hard to review in code review. Storybook fixes that — here's how to document, control, and visually test Lottie components.

Why Storybook for Lottie?

Animation components have state that's invisible in a code diff:

Does it loop?
Does it play at the right speed?
Do the colors match the brand?
Does it stop when it should?

Storybook makes all of this visible to designers and reviewers without running the full app.

Basic Lottie Story

// LottiePlayer.stories.jsx
import { DotLottieReact } from '@lottiefiles/dotlottie-react';
import loadingAnim from './assets/loading.lottie';
import successAnim from './assets/success.lottie';

export default {
  title: 'Animations/LottiePlayer',
  component: DotLottieReact,
  argTypes: {
    loop: { control: 'boolean' },
    autoplay: { control: 'boolean' },
  },
};

export const Loading = {
  args: {
    src: loadingAnim,
    loop: true,
    autoplay: true,
    style: { width: 120, height: 120 },
  },
};

export const Success = {
  args: {
    src: successAnim,
    loop: false,
    autoplay: true,
    style: { width: 120, height: 120 },
  },
};

Now any team member can open Storybook, see both animations playing, and toggle loop/autoplay in the Controls panel.

Wrapping in a Component Story

For a real AnimatedButton component:

// AnimatedButton.stories.jsx
import AnimatedButton from './AnimatedButton';

export default {
  title: 'Components/AnimatedButton',
  component: AnimatedButton,
};

export const Default = {};

export const Loading = {
  args: { state: 'loading' },
};

export const Success = {
  args: { state: 'success' },
};

export const Error = {
  args: { state: 'error' },
};

This documents all animation states in one place — designers can verify each one looks correct.

Adding Controls for Speed and Direction

export default {
  title: 'Animations/Showcase',
  argTypes: {
    speed: { control: { type: 'range', min: 0.25, max: 4, step: 0.25 } },
    loop: { control: 'boolean' },
    src: {
      control: 'select',
      options: ['loading', 'success', 'error', 'empty'],
      mapping: {
        loading: '/animations/loading.lottie',
        success: '/animations/success.lottie',
        error: '/animations/error.lottie',
        empty: '/animations/empty.lottie',
      },
    },
  },
};

Visual Regression Testing

With Chromatic or Percy, you can catch animation regressions:

import { composeStories } from '@storybook/react';
import * as stories from './LottiePlayer.stories';

const { Loading, Success } = composeStories(stories);

test('Loading animation renders', () => {
  const { container } = render(<Loading />);
  expect(container.querySelector('canvas')).toBeInTheDocument();
});

For true visual diff, Chromatic captures the first frame and diffs it on each deploy.

Preparing Animation Files

Before adding animations to Storybook:

Preview at IconKing to confirm all states render correctly
Edit colors to match your design system tokens
Convert to .lottie — smaller files = faster Storybook builds

IconKing converts .json → .lottie in the browser with no account.

Summary

Storybook + Lottie = a reviewable animation library. Designers can verify their animations render correctly, engineers can document all states, and Chromatic can catch regressions automatically. Set it up once and it pays off on every PR.

Using Lottie for Error States and Empty States: A UX Guide

Fazal Shah — Mon, 08 Jun 2026 20:01:55 +0000

Empty states and error messages are the most neglected parts of web UI. They're also some of the highest-leverage opportunities for Lottie animations.

Why These States Matter

Users encounter empty states and errors constantly:

Empty inbox after clearing all messages
Search with no results
404 page
Network error
No notifications
First-time user with no data yet

These moments are either dead ends or opportunities. A well-designed empty state with animation can guide users to the next action. A well-designed error can reduce frustration.

Empty State Anatomy

A good empty state has:

An illustration or animation (Lottie)
A clear headline explaining the situation
A call to action telling the user what to do next

function EmptyInbox() {
  return (
    <div style={{ textAlign: 'center', padding: '60px 20px' }}>
      <DotLottieReact
        src="/animations/empty-inbox.lottie"
        loop
        autoplay
        style={{ width: 180, height: 180, margin: '0 auto' }}
      />
      <h3>All caught up!</h3>
      <p>No new messages. Check back later.</p>
      <button>Compose New Message</button>
    </div>
  );
}

Empty Search Results

function NoSearchResults({ query }) {
  return (
    <div className="empty-state">
      <DotLottieReact
        src="/animations/no-results.lottie"
        loop
        autoplay
        style={{ width: 160, height: 160 }}
      />
      <h3>No results for "{query}"</h3>
      <p>Try different keywords or check your spelling</p>
    </div>
  );
}

Network Error State

function NetworkError({ onRetry }) {
  return (
    <div className="error-state">
      <DotLottieReact
        src="/animations/connection-error.lottie"
        loop={false}
        autoplay
        style={{ width: 140, height: 140 }}
      />
      <h3>Connection lost</h3>
      <p>Check your internet connection and try again</p>
      <button onClick={onRetry}>Retry</button>
    </div>
  );
}

For error states, use loop={false} — you don't want an animated error looping indefinitely. Play it once, then show the static final frame.

404 Page

function NotFoundPage() {
  return (
    <div className="not-found">
      <DotLottieReact
        src="/animations/404.lottie"
        loop
        autoplay
        style={{ width: 300, height: 300 }}
      />
      <h1>Page not found</h1>
      <p>The page you're looking for doesn't exist.</p>
      <a href="/">Go home</a>
    </div>
  );
}

404 pages with good animation have lower bounce rates. Users are more likely to navigate back into your app rather than hitting Back.

First-Time User / Onboarding Empty State

function FirstTimeUser() {
  return (
    <div className="onboarding-empty">
      <DotLottieReact
        src="/animations/welcome.lottie"
        loop
        autoplay
        style={{ width: 200, height: 200 }}
      />
      <h2>Welcome to the app!</h2>
      <p>You haven't created anything yet. Start here.</p>
      <button className="primary">Create your first project</button>
    </div>
  );
}

The key difference between first-time empty state and ongoing empty state: the tone. First-time is welcoming and action-oriented; ongoing is neutral and helpful.

Matching Animations to Context

State	Animation Style	Loop?
Empty inbox	Light, cheerful	Yes
No search results	Neutral, searching	Yes
Network error	Concerned, brief	No
404 page	Playful, curious	Yes
Permission denied	Clear, instructive	No
Loading skeleton → empty	Smooth transition	No (play once)

Customizing Colors

Downloaded animations from LottieFiles will have generic colors. Edit them to match your brand using IconKing — open the .json file, click a color swatch, pick your brand color, download. No After Effects, no account required.

Convert to .lottie format at the same time — the file will be 75% smaller, which matters on slow connections where error states are more likely to appear.

Accessibility

Always pair animations with text. Screen readers don't read Lottie. Add an aria-label to the container:

<div role="img" aria-label="Empty inbox illustration">
  <DotLottieReact src="/animations/empty-inbox.lottie" loop autoplay />
</div>

For users who prefer reduced motion:

@media (prefers-reduced-motion: reduce) {
  canvas { display: none; }
  .static-fallback { display: block; }
}

Summary

Empty states and errors are worth investing in — users see them more than you expect. A 2-minute Lottie integration turns a dead end into a moment that either delights or guides. Start with your 404 page and work backward from there.

Lottie Animations for E-Commerce: Add to Cart, Success States, and Loading

Fazal Shah — Mon, 08 Jun 2026 20:01:11 +0000

E-commerce conversion depends on UI feedback. A loading spinner that disappears without confirmation feels broken. An "add to cart" with no visual response loses trust. Lottie solves both.

The Case for Lottie in E-Commerce

Three moments in the shopping flow benefit most from animation:

Add to cart — confirm the action worked
Checkout loading — reassure the user during payment processing
Order success — celebrate the conversion

Each of these currently lives as either a static icon, a CSS spinner, or nothing. Lottie upgrades all three in a way that's memorable and measurable (better feedback = fewer abandoned carts).

Add to Cart Animation

The key is: play the animation after the API confirms success, not when the button is clicked.

import { useState, useRef } from 'react';
import { DotLottieReact } from '@lottiefiles/dotlottie-react';

function AddToCartButton({ productId }) {
  const [state, setState] = useState('idle'); // idle | loading | success
  const lottieRef = useRef(null);

  const handleClick = async () => {
    setState('loading');
    try {
      await addToCart(productId);
      setState('success');
      setTimeout(() => setState('idle'), 2000);
    } catch {
      setState('idle');
    }
  };

  return (
    <button onClick={handleClick} disabled={state === 'loading'}>
      {state === 'idle' && 'Add to Cart'}
      {state === 'loading' && <span className="spinner" />}
      {state === 'success' && (
        <DotLottieReact
          ref={lottieRef}
          src="/animations/cart-success.lottie"
          autoplay
          loop={false}
          style={{ width: 24, height: 24 }}
        />
      )}
    </button>
  );
}

Payment Processing Loader

During payment, users are anxious. A subtle, looping animation is better than a static spinner — it signals active progress.

function PaymentProcessing({ isProcessing }) {
  if (!isProcessing) return null;

  return (
    <div className="payment-overlay">
      <DotLottieReact
        src="/animations/payment-processing.lottie"
        loop
        autoplay
        style={{ width: 120, height: 120 }}
      />
      <p>Processing your payment...</p>
    </div>
  );
}

Tips for payment loaders:

Use a calming, slow animation (not a fast spinner)
Add text — "Processing" is better than silent animation
Keep the overlay visible until you've confirmed the response from your payment processor

Order Success Animation

The order confirmation page is the highest-emotional moment in the funnel. A Lottie animation here has measurable impact on customer satisfaction scores.

function OrderSuccess({ orderNumber }) {
  return (
    <div className="success-page">
      <DotLottieReact
        src="/animations/order-success.lottie"
        autoplay
        loop={false}
        style={{ width: 200, height: 200 }}
      />
      <h1>Order Confirmed!</h1>
      <p>Order #{orderNumber}</p>
    </div>
  );
}

Empty Cart State

Instead of "Your cart is empty" as plain text:

function EmptyCart() {
  return (
    <div className="empty-cart">
      <DotLottieReact
        src="/animations/empty-cart.lottie"
        loop
        autoplay
        style={{ width: 160, height: 160 }}
      />
      <h2>Your cart is empty</h2>
      <a href="/shop">Continue Shopping</a>
    </div>
  );
}

Empty states with animation have higher re-engagement rates than static empty states.

Performance Checklist for E-Commerce

Use .lottie format — 75% smaller than .json, convert at IconKing
Lazy-load non-critical animations — the hero animation doesn't need to block checkout
Destroy after play — call destroy() on single-play animations after complete event
Match brand colors — edit Lottie colors to your brand palette at IconKing
Test on mobile — run your Core Web Vitals before and after adding animations

Finding Good E-Commerce Animations

LottieFiles has a free library. Search for: "cart", "success", "checkmark", "payment", "delivery", "shopping".

Before using any file in production:

Preview at IconKing to confirm it renders correctly
Edit colors to match your brand
Convert to .lottie for production

The whole workflow takes under 5 minutes per animation.

Summary

Moment	Animation Type	Key Rule
Add to cart	Short success animation	Play AFTER API confirms
Payment loading	Looping calm animation	Show until payment confirmed
Order success	Celebratory one-shot	Loop: false, play once
Empty cart	Subtle looping illustration	Encourage action nearby

GSAP vs Lottie: Choosing the Right Animation Tool

Fazal Shah — Mon, 08 Jun 2026 20:00:27 +0000

GSAP and Lottie are both excellent animation tools, but they solve different problems. Here's how to decide which one to reach for — and when to use both.

The Core Difference

GSAP animates DOM elements you create with code. You define what moves where, and GSAP handles the timing and easing.

Lottie plays back animations created in After Effects (or similar tools). Your designer defines what happens; Lottie renders it exactly as designed.

When to Use GSAP

UI transitions: page transitions, accordion opens/closes, element reveals
Scroll-driven animations: parallax, sticky elements, reveal-on-scroll
Dynamic data visualization: animating charts, counters, progress bars with real values
Interactive animations: reactions to user input that are hard to pre-define
When you have no designer: building animations entirely in code

// GSAP example: animate an element based on user interaction
import gsap from 'gsap';

button.addEventListener('click', () => {
  gsap.to('.card', { 
    scale: 1.05, 
    duration: 0.2, 
    ease: 'back.out(1.7)',
    yoyo: true,
    repeat: 1
  });
});

When to Use Lottie

Brand animations: logos, mascots, illustrations — designed by someone who knows After Effects
Icon animations: animated checkmarks, loading spinners, hover states
Onboarding flows: multi-scene character animations
Empty states / error states: illustrated feedback
When a designer owns the animation: you want pixel-perfect rendering of their work

// Lottie example: designer-created animation, zero code for the animation itself
import { DotLottieReact } from '@lottiefiles/dotlottie-react';
import successAnim from './success.lottie'; // ← designer made this

<DotLottieReact src={successAnim} autoplay loop={false} />

File Size Comparison

Format	Typical Size	Notes
GSAP bundle	33KB (core)	Code only, no asset file
Lottie JSON	10–150KB	Depends on animation complexity
dotLottie (.lottie)	3–40KB	~75% smaller than JSON
GIF equivalent	80–500KB	For comparison

GSAP has no animation asset file — the animation is in your code. Lottie ships a separate asset file per animation.

Using Both Together

The real power comes from combining them:

// Use GSAP to control WHEN Lottie plays
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import lottie from 'lottie-web';

const anim = lottie.loadAnimation({
  container: document.getElementById('hero-lottie'),
  renderer: 'svg',
  loop: false,
  autoplay: false,
  path: '/animations/hero.json',
});

// Play the Lottie animation when user scrolls to it
ScrollTrigger.create({
  trigger: '#hero-lottie',
  start: 'top 80%',
  onEnter: () => anim.play(),
  onLeaveBack: () => anim.stop(),
});

GSAP handles the scroll logic; Lottie renders the designer's work.

Practical Decision Matrix

Situation	Use
Animating a div's position/opacity	GSAP
Playing a designer-made loading spinner	Lottie
Scroll-triggered section reveals	GSAP
Animated logo or mascot	Lottie
Counter animation (0 → 1,234)	GSAP
Animated empty state illustration	Lottie
Draggable, physics-based UI	GSAP
Branded animated icons	Lottie

Preparing Lottie Files

Before integrating any Lottie file, preview it at IconKing — you can check that it renders correctly, edit colors to match your brand, and convert from .json to .lottie (75% smaller). No account required.

Summary

Use GSAP when you're building the animation in code. Use Lottie when a designer made the animation in After Effects. Use both when you need scroll/interaction triggers around designer-made content.

Using Lottie Animations in Electron Desktop Apps

Fazal Shah — Mon, 08 Jun 2026 19:59:44 +0000

Lottie works in Electron's renderer process exactly like it does in a browser. Here's how to integrate it properly, including file serving, IPC patterns, and performance considerations.

Why Lottie in Electron?

Desktop apps built with Electron often use simple CSS animations or static images for UI feedback. Lottie gives you After Effects-quality animations at a fraction of the file size — loading states, onboarding illustrations, success/error feedback, and empty states all benefit from it.

The key advantage in Electron: you're serving files locally, so there's no network latency. A .lottie file loads instantly from the app bundle.

Setup

npm install @lottiefiles/dotlottie-web
# or if using React in renderer:
npm install @lottiefiles/dotlottie-react

Place animation files in your renderer's public/assets directory.

Basic Integration (Vanilla JS Renderer)

In your renderer process HTML or JS:

const { DotLottie } = require('@lottiefiles/dotlottie-web');
// or if using ES modules:
import { DotLottie } from '@lottiefiles/dotlottie-web';

const canvas = document.getElementById('lottie-canvas');
const anim = new DotLottie({
  canvas,
  src: './assets/animations/loading.lottie',
  loop: true,
  autoplay: true,
});

<canvas id="lottie-canvas" width="120" height="120"></canvas>

Use relative paths for local files — Electron serves renderer files from the app directory.

React Renderer Integration

import { DotLottieReact } from '@lottiefiles/dotlottie-react';

function LoadingState() {
  return (
    <DotLottieReact
      src="./assets/animations/loading.lottie"
      loop
      autoplay
      style={{ width: 120, height: 120 }}
    />
  );
}

For paths in Electron + React (webpack/vite), import the file directly:

import loadingLottie from './assets/loading.lottie';

<DotLottieReact src={loadingLottie} loop autoplay />

This lets the bundler handle the path correctly across dev and production builds.

Preloading Animations

For animations that need to play immediately (like a splash screen), preload in the main process:

// main.js
const { app, BrowserWindow } = require('electron');
const path = require('path');
const fs = require('fs');

app.whenReady().then(() => {
  const win = new BrowserWindow({ width: 800, height: 600 });

  // Preload the animation file
  const animPath = path.join(__dirname, 'renderer/assets/loading.lottie');
  const animData = fs.readFileSync(animPath);

  win.webContents.on('did-finish-load', () => {
    // Send animation data via IPC if needed
    win.webContents.send('animation-data', animData.toString('base64'));
  });

  win.loadFile('renderer/index.html');
});

IPC-Triggered Animations

A common pattern is triggering animations from main process events:

// renderer.js
const { ipcRenderer } = require('electron');
const { DotLottie } = require('@lottiefiles/dotlottie-web');

let anim = null;

ipcRenderer.on('show-progress', () => {
  const canvas = document.getElementById('progress-canvas');
  canvas.style.display = 'block';
  anim = new DotLottie({ canvas, src: './assets/progress.lottie', loop: true, autoplay: true });
});

ipcRenderer.on('hide-progress', () => {
  anim?.destroy();
  anim = null;
  document.getElementById('progress-canvas').style.display = 'none';
});

// main.js - during a long operation
win.webContents.send('show-progress');
await performLongOperation();
win.webContents.send('hide-progress');

Performance Notes

Electron apps often run on lower-powered machines. A few rules:

Use .lottie format (75% smaller than .json) — less memory at load
Destroy animations when windows are hidden: listen to app.on('browser-window-blur')
Avoid running animations in hidden/background windows
Prefer canvas renderer for complex animations, SVG for simple ones

Preparing Files

Get .lottie files from IconKing — paste your .json, edit colors to match your app's theme, and download as .lottie. No account needed, runs in the browser.

Distribution

Animation files in Electron need to be included in your build. In electron-builder:

{
  "build": {
    "extraResources": [
      { "from": "renderer/assets/animations/", "to": "animations/" }
    ]
  }
}

Then access them at runtime:

const path = require('path');
const animPath = path.join(process.resourcesPath, 'animations/loading.lottie');

Lottie Animations in Solid.js: A Complete Guide

Fazal Shah — Mon, 08 Jun 2026 19:59:00 +0000

SolidJS's fine-grained reactivity pairs well with Lottie's programmatic control API. Here's how to integrate them cleanly.

Setup

npm create solid@latest my-app
cd my-app
npm install @lottiefiles/dotlottie-web

Basic Component

import { onMount, onCleanup } from 'solid-js';
import { DotLottie } from '@lottiefiles/dotlottie-web';

function LottiePlayer({ src, loop = true, autoplay = true }) {
  let canvasRef;
  let dotLottie;

  onMount(() => {
    dotLottie = new DotLottie({
      canvas: canvasRef,
      src,
      loop,
      autoplay,
    });
  });

  onCleanup(() => {
    dotLottie?.destroy();
  });

  return <canvas ref={canvasRef} width="200" height="200" />;
}

export default LottiePlayer;

onMount and onCleanup replace React's useEffect with cleanup return. In SolidJS, refs are assigned directly — no useRef.

Reactive Controls

SolidJS signals integrate naturally with Lottie's playback API:

import { createSignal, onMount, onCleanup } from 'solid-js';
import { DotLottie } from '@lottiefiles/dotlottie-web';

function InteractiveLottie({ src }) {
  let canvasRef;
  let dotLottie;
  const [playing, setPlaying] = createSignal(true);
  const [speed, setSpeed] = createSignal(1);

  onMount(() => {
    dotLottie = new DotLottie({
      canvas: canvasRef,
      src,
      loop: true,
      autoplay: true,
    });
  });

  const togglePlay = () => {
    if (playing()) {
      dotLottie.pause();
    } else {
      dotLottie.play();
    }
    setPlaying(p => !p);
  };

  const changeSpeed = (newSpeed) => {
    dotLottie.setSpeed(newSpeed);
    setSpeed(newSpeed);
  };

  onCleanup(() => dotLottie?.destroy());

  return (
    <div>
      <canvas ref={canvasRef} width="200" height="200" />
      <button onClick={togglePlay}>{playing() ? 'Pause' : 'Play'}</button>
      <input
        type="range"
        min="0.5"
        max="3"
        step="0.5"
        value={speed()}
        onInput={(e) => changeSpeed(Number(e.target.value))}
      />
      <span>{speed()}x</span>
    </div>
  );
}

Using lottie-web (SVG Renderer)

If you prefer SVG rendering or need addValueCallback for color changes:

npm install lottie-web

import lottie from 'lottie-web';
import { onMount, onCleanup } from 'solid-js';

function LottieSVG({ path }) {
  let containerRef;
  let anim;

  onMount(() => {
    anim = lottie.loadAnimation({
      container: containerRef,
      renderer: 'svg',
      loop: true,
      autoplay: true,
      path,
    });
  });

  onCleanup(() => anim?.destroy());

  return <div ref={containerRef} style={{ width: '200px', height: '200px' }} />;
}

Lazy Loading

For animations below the fold, use an Intersection Observer:

import { createSignal, onMount, onCleanup } from 'solid-js';
import { DotLottie } from '@lottiefiles/dotlottie-web';

function LazyLottie({ src }) {
  let canvasRef;
  let wrapperRef;
  let dotLottie;
  const [loaded, setLoaded] = createSignal(false);

  onMount(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting && !loaded()) {
          setLoaded(true);
          dotLottie = new DotLottie({
            canvas: canvasRef,
            src,
            loop: true,
            autoplay: true,
          });
          observer.disconnect();
        }
      },
      { threshold: 0.1 }
    );
    observer.observe(wrapperRef);
    onCleanup(() => observer.disconnect());
  });

  onCleanup(() => dotLottie?.destroy());

  return (
    <div ref={wrapperRef} style={{ width: '200px', height: '200px' }}>
      {loaded() && <canvas ref={canvasRef} width="200" height="200" />}
    </div>
  );
}

Preparing Animation Files

Before integrating:

Preview at IconKing — check colors and bounds
Edit colors directly in the browser — no After Effects needed
Convert .json → .lottie at IconKing — saves ~75% file size

The .lottie format is the right choice for SolidJS projects targeting performance metrics.

Summary

Pattern	SolidJS API	Notes
Mount animation	`onMount`	Runs after DOM is ready
Cleanup	`onCleanup`	Destroy to prevent memory leaks
Refs	`let ref; <div ref={ref}`	Direct assignment, no `useRef`
Reactive state	`createSignal`	Connect to Lottie playback API

Adding Lottie Animations to Alpine.js Projects

Fazal Shah — Mon, 08 Jun 2026 19:58:17 +0000

Lottie animations work naturally with Alpine.js — here's a complete integration guide with x-data, x-init, and interactive controls.

Why Alpine.js + Lottie?

Alpine.js and Lottie are a natural pairing: both are lightweight, both work without a build step, and both excel at progressive enhancement. If you're building a page with Alpine.js and want animations that look like they cost $50k to produce, Lottie delivers them in a 10KB file.

Before touching any code, preview and edit your animation at IconKing — it lets you change colors and convert .json to .lottie without any account.

Setup (No Build Step)

<!-- Alpine.js CDN -->
<script src="https://unpkg.com/alpinejs@3" defer></script>
<!-- lottie-web CDN -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>

That's all the setup you need.

Basic Integration with x-init

<div
  x-data="{ anim: null }"
  x-init="
    anim = lottie.loadAnimation({
      container: $el,
      renderer: 'svg',
      loop: true,
      autoplay: true,
      path: '/animations/hero.json'
    })
  "
  style="width: 200px; height: 200px;"
></div>

x-init fires after Alpine initializes the component. $el refers to the root element — no need for a separate document.getElementById.

Interactive Controls

<div x-data="{
  anim: null,
  playing: true,
  init() {
    this.anim = lottie.loadAnimation({
      container: this.$refs.lottieContainer,
      renderer: 'svg',
      loop: true,
      autoplay: true,
      path: '/animations/loader.json'
    });
  },
  toggle() {
    this.playing ? this.anim.pause() : this.anim.play();
    this.playing = !this.playing;
  }
}">
  <div x-ref="lottieContainer" style="width: 150px; height: 150px;"></div>
  <button @click="toggle()" x-text="playing ? 'Pause' : 'Play'"></button>
</div>

Key pattern: use x-ref instead of $el when the container is a child element rather than the root.

Hover-Triggered Animation

<div x-data="{
  anim: null,
  init() {
    this.anim = lottie.loadAnimation({
      container: this.$refs.icon,
      renderer: 'svg',
      loop: false,
      autoplay: false,
      path: '/animations/hover-icon.json'
    });
  }
}"
@mouseenter="anim.play()"
@mouseleave="anim.stop()"
style="display: inline-block; cursor: pointer;">
  <div x-ref="icon" style="width: 40px; height: 40px;"></div>
</div>

Loading State Pattern

A common pattern is showing a Lottie loader while data fetches:

<div x-data="{
  loading: true,
  data: null,
  lottieAnim: null,
  async init() {
    this.lottieAnim = lottie.loadAnimation({
      container: this.$refs.loader,
      renderer: 'svg',
      loop: true,
      autoplay: true,
      path: '/animations/loading.json'
    });
    this.data = await fetch('/api/data').then(r => r.json());
    this.loading = false;
    this.lottieAnim.destroy();
  }
}">
  <div x-show="loading" x-ref="loader" style="width: 80px; height: 80px;"></div>
  <div x-show="!loading">
    <p x-text="data?.message"></p>
  </div>
</div>

Using dotLottie Format

The .lottie format is ~75% smaller. To use it with Alpine.js, swap lottie-web for dotlottie-web:

<script type="module">
  import { DotLottie } from 'https://esm.sh/@lottiefiles/dotlottie-web';

  document.addEventListener('alpine:init', () => {
    Alpine.data('lottiePlayer', () => ({
      dotLottie: null,
      init() {
        this.dotLottie = new DotLottie({
          canvas: this.$refs.canvas,
          src: '/animations/hero.lottie',
          loop: true,
          autoplay: true,
        });
      },
      destroy() {
        this.dotLottie?.destroy();
      }
    }));
  });
</script>

<div x-data="lottiePlayer" x-init="init()" @alpine:destroyed="destroy()">
  <canvas x-ref="canvas" width="200" height="200"></canvas>
</div>

Note: dotlottie-web requires a <canvas> element, not a <div>.

Cleanup on Component Destroy

Alpine doesn't automatically clean up Lottie instances. Use the destroy magic event:

<div x-data="{ anim: null }"
     x-init="anim = lottie.loadAnimation({ container: $el, loop: true, autoplay: true, path: '/anim.json', renderer: 'svg' })"
     @alpine:destroyed="anim?.destroy()">
</div>

Without this, animations keep running in memory even after the element is removed from the DOM.

Workflow

Get .json from LottieFiles or your designer
Preview and edit colors at IconKing
Convert to .lottie at IconKing for smaller files
Add lottie-web via CDN (or dotlottie-web for .lottie format)
Wire up with x-init and x-ref

Alpine.js + Lottie gives you polished animations without a build pipeline. Start with a loading spinner and go from there.

How to Use Lottie Animations in Vue.js (2025 Guide)

Fazal Shah — Mon, 08 Jun 2026 19:27:35 +0000

Lottie animations are the fastest way to add high-quality motion to a Vue.js app. This guide covers setup, playback control, and integration using vue3-lottie â€” the most actively maintained Vue 3 Lottie wrapper.

Why Lottie in Vue?

No GIF overhead â€” Lottie files are vector-based JSON, typically under 50KB
Programmatic control â€” play, pause, loop, seek, speed â€” all reactive
Easy theming â€” change colors at runtime without touching the source file
Vue 3 + Composition API friendly â€” vue3-lottie exposes a clean ref-based API

Step 0: Preview Your Animation First

Before adding any Lottie file to your project, open it in IconKing:

See exactly how it looks (colors, timing, layer structure)
Edit colors to match your design system
Convert .json â†’ .lottie format (75% smaller file size)
Catch broken layers before they surface in your Vue app

No account needed. Drop the file, inspect, adjust, download.

Step 1: Install vue3-lottie

npm install vue3-lottie

vue3-lottie uses lottie-web under the hood and is built for Vue 3 with full TypeScript support.

Step 2: Register the Component

Global registration (recommended for multiple uses)

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import Vue3Lottie from 'vue3-lottie'

createApp(App)
  .use(Vue3Lottie)
  .mount('#app')

Local registration

<script setup>
import { Vue3Lottie } from 'vue3-lottie'
</script>

Step 3: Basic Usage

<script setup>
import LoadingAnimation from '@/assets/loading.json'
</script>

<template>
  <Vue3Lottie
    :animationData="LoadingAnimation"
    :height="200"
    :width="200"
  />
</template>

That's the minimum setup â€” animationData accepts the imported JSON object directly. The animation plays and loops by default.

Using a URL Instead of a Local File

<template>
  <Vue3Lottie
    animationLink="https://assets10.lottiefiles.com/packages/lf20_example.json"
    :height="200"
    :width="200"
  />
</template>

Loop Control

<template>
  <!-- Loop forever (default) -->
  <Vue3Lottie :animationData="anim" :loop="true" />

  <!-- Play once -->
  <Vue3Lottie :animationData="anim" :loop="false" />

  <!-- Loop 3 times -->
  <Vue3Lottie :animationData="anim" :loop="3" />
</template>

Speed Control

<template>
  <!-- Half speed -->
  <Vue3Lottie :animationData="anim" :speed="0.5" />

  <!-- Double speed -->
  <Vue3Lottie :animationData="anim" :speed="2" />
</template>

Programmatic Playback with `ref`

<script setup>
import { ref } from 'vue'
import SuccessAnimation from '@/assets/success.json'

const lottieRef = ref(null)

function play() {
  lottieRef.value.play()
}
function pause() {
  lottieRef.value.pause()
}
function stop() {
  lottieRef.value.stop()
}
</script>

<template>
  <Vue3Lottie
    ref="lottieRef"
    :animationData="SuccessAnimation"
    :autoPlay="false"
    :loop="false"
  />

  <button @click="play">Play</button>
  <button @click="pause">Pause</button>
  <button @click="stop">Stop</button>
</template>

Listening for Events

<template>
  <Vue3Lottie
    :animationData="anim"
    :loop="false"
    @onComplete="handleComplete"
    @onLoopComplete="handleLoopComplete"
    @onEnterFrame="handleFrame"
  />
</template>

<script setup>
function handleComplete() {
  console.log('Animation finished')
}
function handleLoopComplete() {
  console.log('One loop completed')
}
function handleFrame(event) {
  // event.currentTime â€” current frame
}
</script>

Play a Specific Segment

<script setup>
import { ref } from 'vue'
import anim from '@/assets/animation.json'

const lottieRef = ref(null)

// Play frames 0â€“30 only
function playSegment() {
  lottieRef.value.playSegments([0, 30], true)
}
</script>

<template>
  <Vue3Lottie ref="lottieRef" :animationData="anim" :autoPlay="false" />
  <button @click="playSegment">Play intro only</button>
</template>

Using dotLottie (.lottie) Format

.lottie files are ~75% smaller than .json. To use them in Vue 3, switch to @lottiefiles/dotlottie-vue:

npm install @lottiefiles/dotlottie-vue

<script setup>
import { DotLottieVue } from '@lottiefiles/dotlottie-vue'
</script>

<template>
  <DotLottieVue
    src="/animations/loading.lottie"
    :loop="true"
    :autoplay="true"
    style="width: 200px; height: 200px"
  />
</template>

To convert your .json file to .lottie, use IconKing â€” drop the file, click convert, download.

Reactive Animation Switching

Swap animations on user action using Vue's reactive data:

<script setup>
import { ref } from 'vue'
import IdleAnim from '@/assets/idle.json'
import SuccessAnim from '@/assets/success.json'

const currentAnim = ref(IdleAnim)
const isSuccess = ref(false)

function triggerSuccess() {
  isSuccess.value = true
  currentAnim.value = SuccessAnim
}
</script>

<template>
  <Vue3Lottie :animationData="currentAnim" :key="isSuccess" :loop="false" />
  <button @click="triggerSuccess">Trigger</button>
</template>

The :key binding forces the component to remount when the animation changes â€” important for resetting state.

Performance Tips

1. Pause when not visible

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

const lottieRef = ref(null)

const observer = new IntersectionObserver(([entry]) => {
  if (lottieRef.value) {
    entry.isIntersecting
      ? lottieRef.value.play()
      : lottieRef.value.pause()
  }
})

onMounted(() => {
  observer.observe(lottieRef.value.$el)
})

onUnmounted(() => {
  observer.disconnect()
})
</script>

<template>
  <Vue3Lottie ref="lottieRef" :animationData="anim" />
</template>

2. Use .lottie format

Smaller files = faster initial page load. Convert at IconKing.

3. Lazy load animations

<script setup>
import { ref, defineAsyncComponent } from 'vue'
import { Vue3Lottie } from 'vue3-lottie'

const animData = ref(null)

// Only fetch when needed
async function loadAnim() {
  const module = await import('@/assets/heavy-animation.json')
  animData.value = module.default
}
</script>

<template>
  <button @click="loadAnim">Load Animation</button>
  <Vue3Lottie v-if="animData" :animationData="animData" />
</template>

Complete Example: Loading State

<script setup>
import { ref } from 'vue'
import { Vue3Lottie } from 'vue3-lottie'
import LoadingAnim from '@/assets/loading.json'
import SuccessAnim from '@/assets/success.json'

const status = ref('idle') // 'idle' | 'loading' | 'success'

async function fetchData() {
  status.value = 'loading'

  try {
    await new Promise(resolve => setTimeout(resolve, 2000)) // simulate API call
    status.value = 'success'
  } catch {
    status.value = 'idle'
  }
}
</script>

<template>
  <button @click="fetchData" :disabled="status === 'loading'">
    Fetch Data
  </button>

  <Vue3Lottie
    v-if="status === 'loading'"
    :animationData="LoadingAnim"
    :loop="true"
    :height="150"
    :width="150"
  />

  <Vue3Lottie
    v-if="status === 'success'"
    :animationData="SuccessAnim"
    :loop="false"
    :height="150"
    :width="150"
    @onComplete="() => status = 'idle'"
  />
</template>

Common Issues

Animation not showing

Check that animationData is the parsed JSON object, not a string path
If using a URL, check for CORS issues on the server hosting the file

Animation resets unexpectedly

If the parent component re-renders, vue3-lottie may remount. Use :key intentionally and avoid passing unstable references as props.

Wrong colors on screen

Preview in IconKing first. If it looks correct there, the issue is with how the JSON was generated (check your After Effects export settings).

Finding Lottie Files for Vue

LottieFiles â€” large free library
IconKing â€” preview any file before using it, edit colors to match your Vue app's design system, convert formats

Always preview before committing to a file. What looks good in a desktop browser might clip or scale unexpectedly at mobile breakpoints â€” catch it in IconKing first.

Summary

Install vue3-lottie (Vue 3) or @lottiefiles/dotlottie-vue for .lottie files
Import your animation JSON and pass it via :animationData
Use :loop, :speed, :autoPlay props for basic control
Use ref + lottieRef.value.play() / .pause() for programmatic control
Listen to @onComplete to chain animations or trigger UI state
Convert to .lottie at IconKing for smaller bundle size
Pause off-screen animations with IntersectionObserver

dotLottie vs Lottie JSON: Which Should You Use in 2025?

Fazal Shah — Mon, 08 Jun 2026 19:26:52 +0000

Two formats exist for Lottie animations: the original .json (Lottie JSON) and the newer .lottie (dotLottie). They render identically in the browser â€” but one is dramatically smaller. Here's when to use each, and how to switch.

TL;DR

.json â€” use when maximum tooling compatibility matters (older projects, plugins that don't support dotLottie yet)
.lottie â€” use for everything else. 75% smaller, faster, supports multiple animations per file

What Is Lottie JSON?

.json is the original format, introduced by Airbnb's Bodymovin After Effects plugin in 2015. It's plain text JSON describing every layer, shape, keyframe, and property in the animation.

Example size: A 3-second loading spinner â†’ ~25KB

Because it's plain JSON:

Human-readable
Universal support across all Lottie libraries
Can be edited with a text editor or a tool like IconKing

What Is dotLottie (.lottie)?

.lottie is a ZIP archive (renamed) containing the Lottie JSON plus any assets (images, fonts). It was introduced by LottieFiles in 2022.

Same 3-second spinner: ~7KB (72% smaller)

Additional features over .json:

Multiple animations in a single file (scenes)
Embedded fonts/images in one container
Metadata (author, description, version)
Background color and loop settings baked in

Size Comparison

These are real-world examples:

Animation	`.json`	`.lottie`	Savings
Loading spinner	24KB	6KB	75%
Success checkmark	18KB	5KB	72%
Hero illustration	145KB	38KB	74%
Icon set (5 icons)	92KB	24KB	74%

The compression is consistent regardless of animation complexity.

Converting Between Formats

IconKing converts .json â†”.lottie in the browser:

Go to iconking.net
Drop your file onto the page
Click the convert button
Download the new format

No account, no upload limit, fully client-side. The converted file is byte-for-byte identical in visual output to the original.

Library Support Comparison

Library	`.json`	`.lottie`
lottie-web	âœ…	âŒ
lottie-react	âœ…	âŒ
vue3-lottie	âœ…	âŒ
@lottiefiles/dotlottie-web	âœ…	âœ…
@lottiefiles/dotlottie-react	âœ…	âœ…
@lottiefiles/dotlottie-vue	âœ…	âœ…
lottie-android	âœ…	âœ… (v2.0+)
lottie-ios	âœ…	âœ… (v4.0+)

Key insight: To use .lottie on web, you need to switch from lottie-web/lottie-react to the @lottiefiles/dotlottie-* libraries. The switch is a one-time migration â€” APIs are similar.

Migrating: lottie-react â†’ dotlottie-react

Before (lottie-react, .json):

npm install lottie-react

import Lottie from 'lottie-react';
import animData from './animation.json';

<Lottie animationData={animData} loop autoplay />

After (@lottiefiles/dotlottie-react, .lottie):

npm uninstall lottie-react
npm install @lottiefiles/dotlottie-react

import { DotLottieReact } from '@lottiefiles/dotlottie-react';

<DotLottieReact
  src="/animations/animation.lottie"
  loop
  autoplay
/>

Key differences:

animationData prop â†’ src prop (URL string, not JSON object)
Place .lottie files in public/animations/ instead of bundling them

Migrating: Vue

Before (vue3-lottie, .json):

<Vue3Lottie :animationData="animData" />

After (@lottiefiles/dotlottie-vue, .lottie):

npm install @lottiefiles/dotlottie-vue

<DotLottieVue src="/animations/animation.lottie" :loop="true" :autoplay="true" />

Migrating: Vanilla JS

Before (lottie-web, .json):

lottie.loadAnimation({
  container: el,
  animationData: require('./animation.json'),
  renderer: 'svg'
});

After (@lottiefiles/dotlottie-web, .lottie):

npm install @lottiefiles/dotlottie-web

import { DotLottie } from '@lottiefiles/dotlottie-web';

const dotLottie = new DotLottie({
  canvas: document.getElementById('canvas'),  // Note: requires <canvas>, not <div>
  src: '/animations/animation.lottie',
  loop: true,
  autoplay: true,
});

One important difference: dotlottie-web requires a <canvas> element, not a <div>.

When to Stick With .json

You use lottie-web/lottie-react directly and don't want to swap libraries yet
Designer tools like Adobe After Effects + Bodymovin export .json natively; no friction
Older plugin ecosystem â€” some CMS plugins (WordPress Lottie plugins) only support .json
Programmatic manipulation â€” editing colors via addValueCallback on lottie-web works with .json; dotLottie has different APIs for this

When to Use .lottie

New projects â€” no legacy to worry about
Mobile apps â€” 75% smaller files = meaningful bandwidth savings on LTE/3G
Multiple animations â€” bundle a full icon set into one .lottie file
Core Web Vitals â€” smaller files = better LCP scores
CDN serving â€” less transfer cost

dotLottie Programmatic API

The @lottiefiles/dotlottie-web API is slightly different from lottie-web:

const dotLottie = new DotLottie({ canvas, src, loop: true, autoplay: true });

// Playback
dotLottie.play();
dotLottie.pause();
dotLottie.stop();
dotLottie.setSpeed(1.5);
dotLottie.setLoop(true);

// Events
dotLottie.addEventListener('play', () => console.log('playing'));
dotLottie.addEventListener('complete', () => console.log('done'));
dotLottie.addEventListener('frame', ({ currentFrame }) => {});

// Cleanup
dotLottie.destroy();

Multiple Animations in One .lottie File

This is the killer feature of dotLottie for icon sets:

const dotLottie = new DotLottie({
  canvas,
  src: '/animations/icons.lottie', // contains 10 icons
  loop: false,
  autoplay: false,
});

// Switch to a specific animation by name
dotLottie.loadAnimation({ animationId: 'icon-success' });
dotLottie.play();

Ship a full animated icon library as a single 30KB file instead of 10 separate 15KB files.

Workflow Recommendation

For new projects:

Get .json from LottieFiles or your designer
Preview and edit colors in IconKing
Convert to .lottie in IconKing
Install @lottiefiles/dotlottie-react (or vue/web)
Use src="/animations/file.lottie" â€” done

For existing projects:

Keep .json working (don't break things)
Convert each file to .lottie at IconKing
Migrate components one by one from lottie-react â†’ dotlottie-react
Remove lottie-react once fully migrated

Summary

	`.json`	`.lottie`
File size	Larger	~75% smaller
Web library	lottie-web, lottie-react	@lottiefiles/dotlottie-*
Compatibility	Universal	Growing (all major platforms)
Multiple animations	No	Yes
Editing tools	All Lottie tools	IconKing, LottieFiles
Best for	Legacy projects, CMS plugins	New projects, mobile, performance

If you're starting fresh: use .lottie. Convert existing files at IconKing when you're ready to migrate.

Lottie Animations: The Complete Beginner's Guide (2025)

Fazal Shah — Mon, 08 Jun 2026 19:26:09 +0000

Lottie animations are the fastest way to add professional motion to any app or website. This guide covers everything from what Lottie is to getting your first animation running in under 10 minutes.

What Is Lottie?

Lottie is an open-source animation format created by Airbnb in 2017. It renders Adobe After Effects animations natively in browsers and mobile apps â€” as smooth vectors, not GIFs or videos.

Why it's popular:

A 3-second loading spinner is typically 10â€“30KB as Lottie, vs 300KB+ as a GIF
Vector-based â€” looks sharp on any screen density (including 4K and Retina)
Scriptable â€” play, pause, loop, seek, change speed, change colors
Works in React, Vue, Angular, iOS, Android, Flutter, and plain HTML

Who made it possible: Lottie files are .json files exported from After Effects using a plugin called Bodymovin. In 2022, the newer .lottie (dotLottie) format was introduced â€” a compressed binary format that's 75% smaller.

Step 1: Find an Animation

Before writing any code, you need a Lottie file. The main sources:

LottieFiles â€” the largest free Lottie library. Search by keyword, download .json or .lottie.
IconScout â€” free and premium Lottie animations
Custom â€” have a designer export from After Effects using the Bodymovin plugin

Step 2: Preview Before Using

Don't skip this step. Always preview a Lottie file in IconKing before adding it to your project:

See exactly how it renders (colors, timing, bounds)
Edit colors to match your brand without touching After Effects
Convert .json â†’ .lottie format for 75% smaller file size
Check that all layers render correctly

Takes 30 seconds. Saves hours of debugging.

Step 3: Add It to Your Project

Plain HTML / Vanilla JS

<!-- Add the lottie-player web component -->
<script src="https://unpkg.com/@lottiefiles/lottie-player@latest/dist/lottie-player.js"></script>

<!-- Use it in your HTML -->
<lottie-player
  src="https://assets10.lottiefiles.com/packages/lf20_your-animation.json"
  background="transparent"
  speed="1"
  style="width: 300px; height: 300px;"
  loop
  autoplay>
</lottie-player>

Or use lottie-web directly:

<div id="animation"></div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>
<script>
  lottie.loadAnimation({
    container: document.getElementById('animation'),
    renderer: 'svg',
    loop: true,
    autoplay: true,
    path: '/animations/loading.json'
  });
</script>

React

npm install lottie-react

import Lottie from 'lottie-react';
import loadingAnimation from './loading.json';

export default function Loading() {
  return <Lottie animationData={loadingAnimation} loop={true} style={{ width: 200, height: 200 }} />;
}

Vue 3

npm install vue3-lottie

<script setup>
import animData from './animation.json'
</script>

<template>
  <Vue3Lottie :animationData="animData" :height="200" :width="200" />
</template>

The Two Lottie Formats: .json vs .lottie

	`.json` (Lottie JSON)	`.lottie` (dotLottie)
File size	Larger (text)	~75% smaller (compressed binary)
Browser support	Universal	Needs dotLottie library
Tooling	Universal	Growing (recommended for new projects)
Multiple animations	No	Yes (one file, multiple scenes)

Recommendation: Use .json for maximum compatibility. Use .lottie when file size matters (mobile apps, slow connections). Convert between formats at IconKing.

Key Concepts

Renderer

Lottie supports three renderers:

SVG (default for web) â€” best quality, most compatible
Canvas â€” faster for many simultaneous animations
HTML â€” CSS-based, limited feature support

For most projects, stick with SVG.

The `lottie-web` API

const anim = lottie.loadAnimation({
  container: document.getElementById('anim'),
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: '/animation.json'
});

// Control playback
anim.play();
anim.pause();
anim.stop();
anim.setSpeed(2);       // 2x speed
anim.setDirection(-1);  // reverse
anim.goToAndPlay(30);   // jump to frame 30 and play
anim.destroy();         // clean up

Events

anim.addEventListener('complete', () => {
  console.log('animation finished');
});

anim.addEventListener('loopComplete', () => {
  console.log('one loop done');
});

Changing Colors at Runtime

The easiest way to change Lottie colors without After Effects is IconKing â€” open the file, click a color swatch, change it, download.

For runtime color changes in code, use the addValueCallback API (lottie-web) or setValueProvider (lottie-ios). The approach varies by platform â€” see the platform-specific guides:

React â€” addValueCallback with KeyPath
iOS/Swift â€” setValueProvider
Android/Kotlin â€” addValueCallback with KeyPath

Performance Rules

Pause off-screen animations â€” running animations consume CPU/GPU even when not visible
Avoid 10+ simultaneous animations â€” especially on mobile
Use .lottie format â€” 75% smaller = faster load
Limit canvas size â€” don't render a 1000Ã—1000 animation in a 50Ã—50 box
Avoid After Effects effects that Lottie doesn't support â€” Gaussian blur, certain blend modes, 3D layers

What Lottie Does NOT Support

A few After Effects features don't translate to Lottie:

Raster images (sort of â€” can be embedded but increases file size dramatically)
3D layers
Some blend modes
Expressions that reference external data

If your animation uses these, check Lottie's supported features list before committing.

Common Beginner Mistakes

1. Not previewing first

Always open the file in IconKing before adding it to your code. A file that looks great in After Effects may have broken layers, wrong colors, or unexpected bounds in Lottie.

2. Using GIF instead of Lottie

GIFs are 10â€“30Ã— larger, not scalable, and have poor color support (256 colors max). There's almost never a reason to use GIF if you can use Lottie.

3. Forgetting to stop the animation

Every running animation consumes resources. Always stop or pause animations when they go off-screen.

4. Wrong file in res/raw/ (Android) or bundle (iOS)

The file must be copied to the right location. Use IconKing to verify the file is valid before debugging your build setup.

The Ecosystem

Tool	Purpose
LottieFiles	Find and share Lottie animations
IconKing	Preview, edit colors, convert formats
lottie-web	Web renderer (vanilla JS)
lottie-react	React wrapper
vue3-lottie	Vue 3 wrapper
lottie-android	Android renderer
lottie-ios	iOS renderer
lottie-flutter	Flutter renderer

Summary

Get a .json or .lottie file from LottieFiles or your designer
Preview and edit it at IconKing before writing code
Use the appropriate wrapper for your platform
Control playback with play(), pause(), stop(), setSpeed()
Listen to complete event to chain animations or trigger UI state
Convert to .lottie at IconKing for 75% smaller files
Always stop/pause animations when they go off-screen

How to Use Lottie Animations in Next.js (2025 Guide)

Fazal Shah — Mon, 08 Jun 2026 19:25:25 +0000

Lottie animations are the best way to ship high-quality motion in a Next.js app. This guide covers server-side rendering gotchas, client component setup, and performance optimization â€” all the things that trip people up when using lottie-react with Next.js's App Router.

The SSR Problem (and How to Solve It)

lottie-react uses browser APIs that don't exist in Node.js. If you import it in a Server Component or without proper guarding, you'll get:

ReferenceError: document is not defined

The fix: mark your animation component as a Client Component and/or use dynamic import with ssr: false.

Step 0: Preview Before You Build

Before adding any .json or .lottie file, preview it in IconKing:

See exact colors, timing, and layer structure
Edit colors to match your Tailwind/design system
Convert .json â†’ .lottie format (75% smaller)
Catch broken After Effects effects before runtime

Free, no login required.

Step 1: Install lottie-react

npm install lottie-react

Step 2: Create a Client Component

In Next.js App Router, create a dedicated client component for your animation:

// components/LottieAnimation.tsx
'use client'

import Lottie from 'lottie-react'
import loadingAnimation from '@/public/animations/loading.json'

export default function LoadingAnimation() {
  return (
    <Lottie
      animationData={loadingAnimation}
      loop={true}
      style={{ width: 200, height: 200 }}
    />
  )
}

Then use it anywhere â€” Server or Client Component:

// app/page.tsx (Server Component is fine)
import LoadingAnimation from '@/components/LottieAnimation'

export default function Page() {
  return (
    <main>
      <LoadingAnimation />
    </main>
  )
}

Step 3: Dynamic Import (Alternative Approach)

If you can't mark the component as 'use client', use next/dynamic with ssr: false:

// app/page.tsx
import dynamic from 'next/dynamic'

const LottieAnimation = dynamic(
  () => import('@/components/LottieAnimation'),
  { ssr: false }
)

export default function Page() {
  return <LottieAnimation />
}

Storing Animation Files

Two good options:

Option A: Import JSON directly (bundled)

import animationData from '@/public/animations/loading.json'
// or
import animationData from '@/animations/loading.json'

Option B: Fetch from /public at runtime

'use client'
import { useState, useEffect } from 'react'
import Lottie from 'lottie-react'

export default function LazyAnimation() {
  const [animData, setAnimData] = useState(null)

  useEffect(() => {
    fetch('/animations/loading.json')
      .then(r => r.json())
      .then(setAnimData)
  }, [])

  if (!animData) return null
  return <Lottie animationData={animData} loop />
}

Option B reduces initial bundle size â€” good for large or rarely-seen animations.

Loop and Autoplay

// Loop forever (default)
<Lottie animationData={anim} loop={true} />

// Play once
<Lottie animationData={anim} loop={false} />

// Loop N times â€” use onComplete + state

Programmatic Control with `lottieRef`

'use client'

import { useRef } from 'react'
import Lottie, { LottieRefCurrentProps } from 'lottie-react'
import anim from '@/public/animations/anim.json'

export default function ControlledAnimation() {
  const lottieRef = useRef<LottieRefCurrentProps>(null)

  return (
    <div>
      <Lottie
        lottieRef={lottieRef}
        animationData={anim}
        autoplay={false}
        loop={false}
      />
      <button onClick={() => lottieRef.current?.play()}>Play</button>
      <button onClick={() => lottieRef.current?.pause()}>Pause</button>
      <button onClick={() => lottieRef.current?.stop()}>Stop</button>
      <button onClick={() => lottieRef.current?.setSpeed(2)}>2x Speed</button>
    </div>
  )
}

Speed and Direction

lottieRef.current?.setSpeed(0.5)   // half speed
lottieRef.current?.setSpeed(2)     // double speed
lottieRef.current?.setDirection(1) // forward
lottieRef.current?.setDirection(-1) // reverse

Listening for Events

<Lottie
  animationData={anim}
  loop={false}
  onComplete={() => console.log('done')}
  onLoopComplete={() => console.log('loop done')}
  onEnterFrame={({ currentTime }) => console.log(currentTime)}
/>

Using dotLottie (.lottie) Format

For smaller files, use @lottiefiles/dotlottie-react:

npm install @lottiefiles/dotlottie-react

'use client'

import { DotLottieReact } from '@lottiefiles/dotlottie-react'

export default function DotLottieAnimation() {
  return (
    <DotLottieReact
      src="/animations/loading.lottie"
      loop
      autoplay
      style={{ width: 200, height: 200 }}
    />
  )
}

dotLottie files are ~75% smaller than JSON â€” significant for Core Web Vitals. Convert your .json to .lottie at IconKing.

Performance in Next.js

1. Use dotLottie format

75% smaller = faster LCP and better Lighthouse scores. Convert at IconKing.

2. Lazy load with dynamic import

const HeavyAnimation = dynamic(
  () => import('@/components/HeavyAnimation'),
  { ssr: false, loading: () => <div className="h-48 w-48 bg-gray-100 animate-pulse" /> }
)

3. Pause off-screen with IntersectionObserver

'use client'

import { useRef, useEffect } from 'react'
import Lottie, { LottieRefCurrentProps } from 'lottie-react'
import anim from '@/public/animations/anim.json'

export default function PausedWhenHidden() {
  const containerRef = useRef<HTMLDivElement>(null)
  const lottieRef = useRef<LottieRefCurrentProps>(null)

  useEffect(() => {
    const observer = new IntersectionObserver(([entry]) => {
      entry.isIntersecting
        ? lottieRef.current?.play()
        : lottieRef.current?.pause()
    })
    if (containerRef.current) observer.observe(containerRef.current)
    return () => observer.disconnect()
  }, [])

  return (
    <div ref={containerRef}>
      <Lottie lottieRef={lottieRef} animationData={anim} />
    </div>
  )
}

Complete Example: Form Submit Animation

'use client'

import { useState, useRef } from 'react'
import Lottie, { LottieRefCurrentProps } from 'lottie-react'
import loadingAnim from '@/public/animations/loading.json'
import successAnim from '@/public/animations/success.json'

type Status = 'idle' | 'loading' | 'success'

export default function SubmitForm() {
  const [status, setStatus] = useState<Status>('idle')
  const lottieRef = useRef<LottieRefCurrentProps>(null)

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    setStatus('loading')
    await new Promise(r => setTimeout(r, 2000)) // simulated API call
    setStatus('success')
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Your email" required />

      {status === 'idle' && (
        <button type="submit">Subscribe</button>
      )}

      {status === 'loading' && (
        <Lottie animationData={loadingAnim} loop style={{ width: 48, height: 48 }} />
      )}

      {status === 'success' && (
        <Lottie
          lottieRef={lottieRef}
          animationData={successAnim}
          loop={false}
          style={{ width: 48, height: 48 }}
          onComplete={() => setStatus('idle')}
        />
      )}
    </form>
  )
}

Common Issues in Next.js

`document is not defined`

You're importing lottie-react in a Server Component. Add 'use client' to the component file or use dynamic(() => import(...), { ssr: false }).

Hydration mismatch

The server renders nothing (or a placeholder), but the client renders the animation. Use a loading state or Suspense boundary to keep them in sync.

Animation file is too large

Switch to .lottie format. Convert at IconKing â€” files are typically 75% smaller.

Animation looks different in browser vs. preview

Open the file in IconKing â€” it's the authoritative preview for how the animation actually renders. If it looks wrong there, fix it at the source before debugging your Next.js setup.

Placing Animation Files in Next.js

Location	Use case
`public/animations/`	Fetched at runtime, not bundled
`src/animations/` or `src/assets/`	Imported and bundled with your JS

For frequently-used animations (loading spinners, button states), bundle them. For large or rarely-seen animations, serve from public/.

Summary

Mark Lottie components as 'use client' â€” they need browser APIs
Use dynamic(() => ..., { ssr: false }) as an alternative
Use lottieRef for programmatic play/pause/seek
Listen to onComplete for chaining state transitions
Switch to .lottie format at IconKing for 75% smaller files
Lazy load and pause off-screen for Core Web Vitals