@curiousmedia/scrollpercent v2.0.3

Scroll Percent

Javascript library for handling triggered and contonious scroll animations within the context of the viewport.

Triggerable elements are declared to the script. As the user scrolls or resizes their browser, the script will use the scroll position, element position, and viewport size to determine if the element is visible (a percent between 0 and 1). If the element is visible, it will trigger a custom method for initiating an animation or other visual effects. The method of calculating the visiblity of an element, target percentage, and trigger behavior are configurable.

Installation

npm install @curiousmedia/scrollpercent 

Usage

Basic

import '@curiousmedia/scrollpercent';

let sp = new ScrollPercent();
sp.add('a', document.querySelector('.a'), {
    target: 0,
    origin: 'top',
    triggerBehavior: 'once',
    triggerAfter: true,
    callback: function(element, percent, trigger) {
        console.log('trigger animation');
    }
})

When the top of the element is visible in the viewport, the callback will trigger.

Target

import '@curiousmedia/scrollpercent';

let sp = new ScrollPercent();
sp.add('a', document.querySelector('.a'), {
    target: 0.5,
    origin: 'top',
    triggerBehavior: 'once',
    triggerAfter: true,
    callback: function(element, percent, trigger) {
        console.log('trigger animation');
    }
})

When the top of the element is 50% in the viewport, the callback will trigger.

Scroll animations

import '@curiousmedia/scrollpercent';

let sp = new ScrollPercent();
sp.add('a', document.querySelector('.a'), {
    target: 0,
    origin: 'top',
    triggerBehavior: 'during',
    triggerAfter: false,
    callback: function(element, percent, trigger) {
        console.log(percent);
    }
})

When the element is visible in the viewport, the callback will be give a percent to base animations off of.

Options

• active
  • true (default) Element is active and can be triggered
  • false Element is inactive and cannot be triggered
• visibleBehavior Method used to determine percentage
  • top (default) Percent is 0 when the top of the element is at the bottom of the viewport and 1 when the top of the element is at the top of the viewport.
  • bottom Percent is 0 when the bottom of the element is at the bottom of the viewport and 1 when the bottom of the element is at the top of the viewport.
  • height Percent is 0 when the top of the element is at the bottom of the viewport and 1 when the bottom of the element is at the bottom of the viewport.
  • visible Percent is 0 when the top of the element is at the bottom of the viewport and 1 when the bottom of the element is at the top of the viewport.
  • callback A custom function can be passed and should return a number. Argument: element.
• triggerBehavior
  • once (default) Element callback can only be triggered once
  • always Element callback is triggered on every resize or scroll event.
  • reverse Element can only be triggered if an element changes from visible to invisible or vise versa.
  • during Element can only be triggered if it is currently visible (percent is between 0 and 1).
  • callback A custom function can be passed and should return a boolean. Arguments: element, percent, visible.
• visibleBefore
  • false (default) Not visible before the target is met.
  • true Always visible before the target is met.
• visibleAfter
  • true (default) Always visible after the target is met.
  • false Not visible after the target is met.
• target
  • 0 (default) Trigger when element immediate becomes visible. Should typically be a number between 0-1, however, other numbers are accepted.
  • callback A custom function can be passed and should return a boolean. Arguments: element, percent.

• callback Custom function to call when element is triggered. Arguments: element, percent, visible.

Methods

Add element

sp.add('a', document.querySelector('.a'), {});

Disable all elements

sp.active = false;

Disable element

sp.update('a', {
    active: false
});

Refresh of all elements

Only an update to the scrollY and viewport will trigger a refresh. A refresh is recommended when adding, removing, or manipulating elements.

sp.refresh();

Force refresh of all elements

Recalculate the scrollY and viewport and refresh.

sp.forceRefresh();

Refresh of an element

sp.refreshElement(sp.find('a'));

Destroy instance

sp.destroy();