Anime-scrolltrigger NPM

Anime-ScrollTrigger

Features

Trigger animation when scroller offset intersects with trigger element.
Support Scroll Triggering without the need of using animation ( i.e you can still use scroll trigger when you don't want to animate)
Pinning trigger element
Option for linear interpolation of animation based on scroll. i.e, trigger animation state based on scroll
Debugging the offset markers.
Calculates offsets using boundingClientRect and scrollTop instead of using Intersection Observer.

Demo codepen: https://codepen.io/Zaw-Lin-Tun-the-encoder/pen/vYbervK

Introduction

Anime-ScrollTrigger is a library which is aimed to animate on scroll just like ScrollTrigger. Some name conventions would be different but the logic is pretty similar.

I strongly recommend you to use that library because it is awesome and maintained.

I don’t know how exactly that library is implemented in the context of coding. I only have abstract ideas of that library and tried to create my own one based on those ideas.

💡 The animation system of this library is solely dependent on animejs library.

Most of usages are similar to ScrollTrigger . Please have a look at the following instructions.

Understanding How Trigger Works

It's important to know that there are two types of trigger offsets ( trigger positions ):

trigger element: start offset startTriggerOffset and end offset endTriggerOffset:
Offsets are calculated on height of the trigger element relative to the top of the trigger element. You can change the value with first word of start or end attribute under scrollTrigger attribute.
scroller/container element: start offset startScrollerOffset and end offset endScrollerOffset.
Offsets are calculated relative to clientHeight of the scroller element. You can change the value with second word of start or end attribute under scrollTrigger attribute.

Trigger will start when startTriggerOffset meets startScrollerOffset. Trigger will end when endTriggerOffset meets endScrollerOffset. For example,

...
scrollTrigger: {
   start: 'top bottom', 
   end: '10% bottom',
}

The above values indicate that

animation will start when the top of trigger element and the bottom end of scroller meets.
animation will end when 10% of the trigger element height + top of trigger element and bottom end of scroller meets.

Changelogs

Read Changelog here

Installation

Use npm

npm install anime-scrolltrigger

Or cdn

import AnimeScrollTrigger from 'https://cdn.jsdelivr.net/npm/anime-scrolltrigger@{enter version e.g, 0.1.0}/dist/anime-scrolltrigger.es.js';

Usages

Import `AnimeScrolltrigger`

import AnimeScrollTrigger from 'anime-scrolltrigger'

Create an instance.

container: Scroller HTML element
animations: Array of animation object

let container = document.getElementById('container');
let boxes = document.querySelectorAll('.box')
let animations = [
    {
        targets: boxes[0],
        translateX: 100,
        easing: 'linear',
        scrollTrigger: {
            trigger: boxes[0],
            start: 'top 3%',
            end: 'bottom 30%',
        }
    }, {
        targets: boxes[1],
        backgroundColor: '#a993ff',
        easing: 'linear',
        scrollTrigger: {
            trigger: boxes[1],
            start: 'top 40%',
            end: 'bottom center',
            lerp: true,
        }
    }];

new AnimeScrollTrigger(container, animations);

Animation

Animation object has the following structure.

targets (optional) : HTML elements to animate
attributes (optional) which you want to animate ( same as animejs) - for example
```
{
  translateX: 100,
  backgroundColor: 100,
  ...
}
```
scrollTrigger: scroll trigger object

Example Animation Object

{
    targets: boxes[1], 
    backgroundColor: '#a993ff',
    easing: 'linear',
    scrollTrigger: {
    ...
    }
}

Scroll Trigger

trigger: HTMLElement
start: String
Indicate where startTriggerOffset of trigger element will intersect with startScrollerOffset of scroller element and when it intersects, animation will * *start**. Format is "start-trigger-offset start-scroller-offset". Default value is "top center".
Offset can be provided as percentage (e.g. 10%, 20%, -5%) or constant values: top, center, bottom.
end: String
Indicate where endTriggerOffset will intersect with endScrollerOffset and when it intersects, animation will end .
Format is "end-trigger-offset end-scroller-offset". Default value is "bottom center".
Offset can be provided as percentage (e.g. 10%, 20%, -5%) or constant values: top, center, bottom.
actions: String
Action behavior when a certain event is triggered. Format is "on-enter-action on-leave-action on-enter-back-action on-leave-back-action". Default value is "play none none reverse".
Note: when lerp is enabled, user-defined on-enter-action and on-enter-back-action will be ignored which means that animation will be forwarded on scrolling down and backwarded on scrolling up.
lerp: Boolean
Lerp ( linear interpolation) enables progressive transition of animation which means that animation state will be triggered based on scroll position instead of triggering at once when scroller reach trigger start offset.
pin: Boolean or String or HTMLElement
Pinning will pin the trigger element to the top of container element. Pinning state will start when it reaches animation-trigger-start-offset and ends when it reaches animation-trigger-end-offset.
A pinned element should exist equal or below top of the trigger element so that it will pin the element when trigger element is reached.
debug: Boolean or Object
Indicate to show start offset markers and end offset markers in order to see where they are located visually. You can pass object in order to change markers color.
```
debug: { 
   startTriggerOffsetMarker: '#f6a945',
   endTriggerOffsetMarker: '#ffd291',
   startScrollerOffsetMarker: '#4b45f6',
   endScrollerOffsetMarker: '#d5d4ff',
}
```
events: Object
Events triggered on scroll.
- onEnter:
- onLeave:
- onEnterBack:
- onLeaveBack:
- onUpdate:

Example scroll trigger object is

{
    trigger: boxes[1],
    start: 'top 40%',
    end: 'bottom center',
    lerp: true,
    debug: true,
    pin: false,
    actions: 'play none none reverse',
    events:
        { // Scroll Trigger Events
            onEnter: (trigger) => {},
            onLeave: (trigger) => {},
            onEnterBack: (trigger) => {},
            onLeaveBack: (trigger) => {},
            onUpdate: (trigger,progress) => {},
        }
}

Examples

simple-boxes

Tips and mistakes

Sometimes when the animation is not working, make sure that container element you provided is actually scrolling. You may want to listen to scroll event of that element.
```
container.addEventListener('scroll',()=>console.log('yay scrolling'))
```
The start-intersection-trigger-offset needs to be lower than end-intersection-trigger-point offset. If it is not, animation/ triggering won't work.
Incorrect trigger offsets could probably happen because of initializing trigger before dom tree hasn't completed building yet. So workaround might be setting timeout.
```
setTimeout(()=>{
  new AnimeScrollTrigger(element,animations)
},300)
```

TO-DO

configurable marker colors
pin option
- it should pin the target element to trigger element until it reaches animation-end-offset
test on horizontal scroll