• Stars
    star
    718
  • Rank 63,070 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 4 years ago
  • Updated 6 months ago

Reviews

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

Repository Details

lottie web player as a react component

LottiePlayer React Component

This is a React component for the Lottie Web Player

Demo

screencast

Documentation

In Javascript or TypeScript:

  1. Install package using npm or yarn.
npm install --save @lottiefiles/react-lottie-player
  1. Import package in your code.
import { Player, Controls } from '@lottiefiles/react-lottie-player';

Example/Development

  1. Clone repo

  2. run yarn install

  3. run yarn storybook

yarn storybook

Usage

Player component

Add the element Player and set the src prop to a URL pointing to a valid Lottie JSON.

<Player
  autoplay
  loop
  src="https://assets3.lottiefiles.com/packages/lf20_UJNc2t.json"
  style={{ height: '300px', width: '300px' }}
>
  <Controls visible={true} buttons={['play', 'repeat', 'frame', 'debug']} />
</Player>

Props

Prop Description Type Default
lottieRef Get lottie animation object function undefined
onEvent Listen for events function undefined
onStateChange Play state changes function undefined
onBackgroundChange Listen for bg changes function undefined
autoplay Autoplay animation on load. boolean false
background Background color. string undefined
controls Show controls. boolean false
direction Direction of animation. number 1
hover Whether to play on mouse hover. boolean false
keepLastFrame Stop animation on the last frame.
Has no effect if loop is true.
boolean false
loop Whether to loop animation. boolean false
renderer Renderer to use. `"svg" "canvas"`
speed Animation speed. number 1
style The style for the container. object undefined
src (required) Bodymovin JSON data or URL to JSON. object string

Get Player instance

To call methods on the instance of the Player component. you may get a reference to the component and call the methods on ref.current. This is esentially reacts way of doing a document.getElementById(); You may then use this ref ie: player in the example below to call methods that are described in this documentation. See ref in react documentation

import React from 'react';
import { Player } from '@lottiefiles/react-lottie-player';

class App extends React.Component {
  constructor(props) {
    super(props);
    this.player = React.createRef(); // initialize your ref
  }
  render() {
    return (
      <Player
        ref={this.player} // set the ref to your class instance
        autoplay={false}
        loop={true}
        controls={true}
        src="https://assets3.lottiefiles.com/packages/lf20_XZ3pkn.json"
        style={{ height: '300px', width: '300px' }}
      ></Player>
    );
  }
}

export default App;

Get Lottie instance

The lottieRef prop returns the Lottie instance which you can use to set data and call methods as described in the bodymovin documentation.

import React from 'react';
import { Player } from '@lottiefiles/react-lottie-player';

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = { lottie: null }; // initialize your state
  }

  render() {
    return (
      <Player
        lottieRef={instance => {
          this.setState({ lottie: instance }); // the lottie instance is returned in the argument of this prop. set it to your local state
        }}
        autoplay={false}
        loop={true}
        controls={true}
        src="https://assets3.lottiefiles.com/packages/lf20_XZ3pkn.json"
        style={{ height: '300px', width: '300px' }}
      ></Player>
    );
  }
}

export default App;

Listening for events

import React from 'react';
import { Player } from '@lottiefiles/react-lottie-player';

class App extends React.Component {
  constructor(props) {
    super(props);
    this.player = React.createRef();
  }

  doSomething() {
    this.player.current.play(); // make use of the player and call methods
  }

  render() {
    return (
      <Player
        onEvent={event => {
          if (event === 'load') this.doSomething(); // check event type and do something
        }}
        ref={this.player}
        autoplay={false}
        loop={true}
        controls={true}
        src="https://assets3.lottiefiles.com/packages/lf20_XZ3pkn.json"
        style={{ height: '300px', width: '300px' }}
      ></Player>
    );
  }
}

export default App;

Events

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

Name Description
load Animation data is loaded.
error An animation source cannot be parsed, fails to load or has format errors.
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

pause() => void

Pause animation play.

Returns

Type: void

play() => void

Start playing animation.

Returns

Type: void

setPlayerDirection(direction: 1 | -1 ) => void

Animation play direction.

Parameters

Name Type Description
value number Direction values.

Returns

Type: void

setPlayerSpeed(speed?: number) => void

Sets animation play speed.

Parameters

Name Type Description
value number Playback speed.

Returns

Type: void

stop() => void

Stops animation play.

Returns

Type: void

setSeeker(frame: number, play: boolean) => void

Seek to a given frame.

Returns

Type: void

Contributing

We use changesets to maintain a changelog for this repository. When making any change to the codebase that impacts functionality or performance we require a changeset to be present.

To add a changeset run:

yarn run changeset

And select the type of version bump you'd like (major, minor, path).

You can document the change in detail and format it properly using Markdown by opening the ".md" file that the "yarn changeset" command created in the ".changeset" folder. Open the file, it should look something like this:

---
"@lottiefiles/pkg1": minor
"@lottiefiles/pkg2": major
---

This is where you document your **changes** using Markdown.

- You can write
- However you'd like
- In as much detail as you'd like

Aim to provide enough details so that team mates and future you can understand the changes and the context of the change.

You can commit your changes and the changeset to your branch and then create a pull request on the develop branch.

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-interactivity

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

awesome-lottie

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

jlottie

A small-footprint lottie player in Javascript
CSS
182
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