LottiePlayer

LottiePlayer component: render lightweight vector animations from Lottie JSON files with loop, autoplay, and speed control

Overview

LottiePlayer renders high-quality vector animations using the Lottie format. Lottie animations are scalable, small in file size, and can be exported directly from After Effects, making them perfect for loading states, success animations, and feature highlights.

Why Use LottiePlayer?

Scalable: Vector-based, looks crisp at any size
Lightweight: Much smaller than video or GIF (typically < 50KB)
Interactive: Can be controlled programmatically
Designer-friendly: Exported directly from After Effects
Performant: GPU-accelerated rendering

Installation

LottiePlayer requires the lottie-web peer dependency:

pnpm add lottie-web

npm install lottie-web

yarn add lottie-web

Basic Usage

import { LottiePlayer } from '@tour-kit/media'

export function SuccessAnimation() {
  return (
    <LottiePlayer
      src="/animations/success.json"
      alt="Success celebration animation"
      autoplay
      loop
    />
  )
}

Props

Prop

Type

Examples

Success Celebration

<LottiePlayer
  src="/animations/success-checkmark.json"
  alt="Success animation with checkmark"
  autoplay
  size="sm"
/>

Loading Spinner

<LottiePlayer
  src="/animations/loading-spinner.json"
  alt="Loading animation"
  autoplay
  loop
  size="sm"
/>

Error State

<LottiePlayer
  src="/animations/error-state.json"
  alt="Error notification animation"
  autoplay
  speed={0.8}
  size="md"
/>

Reversed Animation

Play animation in reverse for unique effects:

<LottiePlayer
  src="/animations/reveal.json"
  alt="Reverse reveal animation"
  autoplay
  direction={-1}
/>

Slow Motion

Slow down for dramatic effect:

<LottiePlayer
  src="/animations/celebration.json"
  alt="Celebration animation"
  autoplay
  speed={0.5}
  loop
/>

Custom Aspect Ratio

Wide animations for banners:

<LottiePlayer
  src="/animations/banner.json"
  alt="Banner animation"
  aspectRatio="21/9"
  size="full"
  autoplay
  loop
/>

Canvas Renderer

Use canvas for better performance with complex animations:

<LottiePlayer
  src="/animations/complex.json"
  alt="Complex particle animation"
  renderer="canvas"
  autoplay
  loop
/>

Reduced Motion Fallback

Show static image for motion-sensitive users:

<LottiePlayer
  src="/animations/animated-feature.json"
  alt="Feature showcase animation"
  reducedMotionFallback="/images/feature-static.svg"
  autoplay
  loop
/>

Event Callbacks

Track animation completion:

<LottiePlayer
  src="/animations/onboarding.json"
  alt="Onboarding animation"
  autoplay
  onComplete={() => {
    console.log('Animation finished')
    // Proceed to next step
  }}
/>

Advanced Configuration

LottieOptions

Fine-tune animation behavior with advanced options:

<LottiePlayer
  src="/animations/complex.json"
  alt="Advanced animation"
  lottieOptions={{
    renderer: 'svg',
    loop: true,
    autoplay: true,
    rendererSettings: {
      preserveAspectRatio: 'xMidYMid slice',
      progressiveLoad: true,
      hideOnTransparent: true
    }
  }}
/>

Programmatic Control

For advanced use cases, use the headless API:

import { MediaHeadless } from '@tour-kit/media'

<MediaHeadless src="/animations/interactive.json" type="lottie">
  {({ play, pause, seek, isPlaying }) => (
    <div>
      <div id="lottie-container" />
      <button onClick={play}>Play</button>
      <button onClick={pause}>Pause</button>
      <button onClick={() => seek(0)}>Restart</button>
    </div>
  )}
</MediaHeadless>

Finding Lottie Animations

Free Sources

LottieFiles - Largest library of free animations
IconScout - Free and premium
Motion Elements - Curated collection

Creating Custom Animations

Tools:

After Effects + Bodymovin plugin - Industry standard
LottieFiles Creator - Browser-based editor
Haiku Animator - Animation tool with Lottie export

After Effects workflow:

Create animation in After Effects
Install Bodymovin extension
Export as JSON
Upload JSON file to your project

File Size Optimization

Lottie files are JSON and can be optimized:

Compression

# Minify JSON
cat animation.json | jq -c > animation-min.json

# Gzip for serving
gzip animation-min.json

LottieFiles Optimizer

Use LottieFiles optimizer to:

Remove unused layers
Simplify paths
Reduce keyframes
Optimize colors

Typical sizes:

Simple icon animation: 5-20 KB
Loading spinner: 10-30 KB
Complex scene: 50-200 KB

Accessibility

Required Alt Text

Describe what the animation represents:

// Good - describes the purpose
<LottiePlayer
  src="success.json"
  alt="Success checkmark animation confirming action completed"
/>

// Bad - too generic
<LottiePlayer
  src="success.json"
  alt="Animation"
/>

Reduced Motion

Always provide fallbacks for motion-sensitive users:

<LottiePlayer
  src="animated-feature.json"
  alt="Feature showcase"
  reducedMotionFallback="feature-static.svg"
/>

Decorative Animations

For purely decorative animations, use aria-hidden:

<div aria-hidden="true">
  <LottiePlayer
    src="background-decoration.json"
    alt=""
    autoplay
    loop
  />
</div>

Use Cases

Success States

Celebrate user achievements:

function SuccessMessage() {
  return (
    <div className="success-toast">
      <LottiePlayer
        src="/animations/success.json"
        alt="Success celebration"
        autoplay
        size="sm"
      />
      <p>Your project was created successfully!</p>
    </div>
  )
}

Loading States

Engaging loading indicators:

function LoadingState() {
  return (
    <div className="loading">
      <LottiePlayer
        src="/animations/loading.json"
        alt="Loading animation"
        autoplay
        loop
        size="md"
      />
      <p>Processing your request...</p>
    </div>
  )
}

Feature Highlights

Animate feature icons:

<div className="feature-card">
  <LottiePlayer
    src="/animations/analytics-icon.json"
    alt="Analytics feature icon animation"
    autoplay
    size="sm"
  />
  <h3>Analytics Dashboard</h3>
  <p>Track your metrics in real-time</p>
</div>

Onboarding Tours

Add delight to tour steps:

import { Tour, TourStep } from '@tour-kit/react'
import { LottiePlayer } from '@tour-kit/media'

<Tour id="onboarding">
  <TourStep id="welcome">
    <LottiePlayer
      src="/animations/welcome.json"
      alt="Welcome animation"
      autoplay
    />
    <h2>Welcome to Our Platform!</h2>
  </TourStep>
</Tour>

Empty States

Make empty states more engaging:

<div className="empty-state">
  <LottiePlayer
    src="/animations/empty-inbox.json"
    alt="Empty inbox illustration"
    autoplay
    size="lg"
  />
  <h3>No messages yet</h3>
  <p>Your inbox is empty</p>
</div>

Performance

Renderer Comparison

Renderer	Best For	Performance	File Size Impact
SVG	Most cases, scalability	Good	None
Canvas	Complex animations, many elements	Better	None
HTML	Text-heavy animations	Variable	Larger DOM

Recommendation: Use SVG unless you have performance issues with complex animations.

Progressive Loading

Enable progressive loading for large animations:

<LottiePlayer
  src="/animations/large.json"
  alt="Complex animation"
  lottieOptions={{
    rendererSettings: {
      progressiveLoad: true
    }
  }}
/>

TypeScript

Full type safety with Lottie options:

import type { LottiePlayerProps, LottieOptions } from '@tour-kit/media'

const lottieConfig: LottieOptions = {
  renderer: 'svg',
  loop: true,
  autoplay: true,
  rendererSettings: {
    preserveAspectRatio: 'xMidYMid slice'
  }
}

const config: LottiePlayerProps = {
  src: '/animations/demo.json',
  alt: 'Demo animation',
  autoplay: true,
  loop: true,
  speed: 1,
  lottieOptions: lottieConfig
}

<LottiePlayer {...config} />

LottiePlayer

On this page