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