@curiousmedia/scrollpercent
v2.0.3
Published
Attach events to elements and fire on window / scroll
Downloads
2
Keywords
Readme
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 triggeredfalse
Element is inactive and cannot be triggered
visibleBehavior
Method used to determine percentagetop
(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 oncealways
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();