ThorVG 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

Contents

• Usage
  • With HTML (Basic Usage)
  • With NPM (JS/TS)
  • With ReactJS + TypeScript
  • With SSR Framework
• Player Preset Variants
  • Standard Presets
  • Lite Presets
  • Preset Comparison
  • Preset Usage
• API
  • Properties
  • Events
  • Methods
• Examples
  • Framework-specific Examples
  • Build Testing
  • Local Examples

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>

Back to contents

Player Preset Variants

ThorVG Lottie Player provides multiple presets optimized for different use cases. Each preset can be selected based on bundle size and performance requirements.

Standard Presets

• SW: A CPU-based renderer with full Lottie specification support
• GL: A WebGL accelerated renderer with full Lottie specification support
• WG: A WebGPU accelerated renderer with full Lottie specification support

Lite Presets

• SW-Lite: A CPU-based renderer that supports basic Lottie specification (PNG only; Fonts and Expressions are not supported)
• GL-Lite: A WebGL accelerated renderer that supports basic Lottie specification (PNG only; Fonts and Expressions are not supported)
• WG-Lite: A WebGPU accelerated renderer that supports basic Lottie specification (PNG only; Fonts and Expressions are not supported)

Preset Comparison

| Preset | Renderer | Features | Bundle Size | Use Case | |--------|----------|---------|-------------|----------| | sw | Software | lottie + expressions, jpg, png, webp, ttf | ~600KB | Full-featured applications with CPU rendering | | gl | WebGL | lottie + expressions, jpg, png, webp, ttf | ~650KB | Full-featured applications with WebGL acceleration | | wg | WebGPU | lottie + expressions, jpg, png, webp, ttf | ~650KB | Full-featured applications with WebGPU acceleration | | sw-lite | Software | lottie, png | ~250KB | Lightweight applications with CPU rendering | | gl-lite | WebGL | lottie, png | ~250KB | Lightweight applications with WebGL acceleration | | wg-lite | WebGPU | lottie, png | ~300KB | Lightweight applications with WebGPU acceleration |

Preset Usage

CDN Usage

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

<!-- Software Renderer (Standard) -->
<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/sw/lottie-player.js"></script>

<!-- WebGL Renderer (Standard) -->
<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/gl/lottie-player.js"></script>

<!-- WebGPU Renderer (Standard) -->
<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/wg/lottie-player.js"></script>

<!-- Software Renderer (Lite) -->
<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/sw-lite/lottie-player.js"></script>

<!-- WebGL Renderer (Lite) -->
<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/gl-lite/lottie-player.js"></script>

<!-- WebGPU Renderer (Lite) -->
<script src="https://unpkg.com/@thorvg/lottie-player@latest/dist/wg-lite/lottie-player.js"></script>

NPM Usage

// Default version
import '@thorvg/lottie-player';

// Software Renderer (Standard)
import '@thorvg/lottie-player/sw';

// WebGL Renderer (Standard)
import '@thorvg/lottie-player/gl';

// WebGPU Renderer (Standard)
import '@thorvg/lottie-player/wg';

// Software Renderer (Lite)
import '@thorvg/lottie-player/sw-lite';

// WebGL Renderer (Lite)
import '@thorvg/lottie-player/gl-lite';

// WebGPU Renderer (Lite)
import '@thorvg/lottie-player/wg-lite';

Back to contents

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 | --- | --- | --- | | frame | 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 : destroy()

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 background color

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

Return Type : void

Method : setQuality(value: number)

Purpose : Set rendering quality for animations

Parameters | Name | Type | Description | --- | --- | --- | | value | number | Quality value (1-100). Higher values are likely to support better quality but may impact performance.

Return Type : void

Method : save(target: ExportableType)

Purpose : Export current animation to other file type

Parameters | Name | Type | Description | --- | --- | --- | | target | ExportableType | File type to export

Return Type : void

Method : getVersion()

Purpose : Return current ThorVG version

Return Type : LibraryVersion

Back to contents

Examples

Framework-specific Examples

Check the usage of each preset in the example/{framework} directory:

• ThorVG React Example
• ThorVG Vue Example
• ThorVG Svelte Example

Build Testing

Test framework compatibility by running builds across different frontend frameworks:

# From the root directory
$ npm run test:build

This will automatically detect framework projects in the example/ directory and test their build processes.

The build testing script is located in ./build-test/.

Local Examples

Check the usage of each preset in the example/ directory:

• Software Renderer (Standard) - Full Lottie support with CPU rendering
• WebGL Renderer (Standard) - Full Lottie support with WebGL acceleration
• Software Renderer (Lite) - Basic Lottie support with CPU rendering
• WebGL Renderer (Lite) - Basic Lottie support with WebGL acceleration
• WebGPU Renderer - Full Lottie support with WebGPU acceleration

Back to contents