lottie-player Web Component

This is a Web Component for easily embedding and playing Lottie animations and the Lottie-based Telegram Sticker (tgs) animations in websites.

npm webcomponents.org

Demo

screencast

Installation

In HTML, import from CDN or from the local Installation:

Lottie Player:
  • Import from CDN.
<script src="https://unpkg.com/@lottiefiles/lottie-player@0.2.0/dist/lottie-player.js"></script>
  • Import from local node_modules directory.
<script src="/node_modules/@lottiefiles/lottie-player/dist/lottie-player.js"></script>
Telegram Sticker (TGS) Player:
  • Import from CDN.
<script src="https://unpkg.com/@lottiefiles/lottie-player@0.2.0/dist/tgs-player.js"></script>
  • Import from local node_modules directory.
<script src="/node_modules/@lottiefiles/lottie-player/dist/tgs-player.js"></script>

In Javascript or TypeScript:

  1. Install package using npm or yarn.
npm install --save @lottiefiles/lottie-player
  1. Import package in your code.
import '@lottiefiles/lottie-player';

Usage

Lottie-Player

Add the element lottie-player and set the src property to a URL pointing to a valid Bodymovin JSON.

<lottie-player
    autoplay
    controls
    loop
    mode="normal"
    src="https://assets3.lottiefiles.com/packages/lf20_UJNc2t.json"
    style="width: 320px"
>
</lottie-player>

You may set and load animations programatically as well.

<lottie-player
    autoplay
    controls
    loop
    mode="normal"
    style="width: 320px"
>
</lottie-player>
const player = document.querySelector('lottie-player');
player.load('https://assets3.lottiefiles.com/packages/lf20_UJNc2t.json');

// or load via a Bodymovin JSON string/object
player.load('{"v":"5.3.4","fr":30,"ip":0,"op":38,"w":315,"h":600,"nm":"new", ... }');

TGS-Player

Add the element tgs-player and set the src property to a URL pointing to a valid TGS JSON.

<tgs-player
    autoplay
    loop
    mode="normal"
    src="https//domain/example.tgs"
>
</tgs-player>

Properties

PropertyAttributeDescriptionTypeDefault
autoplayautoplayAutoplay animation on load.booleanfalse
backgroundbackgroundBackground color.stringundefined
controlscontrolsShow controls.booleanfalse
countcountNumber of times to loop animation.numberundefined
directiondirectionDirection of animation.number1
hoverhoverWhether to play on mouse hover.booleanfalse
looploopWhether to loop animation.booleanfalse
modemodePlay mode.PlayMode.Bounce \| PlayMode.NormalPlayMode.Normal
rendererrendererRenderer to use."svg"'svg'
speedspeedAnimation speed.number1
src (required)srcBodymovin JSON data or URL to JSON.stringundefined

Methods

getLottie() => Promise<any>

Returns the instance of lottie player used in the component.

Returns

Type: Promise<any>

load(src: string | object) => void

Load (and play) a given Bodymovin animation.

Parameters

NameTypeDescription
srcstring or objectURL, or a JSON string or object representing a Bodymovin JSON.

Returns

Type: void

pause() => void

Pause animation play.

Returns

Type: void

play() => void

Start playing animation.

Returns

Type: void

setDirection(value: number) => void

Animation play direction.

Parameters

NameTypeDescription
valuenumberDirection values.

Returns

Type: void

setLooping(value: boolean) => void

Sets the looping of the animation.

Parameters

NameTypeDescription
valuebooleanWhether to enable looping. Boolean true enables looping.

Returns

Type: void

setSpeed(value?: number) => void

Sets animation play speed.

Parameters

NameTypeDescription
valuenumberPlayback speed.

Returns

Type: void

stop() => void

Stops animation play.

Returns

Type: void

seek(value: number | string) => void

Seek to a given frame. Frame value can be a number or a percent string (e.g. 50%).

Returns

Type: void

snapshot(download?: boolean) => string

Snapshot the current frame as SVG. If 'download' argument is boolean true, then a download is triggered in browser.

Returns

Type: string

toggleLooping() => void

Toggles animation looping.

Returns

Type: void

togglePlay() => void

Toggle playing state.

Returns

Type: void

Events

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

NameDescription
loadAnimation data is loaded.
errorAn animation source cannot be parsed, fails to load or has format errors.
readyAnimation data is loaded and player is ready.
playAnimation starts playing.
pauseAnimation is paused.
stopAnimation is stopped.
freezeAnimation is paused due to player being invisible.
loopAn animation loop is completed.
completeAnimation is complete (all loops completed).
frameA new frame is entered.

Styling

Custom propertyDescriptionDefault
--lottie-player-toolbar-heightToolbar height35px
--lottie-player-toolbar-background-colorToolbar background colortransparent
--lottie-player-toolbar-icon-colorToolbar icon color#999
--lottie-player-toolbar-icon-hover-colorToolbar icon hover color#222
--lottie-player-toolbar-icon-active-colorToolbar icon active color#555
--lottie-player-seeker-track-colorSeeker track color#CCC
--lottie-player-seeker-thumb-colorSeeker thumb colorrgba(0, 107, 120, 0.8)

License

MIT License © LottieFiles.com