Skip to content

Usage

Jump to bottom
Mattia Basaglia edited this page Feb 14, 2023 · 2 revisions

Getting Started

Here's a video tutorial explaining how to export a basic animation and load it in an html page

  • get the lottie.js file from the build/player/ folder for the latest build
  • include the .js file on your html (remember to gzip it for production)
<script src="js/lottie.js" type="text/javascript"></script>

You can call lottie.loadAnimation() to start an animation. It takes an object as a unique param with:

  • animationData: an Object with the exported animation data. Note: If your animation contains repeaters and you plan to call loadAnimation multiple times with the same animation, please deep clone the object before passing it (see #1159 and #2151.)
  • path: the relative path to the animation object. (animationData and path are mutually exclusive)
  • loop: true / false / number
  • autoplay: true / false it will start playing as soon as it is ready
  • name: animation name for future reference
  • renderer: 'svg' / 'canvas' / 'html' to set the renderer
  • container: the dom element on which to render the animation

It returns the animation instance you can control with play, pause, setSpeed, etc.

var anim = lottie.loadAnimation({
  container: element, // the dom element that will contain the animation
  renderer: 'svg',
  loop: true,
  autoplay: true,
  path: 'data.json' // the path to the animation json
});

Or if you already have the JSON parsed in a JavaScript object:

var anim = lottie.loadAnimation({
  container: element, // the dom element that will contain the animation
  renderer: 'svg',
  loop: true,
  autoplay: true,
  animationData: animation
});

You can see more options available under Renderer Settings.

Other loading options

  • if you want to use an existing canvas to draw, you can pass an extra object: 'rendererSettings' with the following configuration:
var anim = lottie.loadAnimation({
  container: element, // the dom element
  renderer: 'svg',
  loop: true,
  autoplay: true,
  animationData: animationData, // the animation data
  // ...or if your animation contains repeaters:
  // animationData: cloneDeep(animationData), // e.g. lodash.clonedeep
  rendererSettings: {
    context: canvasContext, // the canvas context, only support "2d" context
    preserveAspectRatio: 'xMinYMin slice', // Supports the same options as the svg element's preserveAspectRatio property
    clearCanvas: false,
    progressiveLoad: false, // Boolean, only svg renderer, loads dom elements when needed. Might speed up initialization for large number of elements.
    hideOnTransparent: true, //Boolean, only svg renderer, hides elements when opacity reaches 0 (defaults to true)
    className: 'some-css-class-name',
    id: 'some-id',
  }
});

Doing this you will have to handle the canvas clearing after each frame
Another way to load animations is adding specific attributes to a dom element. You have to include a div and set it's class to "lottie". If you do it before page load, it will automatically search for all tags with the class "lottie". Or you can call lottie.searchAnimations() after page load and it will search all elements with the class "lottie".

  • Add the data.json to a folder relative to the html
  • Create a div that will contain the animation.
  • Required
    • A class called "lottie"
    • A "data-animation-path" attribute with relative path to the data.json
  • Optional
    • A "data-anim-loop" attribute
    • A "data-name" attribute to specify a name to target play controls specifically

Example

 <div style="width:1067px;height:600px"  class="lottie" data-animation-path="animation/" data-anim-loop="true" data-name="ninja"></div>

Animation object

lottie.loadAnimation will return an Animation object, which has these main methods:

play()

Starts playing the animation from the current frame.

pause()

Pauses playback, staying at the current frame.

stop()

Pauses playback and goes back to the first frame.

setSpeed(speed)

  • speed: 1 is normal speed.

goToAndStop(value, isFrame)

  • value: numeric value.
  • isFrame: defines if first argument is a time based value or a frame based (default false).

goToAndPlay(value, isFrame)

  • value: numeric value.
  • isFrame: defines if first argument is a time based value or a frame based (default false).

setDirection(direction)

  • direction: 1 is forward, -1 is reverse.

playSegments(segments, forceFlag)

  • segments: array. Can contain 2 numeric values that will be used as first and last frame of the animation. Or can contain a sequence of arrays each with 2 numeric values.
  • forceFlag: boolean. If set to false, it will wait until the current segment is complete. If true, it will update values immediately.

setSubframe(useSubFrames)

  • useSubFrames: If false, it will respect the original AE fps. If true, it will update on every requestAnimationFrame with intermediate values. Default is true.

destroy()

Cleans up the internal data when you no longer need to play the animation

getDuration(inFrames)

  • inFrames: If true, returns duration in frames, if false, in seconds.

Additional methods:

  • updateDocumentData -- updates a text layer's data More Info

Properties

  • currentFrame: The current frame within the animation

Events

  • onComplete
  • onLoopComplete
  • onEnterFrame
  • onSegmentStart

you can also use addEventListener with the following events:

  • complete
  • loopComplete
  • drawnFrame
  • enterFrame
  • segmentStart
  • config_ready (when initial config is done)
  • data_ready (when all parts of the animation have been loaded)
  • data_failed (when part of the animation can not be loaded)
  • loaded_images (when all image loads have either succeeded or errored)
  • DOMLoaded (when elements have been added to the DOM)
  • destroy

Global Methods

Lottie has several global methods that will affect all animations:

lottie.play() -- with 1 optional parameter name to target a specific animation
lottie.stop() -- with 1 optional parameter name to target a specific animation
lottie.goToAndStop(value, isFrame, name) -- Moves an animation with the specified name playback to the defined time. If name is omitted, moves all animation instances.
lottie.setSpeed() -- first argument speed (1 is normal speed) -- with 1 optional parameter name to target a specific animation
lottie.setDirection() -- first argument direction (1 is normal direction.) -- with 1 optional parameter name to target a specific animation
lottie.searchAnimations() -- looks for elements with class "lottie" or "bodymovin"
lottie.loadAnimation() -- Explained above. returns an animation instance to control individually.
lottie.destroy(name) -- Destroys an animation with the specified name. If name is omitted, destroys all animation instances. The DOM element will be emptied.
lottie.registerAnimation() -- you can register an element directly with registerAnimation. It must have the "data-animation-path" attribute pointing at the data.json url
lottie.getRegisteredAnimations() -- returns all animations instances
lottie.setQuality() -- default 'high', set 'high','medium','low', or a number > 1 to improve player performance. In some animations as low as 2 won't show any difference.
lottie.setLocationHref() -- Sets the relative location from where svg elements with ids are referenced. It's useful when you experience mask issues in Safari.
lottie.freeze() -- Freezes all playing animations or animations that will be loaded
lottie.unfreeze() -- Unfreezes all animations
lottie.inBrowser() -- true if the library is being run in a browser
lottie.resize() -- Resizes all animation instances

Clone this wiki locally