Lottie player

Import LottiePlayer from @waaark/luge, register it with luge.addPlugin('lottie', LottiePlayer), then call luge.init(). See Getting started for a complete setup.

A lottie animation player with auto play and loop capabilities.

Usage

<div
  data-lg-lottie="/path/to/my-lottie.json"
  data-lg-lottie-autoplay
  data-lg-lottie-loop
  data-lg-lottie-loop-frame="50"
  data-lg-lottie-reverse>
</div>

The lottie player elements get a .lg-lottie CSS classes when initiated. They also get .is-loaded, .is-playing, .is-playing-forward, .is-playing-backward, .is-paused CSS classes when loaded/played/paused.

Please note that lottie is not bundled with luge, you have to make sure to load lottie in your code and make the lottie property globally accessible. By default you have to make sure lottie is available before luge initialization.

If you want to defer the load of lottie code for optimization purposes, you can call luge.lottie.deferInit() once lottie has been loaded.

luge.lifecycle.add('siteIn', (done) => {
  import(/* webpackChunkName: "lottie" */ 'lottie-web/build/player/lottie_light').then(module => {
    const lottie = module.default
    window.lottie = lottie
    luge.lottie.deferInit()
  })
  done()
})

Lazy loading

To start loading a lottie animation only when it enters the viewport, you can add the data-lg-lottie-lazy attribute on your element.

Lazy players start playback when their first DOMLoaded event fires, even without data-lg-lottie-autoplay. Lazy player methods and player are unavailable until viewport entry initializes that player. Do not combine lazy with required: the page-loading gate expects an initialized player.

Attributes

Attribute	Type	Default	Description
`data-lg-lottie`	String	unset	Path to lottie json file.
`data-lg-lottie-autoplay`	Boolean	false	Autoplay animation after load or when it gets in the viewport.
`data-lg-lottie-lazy`	Boolean	false	Lazy load the lottie json file only when the element gets in the viewport.
`data-lg-lottie-required`	Boolean	false	Hold page loading until the animation is ready or reports a loading failure. Use with a non-lazy player initialized before `pageLoad`.
`data-lg-lottie-force`	Boolean	false	Keep playback running when the element leaves the viewport.
`data-lg-lottie-persistent`	Boolean	false	For non-lazy players, skip viewport-driven pause/resume listeners. This does not preserve the player across page cleanup.
`data-lg-lottie-loop`	Boolean	false	Makes animation loop.
`data-lg-lottie-loop-frame`	Number	0	If you want the animation to loop from a given frame. Useful when the lottie animation contains both intro and loop animations.
`data-lg-lottie-subframe`	Boolean	true	Let lottie uses subframes. The default value can be changed globally in JS `luge.settings({lottie: {subFrame: true}})`.
`data-lg-lottie-renderer`	String	‘svg’	Change the lottie renderer. The default value can be changed globally in JS `luge.settings({lottie: {renderer: 'svg'}})`.
`data-lg-lottie-reverse`	Boolean	false	When used with the loop attribute, makes the animation play in reverse from end instead of jumping to start.
`data-lg-lottie-scroll`	Boolean	false	When set, the animation will be played on scroll based on the element progress inside the viewport.

Methods

play()

Play the animation manually.

const myElement = document.querySelector('.lg-lottie')
myElement.play()

pause()

Pause the animation manually.

const myElement = document.querySelector('.lg-lottie')
myElement.pause()

stop()

Stop the animation manually.

const myElement = document.querySelector('.lg-lottie')
myElement.stop()

Deferred initialization

Load Lottie into window.lottie before initialization. If loading it later, call luge.lottie.deferInit() once after it becomes available. Initialized players expose play(), pause(), stop(), and player. Deferring until siteIn cannot hold the earlier pageLoad phase, so do not use this approach for required intro assets. Requests that never settle still have no built-in timeout.

deferInit() initializes the current elements but does not install the normal pageInit or pageLoad hooks. If later pages introduce new Lottie containers, emit update after their DOM has been inserted to discover them. Load Lottie before startup when you need automatic page-by-page initialization and required loading gates.

When Lottie reports a loading failure, the container receives is-error and emits a non-bubbling lottieerror event with the asset path in event.detail.path. Listen on the container (or use a capture listener). The failed player does not autoplay, is not marked is-loaded, and releases its required loading gate once so page entry can continue. Other players continue normally.

Page cleanup destroys players belonging to the old page. Loop work already queued on the ticker is discarded if that player has been destroyed or replaced; it cannot restart a player from the departed page. Keep page-specific player containers inside [data-lg-page] when using Transition; persistent is a viewport-playback option, not a general teardown guarantee.

Try it

Open the full demo