@curiousmedia/scrollpercent

    2.0.1 • Public • Published

    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();

    Keywords

    none

    Install

    npm i @curiousmedia/scrollpercent

    DownloadsWeekly Downloads

    26

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    36 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar