Ilottie NPM | npm.io

iLottie

iLottie is a framework made to create complex interactive animations. Under the hood it operates images and Lottie animations to create one nice interactive experience.

Who is this project for?

iLottie is intended to be used by designers who are already familiar with Lottie.

Intro

Installation

Content of YAML file

Installation

instructions for installation will go here

Usage

iLottie uses a single yaml configuration file to do its magic.

Example of YAML file

surfaceWidth: 1000
surfaceHeight: 1000

onExternalValue:
  - min: 0
    max: 500
    actions:
      - type: show
        components: [background]
        animationFunction: ease-in
        animationDuration: 1000
      - type: show
        components: [lottie11]
        animationFunction: ease-in
        animationDuration: 1000
  - min: 500
    max: 1000
    actions:
      - type: hide
        components: [background]
        animationFunction: ease-out
        animationDuration: 1000
resources:
  - name: background
    type: svg
    src: https://picsum.photos/1000/1000?grayscale&blur=2
  - name: lottie 1
    type: lottie
    src: animations/myLottieAnimation.json
  - name: pointRed
    type: svg
    src: test_images/pointRed.svg
  - name: pointGreen
    type: svg
    src: test_images/pointGreen.svg
  - name: pointWithImage
    type: png
    src: https://picsum.photos/200/300
components:
  - name: background
    posRect: {x: -100, y: -100, width: 1200, height: 1200}
    zIndex: 0
    resource: background
  - name: stopLottie
    posRect: {x: 900, y: 900, width: 100, height: 100}
    zIndex: 2
    resource: pointRed
    onClick:
      - type: pause
        delay: 0
        components: [lottie11]
    onHoverIn:
      - type: setStyles
        delay: 0
        components: [stopLottie]
        styles: {
          transform: scale(1.1),
          transition: transform 0.3s ease-in
        }
    onHoverOut:
      - type: setStyles
        delay: 0
        components: [stopLottie]
        styles: {
          transform: scale(1),
          transition: transform 0.3s ease-in
        }
  - name: startLottie
    posRect: {x: 0, y: 900, width: 100, height: 100}
    zIndex: 2
    resource: pointGreen
    onClick:
      - type: play
        delay: 0
        count: 2
        components: [lottie11]
    onHoverIn:
      - type: setStyles
        delay: 0
        components: [startLottie]
        styles: {
          transform: scale(1.1),
          transition: transform 0.3s ease-in
        }
    onHoverOut:
      - type: setStyles
        delay: 0
        components: [startLottie]
        styles: {
          transform: scale(1),
          transition: transform 0.3s ease-in
        }
  - name: lottie11
    posRect: {x: 0, y: 0, width: 500, height: 500}
    zIndex: 1
    resource: lottie 1
    onShow:
      - type: show
        delay: 1000
        components: [stopLottie]
        animationFunction: ease-in
        animationDuration: 1000
        playingTurn: playWithPrevious
      - type: show
        delay: 0
        components: [startLottie]
        animationFunction: ease-in
        animationDuration: 1000
        playingTurn: playAfterPrevious
    onEnd:
      - type: show
        delay: 0
        components: [pointWithImage]
        animationFunction: ease-in
        animationDuration: 1000
        playingTurn: playWithPrevious
  - name: pointWithImage
    posRect: {x: 0, y: 0, width: 100, height: 100}
    zIndex: 1
    resource: pointWithImage

Content of YAML file

On the highest level, configuration file contains the following sections (more details below):

surfaceWidth: number; defines the width of the interactive area. Relative units: all the sizes for all the components will be scaled with respect to this value.
surfaceHeight: number; same as surfaceWidth, but for height.
onExternalValue: this section describes, what actions must be triggered for certain external trigger values. The external trigger could be a scroll position or any other meaningful parameter, that is used to control animations from outside of iLottie component.
resources: contains the list of all the content files(images, Lottie animations .json files) used for the iLottie animation and their paths.
components: main part of the YAML file. Describes all the components participating in the iLottie animation, their behavior and interactions.

onExtenralValue

This section contains a list of objects of the following shape:

  min: 0
  max: 500
  actions: <list of actions>

This section can be used for 2 purposes: control flow of iLottie animation from outside and to define initial animation state(see below).

Min and max are numbers >= 0. Max accepts Inifinity value which suits best when some action must be executed only once(e.g. "show" action for the background that must appear once and then never disappear).

Whenever external trigger value enters the range between min and max, all the corresponding actions will be executed.

Default value for the external trigger is 0. This section would be the right place to describe, what components should appear on load. To do so, it's enough to include one section with min = 0.

Example

- min: 0
  max: Infinity
  actions:
    - type: show
      components: [background]

resources

Describes all the content that is used for the current animation. Contains list of object of the following shape:

  - name: <name_of_content>
    type: <type of content>
    src: <path_to_the_content>

name is a string containing name of the content. It must be unique. Content is referenced from "components" section. Multiple components can be created for each of the content files.

type describes type of the content. The following types are currently supported: svg, png, lottie. This field must be specified carefully, as the kinds of actions possible for images and lottie animations are different and are defined by this field.

src is a path to the content. Can be either relative to public folder of this repository or absolute external URL.

Example 1: relative path: public folder contains an images folder that contains file pointGreen.svg

  - name: pointGreen
    type: svg
    src: images/pointGreen.svg

Exampe 2: external URL

  - name: pointWithImage
    type: png
    src: https://picsum.photos/200/300

components

The heart and soul of the YAML file. Describes all the components that are part of the current iLottie animation.

This section contains list of object of the following shape:

  name: <name_of_component>
  posRect: { x: 0, y: 900, width: 100, height: 100 }
  zIndex: 1
  resource: <name_of_content>
  onClick: <list_of_actions>
  onSecondClick: <list_of_actions>
  onHoverIn: <list_of_actions>
  onHoverOut: <list_of_actions>
  onShow: <list_of_actions>
  onHide: <list_of_actions>
  onEnd: <list_of_actions>
  onPlay: <list_of_actions>
  playWithExternalValue: <list_of_actions>

name, posRect, zIndex and content are required in order to create a visible component. All the actions handlers (onClick, onSecondClick, etc.) are optional.

name is the name of the component. Must be unique within components section.

posRect defines size and position of the component. These values are scaled with respect to surfaceWidth and surfaceHeight.

The origin (0, 0) is in the top-left corner, with Y axis pointing down and X axis pointing to the right.

x, y, width and height can be negative as well as go higher than the surfaceWidth and surfaceHeight values.

Example Let's say we have defined surfaceWidth: 1000 and surfaceHeight: 1000.

This value of posRect defines a square taking 10% of the container's height and width positioned at the origin - top-left corner:

  posRect: {x: 0, y: 0, width: 100, height: 100}

Why do I need values below 0 or higher than surfaceWidth/surfaceHeight?

It is not easy to create a truly responsive animation that is fully visible across all screen sizes. Either you make it fully visible and then have empty spaces on the sides of animation or you stretch the animation and make it disproportional or cropped.

There is however an in-betweem solution: create a high-resolution background image that goes beyond the borders of iLottie animation area defined by surfaceWidth and surfaceHeight. Then you can use that background image as the cover (that would scale well on big screen sizes) and make the active animation part fully fisible (contain).

zIndex: defines z-index of the component. You can define stack order of the components in your animation. Defaults to 0.

content: name of corresponding content. This field must match one of the content names inside resources section.

Example: note that the content's name and the component's content are the same

resources:
  - name: background
    type: png
    src: images/background.png
components:
  - name: mainBackground
    posRect: {x: -100, y: -100, width: 1200, height: 1200}
    zIndex: 0
    resource: background

onClick: contains a sequence of actions that must be executed when the component is clicked. Can be combined with onSecondClick to achieve toggle effect, e.g. show another component on first (odd) click and then hide that other component on second (even) click.

onSecondClick: contains a sequence of actions that must be executed when component is clicked for the second (even) time.

onHoverIn: contains a sequence of actions that must be executed when component is moused over, i.e. cursor is positioned within the boundaries of the component. Can be combined with onHoverOut.

onHoverOut: contains a sequence of actions that must be executed when the cursor leaves the boundaries of the component.

onShow: contains a sequence of actions that must be executed when component is shown.

Important note: actions in this list are executed immediately after the show action for the component is executed, without waiting until the animation is played to the end. So, if some action must be performed after the show animation is finished aka component is fully in view, delay must be added (see more about the delay below in the action section).

Example 1: Imagine we have a lottieAnimation component that was revealed through the show action with the duration of 1000ms. The lottieAnimation will start to plau immediately after the show action was executed, i.e. animation will be already playing while it is fading in.

components:
  - name: lottieAnimation
      posRect: { x: 0, y: 0, width: 1000, height: 1000 }
      zIndex: 3
      resource: lottieAnimation
      onShow:
        - type: play
          components: [lottieAnimation]

Example 2: Imagine we want to hide element after it was shown. If we used onShow action without a delay, we would never see the component appear, as the hide action would be called immediately after the show. Hence, a delay must be added(>= than the duration of show action).

components:
  - name: blinkingButton
    posRect: { x: 0, y: 0, width: 100, height: 100 }
    zIndex: 1
    resource: blinkingButton
    onShow:
      - type: hide
        components: [blinkingButton]
        delay: 1000

onHide: contains a sequence of actions that must be executed when component is hidden.

Same rules as for onShow apply: if the desired action must be executed after the hide action is finished, a delay must be added.

onEnd: contains a sequence of actions that must be executed whenever some action, for which current component is a target, is finished. Unlike onShow and onHide, actions in this sections will be executed after the animation is finished.

Note: actions in this list will be executed every time any action for the current component is finished. So, if the component is first shown via show action and then hidden via hide action, onEnd actions will be triggered both times.

Note: when you add onEnd actions to a component, DO NOT make this component one of action's components; this will cause an infinite loop, as actions in this list will be called every time the previous action is finished.

Example: safe

components:
- name: button1
  posRect: { x: 0, y: 0, width: 100, height: 100 }
  zIndex: 1
  resource: button
  onEnd:
    - type: hide
      components: [blinkingButton]
      delay: 1000

Example: bad, infinite loop, button1 will keep calling hide action

components:
- name: button1
  posRect: { x: 0, y: 0, width: 100, height: 100 }
  zIndex: 1
  resource: button
  onEnd:
    - type: hide
      components: [button1]
      delay: 1000

onPlay: contains a sequence of actions that must be executed when component has started playing a Lottie animation. Should be applied to lottie components only; on images it has no effect.

playWithExternalValue (not yet implemented): specifies an action for playing a Lottie animation along with the external trigger. Is intended to connect animation playback with scroll position or other external trigger.

Action

Actions define what happens to each of your components. Whether you want to show or hide a component, play a Lottie animation or add some styles to one of your components - you need to define an action for that.

Every action is an object of the following shape:

  type: hide
  components: [background]
  delay: 1000
  playingTurn: playWithPrevious
  styles: {}
  animationFunction: ease-in
  animationDuration: 0
  segments: [[0, 100]]
  count: 1

type: defines the type of action, i.e. what exactly will happen to the component. Currently the following action types are supported:

show: reveals the component that was not visible(fade in)
hide: hides the component(fade out)
play: plays the Lottie animation. Only for lottie content type
pause: stops the Lottie animation. Only for lottie content type
setStyles: updates styles of the component.

components: array of the components that are the targets of the current action. If you want to perform an action on the same component the action is defined for, add the component itself in the list.

Example: This action shows 3 different button components with duration of 300 ms and delay of 500ms.

- type: show
  components: [button1, button2, myFancyButton]
  delay: 500
  animationDuration: 300
  animationFunction: ease-in

delay: delay before the start of animation in milliseconds. Defaults to 0.

playingTurn: defines whether the action should be executed together with the previous action in the list or after the previous action is finished. Accepts 2 values: playWithPrevious and playAfterPrevious. Always refers to the previous action in the list. By changing this field and order of actions in the list, various desirable results can be achieved. Defaults to playWithPrevious.

Example: this list of actions shows button1 and button2 components at the same time, and then shows two more buttons button3 and button4 after the first 2 are fully shown.

  - type: show
    components: [button1, button2]
    animationDuration: 300
    animationFunction: ease-in
    playingTurn: playWithPrevious
  - type: show
    components: [button3]
    delay: 300
    animationDuration: 300
    animationFunction: ease-in
    playingTurn: playAfterPrevious
  - type: show
    components: [button4]
    animationDuration: 300
    animationFunction: ease-in
    playingTurn: playWithPrevious

styles: can be used only with setStyles action type!. Contains an object with regular CSS properties.

Example

- type: setStyles
  components: [button]
  styles: {
    transform: scale(1.1),
    transition: transform 0.3s ease-in
  }

animationFunction: can be used only with show and hide action types!. Defines transition timing function . Defaults to ease-in.

animationDuration: can be used only with show and hide action types!. Defines duration of the animation in milliseconds. Defaults to 0.

segments: can be used only with play action type!. Contains list of Lottie animation segments to play. Each segment is also a list of 2 values, representing the start and the end (the first and the last frame) of the animation fragment.

If segments field is missing, animation is played from the first to the last frame.

Example: this action would play a corresponding Lottie animation from frame 80 to frame 120 and then play it in the reverse direction.

- type: play
  components: [lottieAnimation]
  segments: [[80, 120], [120, 80]]
  playingTurn: playAfterPrevious

count: can be used only with play action type!. Defines number of times the animation must be played. Defaults to 1. Accepts Infinity.

Must be used carefully: if you want to execute another action with playingTurn: playAfterPrevious after play action with count >= 1, this next action will start only after the animation is played count times. If count: Infinity is used, the next action will be executed only if the playing animation is paused by some other action, otherwise it will play forever and the next action will never be executed.

Example 1: play action is played once, then the next hide action is executed. Note that setting count: 1 is optional, as it's the default value

- type: play
  components: [lottieAnimation]
  count: 1
- type: hide
  components: [lottieAnimation]
  delay: 500
  playingTurn: playAfterPrevious

Example 2: play action is played three times, then the next hide action is executed.

- type: play
  components: [lottieAnimation]
  count: 3
- type: hide
  components: [lottieAnimation]
  delay: 500
  playingTurn: playAfterPrevious

Example 3: play action is played infinitely. The next hide action will not be executed until the lottieAnimation is stopped from some other action in your config file.

- type: play
  components: [lottieAnimation]
  count: Infinity
- type: hide
  components: [lottieAnimation]
  delay: 500
  playingTurn: playAfterPrevious