@thorvg/lottie-player NPM

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