Lottie Player

Interactivity Guide

This is a quick demo for using the Lottie web player to add interactivity to your applications

github logo

Animation by KidA Studio

Getting Started

Requirements

The Lottie Web Player wrapper is required to use the interactivity library. Click here to view the repository for the player.

Installation

via yarn

npm install --save @lottiefiles/lottie-interactivity

via cdn

<script src="https://unpkg.com/@lottiefiles/lottie-interactivity@latest/dist/lottie-interactivity.min.js"></script>

Add Lottie component to your html dom.

<lottie-player id="firstLottie" src="https://assets2.lottiefiles.com/packages/lf20_i9mxcD.json" style="width:400px; height: 400px;"></lottie-player>

Configure library

<script>
  LottieInteractivity.create({
    player: '#firstLottie',
    mode: 'scroll',
    actions: [
      {
        visibility: [0,1],
        type: 'seek',
        frames: [0, 300],
      },
    ]
  });
</script>

The name of the player ie: 'firstLottie' in this example is the ID set to the lottie web component on the html page. Configuration will contain an actions object. This object takes an array named actions which consists of an array of objects. Multiple objects can be added into this array and therefore multiple actions such as "seek","play", "stop" and "loop", can be set.

Each object has a start and end which is essentially a percentage for the height of the lottie container and is a value between 0 and 1. The visibility arrays first value is the start and the second value is the end. This refers to the percentage of the viewport.

Ensure that the ending frame is the frame you want the interactivity to end at. This could be the last frame or a frame of your choosing. In this case it is set to 100.

Configuration modes include "scroll" where the animation will be synced to the scrolling of the window and "cursor" where the scrolling of the animation will be synced to the cursor position within the container.

The configuration can include a container field as shown in the next example. If a container is not provided the parent div will be taken as a container.

Sync Lottie with scroll

This section shows an example of a Lottie that is synced with the scroll bar. The scrolling effect is activated as soon as the animation enters the viewport. You may position the Lottie anywhere on your website and the Lottie will seek frame by frame as you scroll down the website.

Animation by Ilya Pavlov

<script>
  LottieInteractivity.create({
    player: '#firstLottie',
    mode: 'scroll',
    actions: [
      {
        visibility: [0,1],
        type: 'seek',
        frames: [0, 300],
      },
    ]
  });
</script>

Lottie scroll relative to container

There may be situations where you would like to wrap the lottie player inside a container or just in general sync the lottie scroll with a div on your page. In which case you may pass a container variable with the container id into the action object.

Animation by Mohammed Alruways

This containers ID is "MyContainerId". The scroll activates in this example once the container with "MyContainerId" is in the viewport.

<script>
  LottieInteractivity.create({
    player: "#secondLottie",
    mode:"scroll",
    container: "#MyContainerId",
    actions: [
      {
        visibility: [0, 1.0],
        type: 'seek',
        frames: [90, 123],
      },
    ]
  });
</script>

Lottie scroll with offset

If you would like to add an offset to the top of the container or player you may add an extra action object to the array. For this example, from 0 to 30% of the container, the lottie will be stopped and from 30% to 100% of the container the lottie will be synced with the scroll.

Animation by 0440 Molly

<script>
  LottieInteractivity.create({
    player: '#thirdLottie',
    mode: 'scroll',
    actions: [
      {
          visibility: [0, 0.3],
          type: "stop",
          frames: [50]
      },
      {
          visibility: [0.3, 1.0],
          type: "seek",
          frames: [50, 240]
      }
    ]
  });
</script>

Scroll effect with offset and segment looping

In cases where you would like the animation to loop from a specific frame to a specific frame, you can add an additional object to actions in which you can specify the frames.

In the example below, the lottie loops frame 45 to 60 once 45% of the container is reached.

Animation by Rizwan Asghar

<script>
  LottieInteractivity.create({
    player: "#fourthLottie",
    mode:"scroll",
    actions: [
      {
          visibility: [0, 0.2],
          type: "stop",
          frames: [0]
      },
      {
          visibility: [0.2,0.45],
          type: "seek",
          frames: [0, 45]
      },
      {
          visibility: [0.45,1.0],
          type: "loop",
          frames: [45, 60]
      }
    ]
  });
</script>

Play segments

If you would like to play the animation and loop it only from a certain frame to a certain frame, then you can utilize the loop action and frames variable. This example shows an animation looping from frame 70 to 500.

Animation by Andy Dao

<script>
  LottieInteractivity.create({
    player: '#fifthLottie',
    mode: 'scroll',
    actions: [
      {
          visibility: [0, 1],
          type: "loop",
          frames: [70, 500]
      }
    ]
  });
</script>

Play segments on hover

To loop certain segments on hover, ensure that the Lottie is already at the frame you want to start the on hover loop from (Check the javascript code to find out how). Once that's done you can use the library's "hover" action to loop the segment.

Animation by Rizwan Asghar

<script>
  LottieInteractivity.create({
    player: "#seventhLottie",
    mode:"cursor",
    actions: [
      {
          position: { x: [0, 1], y: [0, 1] },
          type: "loop",
          frames: [45, 60]
      },
      {
          position: { x: -1, y: -1 },
          type: 'stop',
          frames: [0],
      }
    ]
  });
</script>

Sync animation with cursor position

To progress the animation as you move the cursor either on the Lottie or on a given container, you may use the "cursor" mode. This will make the Lottie interactivity based on the cursors movement. Move your cursor on the animation below.

Animation by Motion Jockey

<script>
  LottieInteractivity.create({
    player: '#eighthLottie',
    mode: 'cursor',
    actions: [
      {
          position: { x: [0, 1], y: [0, 1] },
          type: "seek",
          frames: [0, 280]
      }
    ]
  });
</script>

Sync animation with cursor horizontal movement

To progress the animation as you move the cursor horizontally either on the Lottie or on a given container, you may use the "cursor" mode. This will make the Lottie interactivity based on the cursors movement. Move your cursor on the animation below.

Animation by Gabriela Schmitz

<script>
  LottieInteractivity.create({
    player: '#ninthLottie',
    mode: 'cursor',
    actions: [
      {
          position: { x: [0, 1], y: [-1, 2] },
          type: 'seek',
          frames: [0, 180],
      }
    ]
  });
</script>

Play animation on click

This section shows an example of a Lottie that is playing when clicked on. Clicking multiple times won't restart the animation if its already playing. However if you want the animation to restart as soon as it's clicked on set the 'forceFlag' property to true.

Animation by Priyanshu Rijhwani

<script>
  LottieInteractivity.create({
    player: "#tenthLottie",
    mode:"cursor",
    actions: [
      {
          type: "click",
          forceFlag: false
      }
    ]
  });
</script>

Play animation on hover

This section shows an example of a Lottie that is playing when hovered on. Hovering over multiple times won't restart the animation if its already playing. However if you want the animation to restart as soon as it's hovered on set the 'forceFlag' property to true.

Animation by Vitra

<script>
  LottieInteractivity.create({
    player: '#eleventhLottie',
    mode: 'cursor',
    actions: [
      {
          type: "hover",
          forceFlag: false
      }
    ]
  });
</script>

Toggle animation

This section shows an example of a Lottie that is toggled when clicked on.

Animation by Christina Bublyk

<script>
  LottieInteractivity.create({
    player: '#toggleLottie',
    mode: 'cursor',
    actions: [
      {
          type: "toggle"
      }
    ]
  });
</script>

Play animation when visible

This section shows an example of a Lottie that is playing when visible. Visibility can be customised to play the animation when a percentage of the container is reached. Here [0.50, 1.0] means the animation will play when 50% of the container is reached, [0, 1.0] will play as soon as the container is visible.

Animation by Chris Gannon

<script>
  LottieInteractivity.create({
    player: "#twelfthLottie",
    mode:"scroll",
    actions: [
      {
        visibility: [0.50, 1.0],
        type: "play"
      }
    ]
  });
</script>

Play animation on hold

With the 'cursor' mode and 'hold' type the animation will play when the cursor is placed over the animation, and in reverse if the cursor leaves the animation.

Animation by Luca Rondine

<script>
  LottieInteractivity.create({
    player: '#thirteenthLottie',
    mode: 'cursor',
    actions: [
      {
          type: "hold"
      }
    ]
  });
</script>

Play animation on hold (and pause when released)

With the 'cursor' mode and 'pauseHold' type the animation will play when the cursor is placed over the animation, and pause if the cursor leaves the animation.

Animation by Luca Rondine

<script>
  LottieInteractivity.create({
    player: '#fourteenthLottie',
    mode: 'cursor',
    actions: [
      {
          type: "pauseHold"
      }
    ]
  });
</script>

Lottie-interactivity chaining

Lottie-interactivity now possess' the power to chain different segments of animations depending on how the user interacts (click x amount of times, hover..) with the segment but also with Lottie events (onComplete). By using the 'chain' mode Lottie-interactivity can now manage as many segments as you can fit in an animation.

In this example 3 segments are present. The pigeon running on loop, an explosion and the feathers falling. Click on the pigeon to see it in action!

Running pigeon by Christina Bublyk, explosion by Viktor Anisimov, feathers by Daniel Teasdale

<script>
  LottieInteractivity.create({
    player: '#birdExploding',
    mode: 'chain',
    actions: [
      {
          state: 'loop',
          transition: 'click',
          frames: 'bird'
      },
      {
          state: 'autoplay',
          transition: 'onComplete',
          frames: 'explosion'
      },
      {
          state: 'autoplay',
          transition: 'onComplete',
          frames: 'feathers',
          reset: true
      }
    ]
  });
</script>

Configure library

The name of the player ie: 'explodingBird' in this example is the ID set to the lottie-player component on the html page. Interaction chaining can be activated by using the 'chain' mode. An 'actions' array serves to configure each segment and how to interact with it. Multiple objects can be added into this array and therefore multiple different ways to interact and transit through different segments of an animation.

Each object in the actions array should have a 'state' and 'transition' property.

State

State defines how the segment of the animation will be playing when loaded and waiting for an interaction.

State can have the following values:

  • 'autoplay': Plays the animation once on load. Example
  • 'loop': Loops the animation.
  • Optionally a 'loop' property can be defined to loop x amount of times
  • 'click': Plays the animation on click. Example
  • 'hover': Plays the animation on hover. Example
  • 'none': Animation won't play
  • Transition

    Transition defines the interaction that will cause Lottie-Interactivity to go to the next interaction link in the chain.

    Transition can have the following values:

  • 'click': Causes a transition when clicking on the animation is detected. Example
  • Optionally a 'count' property can be defined to transit after x amount of clicks
  • 'hover': Causes a transition when hovering over the animation is detected. Example
  • Optionally a 'count' property can be defined to transit after x amount of hovers
  • 'repeat': Play the animation x amount of times before transiting. Example
  • A 'repeat' property containing a number can then be used to define how many times the animation will repeat before transiting
  • 'hold': Hover over the animation for the length of the 'frames' property to cause a transition. If the cursor leaves the animation, it plays in reverse. Example
  • 'pauseHold': Hover over the animation for the length of the 'frames' property to cause a transition. If the cursor leaves the animation, it pauses. Example
  • 'seek': Sync animation with cursor position. A 'position' object will be needed as well as a 'frames' array. Example
  • 'onComplete': When the animation has finished playing the defined segment, a transition will occur.
  • 'none': Animation won't transit.
  • Frames

    Each link in the interaction chain can have a defined segment of frames to play. The 'frames' array's first value is the start and the second value is the end. If you don't like defining frame numbers, named markers can also be used. More information about named markers here

    If no frames are provided the entirety of the animation is played.

    Path

    A 'path' property can be used to define where to load the animation from.

    Additional properties

  • 'jumpTo: [interaction index]': Jumps to the action defined at the submitted index after the necessary interaction is detected.
  • 'reset: [true/false]': Useful for the last action, if true will go back to the first action.
  • The 'transition' event is fired from the lottie-player element every time a transition occurs. The event contains the following details:
  • oldIndex
  • newIndex
  • 'forceFlag: [true/false]': If true, click and hover interactions will play straight away. Otherwise, will ignore if animation is already playing.
  • 'delay: [time in milliseconds]': Will delay all interactions and playback of the animation until the delay is finished.
  • 'speed: [integer]': Set the speed of the animation, 1 being the default speed.
  • Lottie-interactivity chaining - Click

    In this example the 'forceFlag' property is used with the 'click' state to play the animation as soon as you click on the container and won't wait for the segment to end before playing again.

    When combined with the 'click' transition and a defined number of clicks (here, 5) the star has to be clicked 5 times before getting to the confetti!

    Star by Aneesh Ravi, conffetti by Arvind Lakhani

    <script>
      LottieInteractivity.create({
        player: '#clickPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'click',
              forceFlag: true,
              frames: 'star',
              transition: 'click',
              count: 5
          },
          {
              path: 'https://assets1.lottiefiles.com/packages/lf20_ISbOsd.json',
              frames: 'confetti',
              state: 'autoplay',
              reset: true,
              transition: 'onComplete'
          }
        ]
      });
    </script>

    Lottie-interactivity chaining - Hover

    In this example the 'forceFlag' property is used with the 'hover' state to play the animation as soon as you hover on the container and won't wait for the segment to end before playing again.

    When combined with the 'hover' transition and a defined number of counts (here, 5) the star has to be hovered 5 times before getting to the confetti!

    Star by Aneesh Ravi, conffetti by Arvind Lakhani

    <script>
      LottieInteractivity.create({
        player: '#hoverPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'hover',
              forceFlag: true,
              frames: 'star',
              transition: 'hover',
              path: 'https://assets10.lottiefiles.com/private_files/lf30_rsqq11m6.json',
              count: 5
          },
          {
              path: 'https://assets1.lottiefiles.com/packages/lf20_ISbOsd.json',
              state: 'autoplay',
              reset: true,
              transition: 'onComplete'
          }
        ]
      });
    </script>

    Lottie-interactivity chaining - Repeat

    With the 'repeat' transition the animation will play the number of times you define to the 'repeat' property and then transit to the next action. Here we play the first segment automatically and after repeating the animation twice display the shapes animation.

    Loading shape by Ricardo Figueira, shapes background by Tamojit Das

    <script>
      LottieInteractivity.create({
        player: '#repeatPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'autoplay',
              transition: 'repeat',
              repeat: 2
          },
          {
              path: 'https://assets2.lottiefiles.com/packages/lf20_2m1smtya.json',
              state: 'autoplay',
              frames: [0, 110],
              transition: 'onComplete',
              reset: true,
          }
        ]
      });
    </script>

    Lottie-interactivity chaining - Hold

    The hold transition requires the user to hover over the animation for the defined amount of frames, or if no frames are defined, for the entirety of the animation after which the next action is used. If the user releases the hover over the animation it plays in reverse.

    Tap and hold by LottieFiles, spinner by Jonathon Holden

    <script>
      LottieInteractivity.create({
        player: '#holdPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'none',
              transition: 'hold',
              frames: [0, 170]
          },
          {
              path: 'https://assets4.lottiefiles.com/packages/lf20_7zara4iv.json',
              state: 'autoplay',
              transition: 'onComplete',
              reset: true
          }
        ]
      });
    </script>

    Lottie-interactivity chaining - pauseHold

    The 'pauseHold' transition works in the same way as the 'hold' transition does, the difference being that if the user releases the hold, the animation is paused. The 'pauseHold' transition requires the user to hover over the animation for the defined amount of frames, or if no frames are defined, for the entirety of the animation after which the next action is used. If the user releases the hover over the animation it pauses.

    Tap and hold by LottieFiles, spinner by Jonathon Holden

    <script>
      LottieInteractivity.create({
        player: '#pauseHoldPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'none',
              transition: 'pauseHold',
              frames: [0, 170]
          },
          {
              path: 'https://assets4.lottiefiles.com/packages/lf20_7zara4iv.json',
              state: 'autoplay',
              transition: 'onComplete',
              reset: true
          }
        ]
      });
    </script>

    Lottie-interactivity chaining - Sync and autoplay

    Syncing to the cursor can be achieved by employing the 'seek' transition. In this example we sync the playback of the animation between the frames 0 and 30. Once the animation attains the 30th frame, the next segment of the animation is played automatically due to the 'autoplay' state thus unlocking the phone.

    Animation by Sam Osborne

    <script>
      LottieInteractivity.create({
        player: '#syncPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'none',
              position: { x: [0, 1], y: [-1, 2] },
              transition: 'seek',
              frames: [0, 30],
          },
          {
              state: 'autoplay',
              transition: 'none',
              frames: [30, 160],
          },
        ]
      });
    </script>

    Lottie-interactivity chaining - Load animation dynamically in action

    To save having to manually append animations together and then play segments of the spliced animation, you can define a 'path' in the action and let Lottie-Interactivity load that animation dynamically when the action comes in to play. Here we define three different animations and play through them, click on the first animation to start the chain!

    Target animation by Alex Martov, Confetti animation by David Ukauwa, Well done animation by Dhilip Raju

    <script>
      LottieInteractivity.create({
        player: '#chainLoadPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'click',
              transition: 'onComplete'
          },
          {
              state: 'autoplay',
              transition: 'onComplete',
              path: 'https://assets6.lottiefiles.com/packages/lf20_opn6z1qt.json'
          },
          {
              state: 'autoplay',
              transition: 'onComplete',
              path: 'https://assets9.lottiefiles.com/packages/lf20_pKiaUR.json',
              reset: true
          }
        ]
      });
    </script>

    Lottie-interactivity chaining - jumpTo

    By using 'jumpTo' and an index number we can jump to the indicated action after the current one has finished. In this example after the last action has completed, we jump to the action at index 1, so the triangle segment. Index numbers for jumpTo start at 0 and not 1. Click the example below to get started, can you guess which character goes missing ?

    Animation by Sam Osborne

    <script>
      LottieInteractivity.create({
        player: '#jumpToPlayer',
        mode: 'chain',
        actions: [
          {
              state: 'click',
              frames: 'circle',
              transition: 'onComplete',
          },
          {
              state: 'autoplay',
              frames: 'triangle',
              transition: 'onComplete',
          },
          {
              state: 'autoplay',
              frames: 'square',
              transition: 'onComplete',
          },
          {
              state: 'autoplay',
              frames: 'brocolli',
              transition: 'onComplete',
              jumpTo: 1
          }
        ]
      });
    </script>

    Find thousands of free animations for you to make interactive!

    Browse animations