• This repository has been archived on 12/Nov/2023
  • Stars
    star
    182
  • Rank 211,154 (Top 5 %)
  • Language
    CSS
  • License
    MIT License
  • Created almost 4 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A small-footprint lottie player in Javascript

jLottie

jLottie is a Lottie player written in javascript with an aim to have the smallest possible file size. jLottie is suitable as a general purpose lottie player, though implements a subset of the features in the core player - this approach leads to a tiny footprint and great performance.

At only 15kb when gzipped, jLottie is perfect as a lightweight addition to any webapp where not all of the lottie featues are necessary - common use cases include animated icons and micro animations. A list of all of the playback features supported by jLottie is available here, and there's a test page available here.

jLottie's performance is achieved by compiling the Lottie source into a scene graph, which is subsequently used to play the animation. This forgoes any need to perform real-time computations during playback. jLottie is suitable for use when there are many animations playing on a single page.

  • jLottie player is best used for animated icons and micro animations
  • jLottie player is vastly smaller in size (at 15kb when gzipped) compared to other Lottie players
  • jLottie player is suitable for use if there are many animations playing on a single page
  • jLottie player is highly performant

Performance

Below are results of some performance tests comparing jLottie with lottie-player.

Single animation

In this test 11 Lottie animations were selected from the Lottiefiles public animations repository, and their runtime performance and memory utilization was recorded using Chrome's analysis tools. The performance figures were prorated to 1 second durations, which allows for direct comparison, as per the table below.

All figures other than memory is in milliseconds.

Scripting Rendering Painting System Idle Memory (MB)
Best jLottie 41 11 5 14 928 1.9
lottie-player 122 28 10 37 801 4
Average jLottie 70 29 8 23 872 3.4
lottie-player 91 36 11 31 831 6.2
Worst jLottie 124 35 11 24 805 8
lottie-player 84 41 9 25 840 4.7

Stress test

In this test, a total of 35 Lottie animations, whose features are fully supported by jLottie, were chosen at random from the Lottiefiles public animations repository. These animations were then rendered in one page at the same time, and performance and memory utilization analyzed using Chrome tools.

The test pages used for this test are here for jLottie and here for lottie-player.

During this test, it was discovered that all 35 animations noticeably skipped frames when lottie-player was rendering them. Conversely, jLottie is designed not to skip any frames, and therefore no jitter could be discerned on any of the animations even during the Chrome performance analysis.

All figures other than memory is in milliseconds.

Scripting Rendering Painting System Idle Memory (MB)
jLottie 515 269 36 62 115 73.7
lottie-player 564 205 19 45 166 183

Features

Supported features

  • Shapes (except, ellipse, polystar, repeater, trim paths)
  • Fills (except radial gradient)
  • Strokes (without opacity and dashes)
  • Transforms
  • Interpolation (except roving across time)
  • Masks (limited to path, opacity and subtract)
  • Layer effects (limited to only fills)

Features not supported

  • Matts
  • Merge paths
  • Text
  • Expressions
  • Images
  • Precomps
  • Time stretch
  • Time remap
  • Markers

Installation

In HTML:

  • Import from CDN.
<script src="https://unpkg.com/@lottiefiles/jlottie@latest/dist/jlottie.min.js" type="module"></script>

In Javascript or TypeScript:

  1. Install package using npm or yarn.
npm install --save @lottiefiles/jlottie
  1. Import package in your code.
import * as jlottie from '@lottiefiles/jlottie';

OR

const jlottie = require('@lottiefiles/jlottie');

Usage

<div id="my-animation"></div>

To load an animation from a URL:

jlottie.loadAnimation({
  container: document.getElementById('my-animation'),
  loop: true,
  autoplay: true,
  useWebWorker: false,
  path: '<LOTTIE_URL>',
});

To directly pass animation data:

jlottie.loadAnimation({
  container: document.getElementById('my-animation'),
  loop: true,
  autoplay: true,
  useWebWorker: false,
  animationData: animationDataVariable,
});

To enable debugging (debug outputs console logs and debugAnimation outputs exception messages to the debugContainer):

jlottie.loadAnimation({
  container: document.getElementById('my-animation'),
  loop: true,
  autoplay: true,
  debug: true,
  debugAnimation: true,
  debugContainer: document.getElementById('debug-div'),
  useWebWorker: false,
  path: '<LOTTIE_URL>',
});

In all three cases above, simply set useWebWorker to true to enable rendering using web workers.

API

Methods

jlottie.loadAnimation(configObject)

Takes in an object with format as follows as parameter

{
  container: document.getElementById('my-animation'), // html dom element to hook animation to
  loop: true, // loop toggle
  autoplay: true, // autoplay
  path: '<LOTTIE_URL>', // path to hosted lottie file
}

Returns

Type: Object, that refers to the created animation with the following properties:

thisAnimation._currentFrame; // the current frame number thisAnimation is on
thisAnimation._totalFrames; // the total number of frames in thisAnimation 

jlottie.pause(elementId)

Pause animation. Takes in the Dom element Id as parameter.

Alternative : thisAnimation.pause()

Returns

Type: Null

jlottie.play(elementId)

Play animation. Takes in the Dom element Id as parameter.

Alternative : thisAnimation.play()

Returns

Type: Null

jlottie.stop(elementId)

Stop animation. Takes in the Dom element Id as parameter.

Alternative : thisAnimation.stop()

Returns

Type: Null

jlottie.destroy(elementId)

Destroy animation. Takes in the Dom element Id as parameter.

Alternative : thisAnimation.destroy()

Returns

Type: Null

jlottie.goToAndStop(frame, elementId)

Go to specified frame and stop. Takes in a frame number and Dom element Id as parameter.

Alternative : thisAnimation.goToAndStop(frame)

Returns

Type: Null

Events dispatched

loopComplete

Fires at the end of each loop.

detail = {  
            count: num1, // number of loops thus far
            frame: num2, // the current frame number
            animation: num3 // internal index number of this animation
          }

hovered

Fires when pointer enters the bounding box of the animation.

detail = {  
            animation: num1 // internal index number of this animation
          }

DOMLoaded

Fires right after all DOM content is loaded.

detail = {  
            animation: num1 // internal index number of this animation
          }

loadError

Fires if an error is encountered whilst loading the animation.

detail = {  
            error: {} // the error object thrown
            animation: num1 // internal index number of this animation
          }

Go to specified frame and stop. Takes in a frame number and Dom element Id as parameter.

Development

Building

1. Install dependencies.
yarn install
2. Dev mode.
yarn dev

Automatically build and preview while developing. This runs rollup in watch mode and spins up a server at port 10000 to preview and test the builds.

3. Production builds.
yarn build

This creates ESM, CJS and UMD builds in the dist directory.

Testing

  1. Install packages
yarn install
  1. Run test command.
yarn test

This will generate snapshots in the __snapshots__ directory and warn of mismatches with lottie-web renderer as the comparison baseline.

Contributing

See how to contribute to this project.

FAQ

  • Why doesnt my Lottie animation work on the jLottie player?

  • The jLottie player does not support as many Adobe After Effects features as other players, as it was built to be smaller in size and highly performant. It therefore may not support certain settings, effects or features that were used when creating the animation. Please send us feedback and by popular demand we may make accomdations as needed. You can submit your feed back here. Click here

  • What features/effects of After Effects does this player support?

  • Features supported by jLottie are listed here.

  • Where can I raise issues?

  • Please use github issues to highlight any bugs.

  • Where can I drop feedback?

  • You may Click here and submit your feedback

License

MIT License © LottieFiles.com

More Repositories

1

lottie-player

Lottie viewer/player as an easy to use web component! https://lottiefiles.com/web-player
TypeScript
1,539
star
2

lottie-react

lottie web player as a react component
TypeScript
718
star
3

lottie-interactivity

A small javascript library to enable interactivity with Lottie animations
HTML
428
star
4

awesome-lottie

A curated list of bookmarks, libraries, tools and resources related to Lottie and Bodymovin
306
star
5

dotlottie-web

Official LottieFiles player for rendering Lottie and dotLottie animations in the web. Supports React, Vue, Svelte, SolidJS and Web Components.
TypeScript
155
star
6

dotlottie-rs

A universal, high-performance Lottie and dotLottie player built with Rust. Offers smooth rendering across platforms, low resource consumption, and extensive compatibility. Features FFI bindings for Kotlin, Swift, and WASM for seamless integration in Android, iOS, and Web projects.
Rust
147
star
7

lottie-js

An object model for representing and manipulating the Lottie JSON structure in JS.
TypeScript
143
star
8

svelte-lottie-player

Lottie Player component for Svelte
HTML
136
star
9

glottie

OpenGL/WebGL based Lottie animation player
C++
117
star
10

lottie-vue

Lottie player wrapper for Vue.js
Vue
112
star
11

tgskit

Toolkit for dealing with Telegram Stickers and Bodymovin/Lottie animations.
TypeScript
62
star
12

relottie

Lottie processor powered by plugins
TypeScript
45
star
13

lottie-docs

Documentation for the lottie file format
Python
45
star
14

dotlottie-ios

.lottie player for iOS
C
41
star
15

dotlottie-android

Kotlin
37
star
16

svg-to-lottie-converter

SVG to Lottie API
Python
25
star
17

demo-audio-visualisation

Demonstration code for visualising audio with Lottie
C#
14
star
18

Course-for-Developers

In this quick course, you will learn the basics about implementing Lottie animations across your web and mobile apps.
10
star
19

lottie-theming

JavaScript
10
star
20

dotlottie-cs

C#
8
star
21

plugin-strapi

TypeScript
4
star
22

LottieNB

Simple insertion of Lottie player into Jupyter Notebooks
Jupyter Notebook
4
star
23

labs-epub3

Testing lottie support in an epub3 document
Shell
4
star
24

test-files

A collection of basic lotties to test lottie tooling
Python
3
star
25

lottie-styler

TypeScript
3
star
26

app-tutorial-lottieinteractions

A tutorial for Lottie Interactions
Swift
2
star
27

dotlottie-react-native

Kotlin
2
star
28

gltf-color

TypeScript
1
star