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 is0
when the top of the element is at the bottom of the viewport and1
when the top of the element is at the top of the viewport. -
bottom
Percent is0
when the bottom of the element is at the bottom of the viewport and1
when the bottom of the element is at the top of the viewport. -
height
Percent is0
when the top of the element is at the bottom of the viewport and1
when the bottom of the element is at the bottom of the viewport. -
visible
Percent is0
when the top of the element is at the bottom of the viewport and1
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 between0
and1
). -
callback
A custom function can be passed and should return a boolean. Arguments:element
,percent
,visible
.
-
-
visibleBefore
-
false
(default) Not visible before thetarget
is met. -
true
Always visible before thetarget
is met.
-
-
visibleAfter
-
true
(default) Always visible after thetarget
is met. -
false
Not visible after thetarget
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();