AM LottiePlayer

We proudly claim this to be the most versatile, lightweight, and efficient Lottie Player Web Component available. It's compatible with server-side rendering and completely framework-agnostic.

If you only need to render animations as SVGs, don’t use any SVG effects like blur or drop shadow, don’t use Expressions, and don’t need to convert or combine animations on the fly — you can use a lighter version of this package by importing @aarsteinmedia/dotlottie-player/light.

Demo

Here is a demo, running on Next.js 15 with TypeScript.

Installation

In HTML

• Import from CDN:

  • Full version:

    <script src="https://unpkg.com/@aarsteinmedia/dotlottie-player@latest/dist/unpkg-full.js"></script>

  • Light version:

    <script src="https://unpkg.com/@aarsteinmedia/dotlottie-player@latest/dist/unpkg-light.js"></script>

• Import from node_modules:

  • Full version:

    <script src="/node_modules/@aarsteinmedia/dotlottie-player/dist/unpkg-full.js"></script>

  • Light version:

    <script src="/node_modules/@aarsteinmedia/dotlottie-player/dist/unpkg-light.js"></script>

In JavaScript or TypeScript

1. Install using npm, pnpm, or yarn:

   pnpm add @aarsteinmedia/dotlottie-player

2. Import in your app:

   import '@aarsteinmedia/dotlottie-player'

   Or for the light version:

   import '@aarsteinmedia/dotlottie-player/light'

Because this is a Web Component, you're adding it to the global scope of your web app. Unlike modular components, it should only be imported once – preferably early in your app lifecycle.

If you're using TypeScript and want to import the component type, do it modularly in addition to the global import:

import '@aarsteinmedia/dotlottie-player' // Do this once globally.
import type DotLottiePlayer from '@aarsteinmedia/dotlottie-player' // Do this per component that needs it.

⚠️ Note that this pattern may provoke linter errors, such as import/no-duplicates.

Usage

Add the dotlottie-player element to your markup and point the src to a Lottie animation of your choice:

<dotlottie-player
  autoplay
  controls
  subframe
  loop
  id="find-me"
  src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
  style="width: 320px; margin: auto;"
>
</dotlottie-player>

Load animation

To set animations programmatically, use the load() method.

const lottiePlayer = document.querySelector('#find-me')
player?.load('https://storage.googleapis.com/aarsteinmedia/am.lottie')

Convert to dotLottie

If you have a Lottie JSON animation and want to convert it to a dotLottie file – to leverage compression, combine multiple animations, and maintain a tidy file library – you can use the convert() method. This will trigger a browser download.

If controls are visible, there’s also a convert button in the context menu on the right-hand side.

Convert to JSON

If you're debugging a dotLottie animation (e.g., expressions aren’t working as expected), you can convert it to JSON either using the convert() method or via the convert button if controls are enabled.

Combine animations

To combine multiple animations into a single dotLottie file, use the addAnimation() method. This also triggers a browser download. Source files can be either dotLottie or JSON, and the output will always be dotLottie:

const lottiePlayer = document.querySelector('#find-me')
(async () => {
  await lottiePlayer?.addAnimation([
    { id: 'animation_1', url: '/url/to/animation_1.lottie' },
    { id: 'animation_2', url: '/url/to/animation_2.json', direction: -1, speed: 2 }
  ])
}()) 

You can also use this method without any <dotlottie-player> on the page. As long as the script is loaded, dotLottiePlayer() is available as a global method.

(async () => {
  await dotLottiePlayer().addAnimation([
    { id: 'animation_1', url: '/path/to/animation_1.lottie' },
    { id: 'animation_2', url: '/path/to/animation_2.json', direction: -1, speed: 2 }
  ])
}())

The new file will automatically load the first animation when initialized. You can toggle between animations using the next() and prev() methods, or the navigation buttons in the controls.

Here’s how to control playback settings for multiple animations:

<dotlottie-player
  subframe
  id="find-me"
  src="/path/to/combined-animations.lottie"
>
</dotlottie-player>  

  const player = document.querySelector('#find-me')
  player?.setMultiAnimationSettings(
    [
      {
        autplay: true
      },
      {
        autoplay: true,
        loop: true
      }
    ]
  )

Angular

1. Import the component in app.component.ts.

import { Component } from '@angular/core'
import '@aarsteinmedia/dotlottie-player'

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  title = 'your-app-name';
}

2. Add the player to your html template.

React.js / Next.js

Because this is a Web Component and not a React component, note that you must use the class attribute (not className) when assigning a CSS class.

If you prefer pure React logic, you may want to check out @aarsteinmedia/dotlottie-react.

import '@aarsteinmedia/dotlottie-player'

function App() {
  return (
    <dotlottie-player
      autoplay
      controls
      loop
      class="your-class-name"
      src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
      style={{
        width: '320px',
        margin: 'auto'
      }}
    />
  )
}

export default App

If you're using TypeScript and want to assign a ref, do it like this:

import { useRef } from 'react'
import '@aarsteinmedia/dotlottie-player'
import type DotLottiePlayer from '@aarsteinmedia/dotlottie-player'

function App() {
  const animation = useRef<DotLottiePlayer | null>(null)
  return (
    <dotlottie-player
      subframe
      ref={animation}
      src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
    />
  )
}

export default App

Vue.js / Nuxt.js (using Vite.js)

Compared to React and Angular there's a couple of extra steps, but surely nothing too daunting.

1. Declare the dotlottie-player tag as a custom element, to prevent Vue from attempting to resolve it.

In Vue.js

vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag: string) => ['dotlottie-player'].includes(tag),
        }
      }
    })
  ]
})

In Nuxt.js

nuxt.config.ts:

export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag: string) => ['dotlottie-player'].includes(tag),
    }
  }
})

2. Import/initiate the component.

In Vue.js

main.ts:

import { createApp } from 'vue'
import DotLottiePlayer from '@aarsteinmedia/dotlottie-player'
import App from './App.vue'

const app = createApp(App)
app.component('DotLottiePlayer', DotLottiePlayer)

In Nuxt.js

Create a plugins folder in your root if it doesn't exist already, add a file named dotlottie-player.js:

import DotLottiePlayer from '@aarsteinmedia/dotlottie-player'

export default defineNuxtPlugin(({ vueApp }) => {
  vueApp.component('DotLottiePlayer', DotLottiePlayer)
})

3. The component can now be used in your pages or components template tags.

<template>
  <dotlottie-player
    src="https://storage.googleapis.com/aarsteinmedia/am.lottie"
    autoplay
    controls
    subframe
    loop
    style="width: 320px; margin: auto;"
  />
</template>

Properties

Property / Attribute	Description	Type	Default
animateOnScroll	Animate by scrolling	boolean	false
autoplay	Play animation on load	boolean	false
background	Background color	string	undefined
controls	Show controls	boolean	false
count	Number of times to loop animation	number	undefined
direction	Direction of animation	1 | -1	1
dontFreezeOnBlur	Whether to freeze playback on window blur. This is default behavior, but can be disabled	boolean	1
hover	Whether to play on mouse hover	boolean	false
loop	Whether to loop animation	boolean	false
mode	Play mode	normal | bounce	normal
objectfit	Resizing of animation in container	contain | cover | fill | none	contain
renderer	Renderer to use	svg | canvas | html	svg
speed	Animation speed	number	1
src (required)	URL to LottieJSON or dotLottie	string	undefined
subframe	When enabled this can help to reduce flicker on some animations, especially on Safari and iOS devices.	boolean	false

Methods

Method	Function
addAnimation(params: AddAnimationParams) => Promise<Result>	Add animation. Triggers download of new dotLottie file.
convert(params: ConvertParams) => Promise<Result>	If the current animation is in JSON format – convert it to dotLottie. Triggers a download in the browser.
destroy() => void	Nullify animation and remove element from the DOM.
getLottie() => AnimationItem | null	Returns the lottie-web instance used in the component
load(src: string) => void	Load animation by URL or JSON object
next() => void	Next animation (if several in file)
pause() => void	Pause
prev() => void	Previous animation (if several in file)
play() => void	Play
reload() => void	Reload
seek(value: number | string) => void	Go to frame. Can be a number or a percentage string (e. g. 50%).
setCount(value: number) => void	Dynamically set number of loops
setDirection(value: 1 | -1) => void	Set Direction
setLooping(value: boolean) => void	Set Looping
setMultiAnimationSettings(value: AnimationSettings[]) => void	Set Multi-animation settings
setSegment(value: AnimationSegment) => void	Play only part of an animation. E. g. from frame 10 to frame 60 would be [10, 60]
setSpeed(value?: number) => void	Set Speed
setSubframe(value: boolean) => void	Set subframe
snapshot() => string	Snapshot the current frame as SVG. Triggers a download in the browser.
stop() => void	Stop
toggleBoomerang() => void	Toggle between bounce and normal
toggleLooping() => void	Toggle looping
togglePlay() => void	Toggle play

Events

The following events are exposed and can be listened to via addEventListener calls.

Name	Description
complete	Animation is complete – including all loops
destroyed	Animation is destroyed
error	The source cannot be parsed, fails to load or has format errors
frame	A new frame is entered
freeze	Animation is paused due to player being out of view
load	Animation is loaded
loop	A loop is completed
play	Animation has started playing
pause	Animation has paused
ready	Animation is loaded and player is ready
stop	Animation has stopped

WordPress Plugins

We've made a free WordPress plugin that works with Gutenberg Blocks, Elementor, Divi Builder and Flatsome UX Builder: AM LottiePlayer. It has all the functionality of this package, with a helpful user interface.

It's super lightweight – and only loads on pages where animations are used.

We've also made a premium WordPress plugin for purchase: AM LottiePlayer PRO. It has an easy-to-use GUI for combining and controlling multiple Lottie animations in a single file, converting JSON to dotLottie with drag-and-drop, and many more exclusive features.

License

GPL-2.0-or-later