ThroVG for Web

@thorvg/lottie-player

A Lottie Player which uses ThorVG as a renderer, provides a web component for easily embedding and playing Lottie animations.

Installation

• Import from CDN

<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/lottie-player.js"></script>

• Install from NPM

npm install @thorvg/lottie-player

Usage

With HTML (Basic Usage)

Once you import from CDN, you can access <lottie-player/>

<lottie-player 
  autoPlay 
  loop
  mode="normal"
  src="https://lottie.host/6d7dd6e2-ab92-4e98-826a-2f8430768886/NGnHQ6brWA.json"
  style="width: 500px; height: 500px;"
>
</lottie-player>

With NPM (JS/TS)

Import the library and please follow Basic Usage, you can use library on any NPM-based project such as React, Vue and Svelte.

import '@thorvg/lottie-player';

With ReactJS + TypeScript

Add declarations.d.ts on the root of project and make sure following declaration.

declare namespace JSX {
  interface IntrinsicElements {
    "lottie-player": any;
  }
}

Then you will be able to use this as same as above

import '@thorvg/lottie-player';

<lottie-player 
  autoPlay 
  loop
  mode="normal"
  src="https://lottie.host/6d7dd6e2-ab92-4e98-826a-2f8430768886/NGnHQ6brWA.json"
  style="width: 500px; height: 500px;"
>
</lottie-player>

With SSR Framework

We should be careful when using on SSR frameworks such as NextJS, NuxtJS and Svelte, as it means the library must to be rendered on browser/client side.

• NextJS

import { useEffect } from "react";

export default function Home() {
  // ...

  useEffect(() => {
    import("@thorvg/lottie-player");
  });

  // ...
}

• NuxtJS

<template>
  {/* ... */}
</template>

<script>
  export default {
    mounted() {
      import("@thorvg/lottie-player");
    }
  }
</script>

• Svelte

<script>
  import { onMount } from 'svelte';

  onMount(async () => {
    await import('@thorvg/lottie-player');
  });
</script>

API

Properties

Property	Description	Type	Default Value	Required
src	A graphic resource to play. It could be an internal/external URL or JSON string for Lottie.	string	undefined	Y
speed	Animation speed (for Lottie)	number	1	N
autoplay	When set to true, automatically plays the animation on loading it (for Lottie)	boolean	false	N
count	Number of times to loop the animation	number	undefined	N
loop	When set to true, loops the animation. The count property defines the number of times to loop the animation. Setting the count property to 0 and setting the loop to true, loops the animation indefinitely.	boolean	false	N
direction	Direction of the animation. Set to 1 to play the animation forward or set to -1 to play it backward.	number (1 or -1)	1	N
mode	Play mode. Setting the mode to PlayMode.Bounce plays the animation in an indefinite cycle, forwards and then backwards.	PlayMode	PlayMode.Normal	N
intermission	Duration (in milliseconds) to pause before playing each cycle in a looped animation. Set this parameter to 0 (no pause) or any positive number.	number	1	N

Events

You can adapt the event with the following code example

const player = document.querySelector('lottie-player');

player.addEventListener('load', () => {
  // TODO: implements
});

Name	Description
load	A graphic resource is loaded
error	An animation data can’t be parsed.
ready	Animation data is loaded and player is ready
play	Animation starts playing
pause	Animation is paused
stop	Animation is stopped
freeze	Animation is paused due to player being invisible
loop	An animation loop is completed
complete	Animation is complete (all loops completed)
frame	A new frame is entered

Methods

Method : load(src: string | object)

Purpose : Load and play Lottie animation

Parameters

Name	Type	Description
src	string or object	URL, or a JSON string or object representing a Lottie animation to play.

Return Type : Promise<void>

---

Method : play()

Purpose : Play loaded animation

Return Type : void

---

Method : pause()

Purpose : Pause playing animation

Return Type : void

---

Method : stop()

Purpose : Stop current animation

Return Type : void

---

Method : seek(frame: number)

Purpose : Move to a given frame

Parameters

Name	Type	Description
src	number	The frame number to move, shouldn't be less than 0 and greater than totalFrame

Return Type : void

Tip

You can easily check total frame of animation, use player.totalFrame

---

Method : destory()

Purpose : Destroy animation and lottie-player element

Return Type : void

---

Method : setLooping(value: boolean)

Purpose : Enable animation loop

Parameters

Name	Type	Description
value	boolean	true enables looping, while false disables looping.

Return Type : void

---

Method : setDirection(value: number)

Purpose : Set animation direction

Parameters

Name	Type	Description
value	number	Direction values. 1 to play the animation forward, -1 to play it backward.

Return Type : void

---

Method : setSpeed(value: number)

Purpose : Set speed of animation

Parameters

Name	Type	Description
value	number	Playback speed. The value must be any positive integer.

Return Type : void

---

Method : setBgColor(value: string)

Purpose : Set a backgroud color

Parameters

Name	Type	Description
value	string	Color values. Hex(#fff) or string('red') to set background color

Return Type : void

---

Method : save(target: ExportableType)

Purpose : Export current animation to other file type

Parameters

Name	Type	Description
value	ExportableType	File type to export

Return Type : void

---

Method : getVersion()

Purpose : Return current ThorVG version

Return Type : LibraryVersion

Examples

Please check these examples in various environments.

• VanillaJS Usage
• React Usage
• VueJS Usage
• Svelte Usage