Awesome JavaScript Library For Magical Scroll Interactions - ScrollMagic

File Size: 1.46 MB
Views Total: 23688
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
Awesome JavaScript Library For Magical Scroll Interactions - ScrollMagic

ScrollMagic is an awesome jQuery animation JS library that allows you to do lots of cool stuff when scrolling down/up your web & mobile page.

With ScrollMagic plugin, you can...

  • Start an animation at a specific scroll position.
  • Synchronize an animation to the scrollbar movement.
  • Pin an element at a specific scroll position (sticky elements).
  • Pin an element for a limited amount of scroll progress (sticky elements).
  • Easily add a parallax effect to your website.
  • Create an infinitely scrolling page (ajax load of additional content).
  • Call functions when the user hits certain scroll positions or react in any other way to the current scroll position.

How to use it:

1. Install & download the ScrollMagic.

# NPM
$ npm install scrollmagic  --save

2. Import the core JavaScript ScrollMagic.min.js and plugins of your choice into the document. All available plugins:

  • animation.gsap.min.js: Requires GSAP. This plugin is meant to be used in conjunction with the Greensock Animation Plattform. It offers an easy API to trigger Tweens or synchronize them to the scrollbar movement. Both the 'lite' and the 'max' versions of the GSAP library are supported. The most basic requirement is 'TweenLite'.
  • animation.velocity.min.js: Requires velocity.js. This plugin is meant to be used in conjunction with the Velocity animation framework. It offers an easy API to __trigger__ Velocity animations.
  • debug.addIndicators.min.js: This plugin was formerly known as the ScrollMagic debug extension. It enables you to add visual indicators to your page, to be able to see exactly when a scene is triggered.
  • jquery.ScrollMagic.min.js: Requires jQuery library. This plugin is meant to be used in conjunction with jQuery. It enables ScrollMagic to make use of jQuery's advanced selector engine (sizzle) for all elements supplied to ScrollMagic objects, like scroll containers or trigger elements. ScrollMagic also accepts jQuery elements for all methods that expect references to DOM elements. Please note, that in most cases the first element of the matched set will be used. Additionally it provides the ScrollMagic object within the jQuery namespace, so it can be accessed using '$.ScrollMagic'.
<!-- Core -->
<script src="/path/to/ScrollMagic.min.js"></script>
<!-- Plugins -->
<script src="/path/to/plugins/animation.gsap.min.js"></script>
<script src="/path/to/plugins/animation.velocity.min.js"></script>
<script src="/path/to/plugins/debug.addIndicators.min.js"></script>
<script src="/path/to/plugins/jquery.ScrollMagic.min.js"></script>

3. Initialize the library on a controller element and define scenes as follows.

var controller = new ScrollMagic.Controller({
    // optione here
});

var scene = new ScrollMagic.Scene({
    // options here
})

controller.addScene(scene);

4. Possible options for the controller.

var controller = new ScrollMagic.Controller({

    // A selector, DOM object that references the main container for scrolling.
    container: window,

    // Sets the scroll mode to vertical (`true`) or horizontal (`false`) scrolling.
    vertical: true,

    // These options will be passed to every Scene that is added to the controller using the addScene method.
    globalSceneOptions: {},

    // Loglevel for debugging. Note that logging is disabled in the minified version of ScrollMagic.
    // `0` => silent
    // `1` => errors
    // `2` => errors, warnings
    // `3` => errors, warnings, debuginfo
    loglevel: 2,

    // Some changes don't call events by default, like changing the container size or moving a scene trigger element.  
    // This interval polls these parameters to fire the necessary events.  
    // If you don't use custom containers, trigger elements or have static layouts, where the positions of the trigger elements don't change, you can set this to 0 disable interval checking and improve performance.
    refreshInterval: 100

});

5. Possible options for the Scene.

var scene = new ScrollMagic.Scene({

    // The duration of the scene. 
    // number|string|function
    duration: 0,

    // Offset Value for the Trigger Position. 
    // If no triggerElement is defined this will be the scroll distance from the start of the page, after which the scene will start.
    offset: 0,

    // Selector or DOM object that defines the start of the scene. 
    // If undefined the scene will start right at the start of the page (unless an offset is set).
    triggerElement: null,

    // Can be a number between 0 and 1 defining the position of the trigger Hook in relation to the viewport.  
    // "onEnter" => 1
    // "onCenter" => 0.5
    // "onLeave" => 0
    triggerHook: 'onCenter',

    // Should the scene reverse, when scrolling up?
    reverse: true, 

    // Loglevel for debugging.
    loglevel: 2

})

6. API methods.

// Add one ore more scene(s) to the controller.  
// his is the equivalent to Scene.addTo(controller).
controller.addScene(scene);
controller.addScene(new ScrollMagic.Scene({duration : 0}));

// Remove one ore more scene(s) from the controller.  
// This is the equivalent to Scene.remove().
controller.removeScene(scene);
controller.removeScene([scene, scene2, scene3]);

// Update one ore more scene(s) according to the scroll position of the container.  
// This is the equivalent to Scene.update().  
// The update method calculates the scene's start and end position (based on the trigger element, trigger hook, duration and offset) and checks it against the current scroll position of the container.  
// It then updates the current scene state accordingly (or does nothing, if the state is already correct) – Pins will be set to their correct position and tweens will be updated to their correct progress.  
// **Note:** This method gets called constantly whenever Controller detects a change. The only application for you is if you change something outside of the realm of ScrollMagic, like moving the trigger or changing tween parameters._
controller.updateScene(scene);
controller.updateScene(scene, true); // update the controller immediately
controller.updateScene([scene1, scene2, scene3]);

// Updates the controller params and calls updateScene on every scene, that is attached to the controller.  
// In most cases you will not need this function, as it is called constantly, whenever ScrollMagic detects a state change event, like resize or scroll.  
// The only application for this method is when ScrollMagic fails to detect these events.  
// One application is with some external scroll libraries (like iScroll) that move an internal container to a negative offset instead of actually scrolling. In this case the update on the controller needs to be called whenever the child container's position changes.
// For this case there will also be the need to provide a custom function to calculate the correct scroll position. See `Controller.scrollPos()` for details.
controller.update();
controller.update(true); // update the controller immediately

// Scroll to a numeric scroll offset, a DOM element, the start of a scene or provide an alternate method for scrolling.  
// For vertical controllers it will change the top scroll offset and for horizontal applications it will change the left offset.
controller.scrollTo(100);
controller.scrollTo("#anchor");
controller.scrollTo(scene);
controller.scrollTo(100, "my message");
controller.scrollTo(function (newScrollPos, callback) {
  // with callback
});

// **Get** the current scrollPosition or **Set** a new method to calculate it.  
// **GET**:
// When used as a getter this function will return the current scroll position.  
// To get a cached value use Controller.info("scrollPos"), which will be updated in the update cycle.  
// For vertical controllers it will return the top scroll offset and for horizontal applications it will return the left offset.
// **SET**:
// When used as a setter this method prodes a way to permanently overwrite the controller's scroll position calculation.  
// A typical usecase is when the scroll position is not reflected by the containers scrollTop or scrollLeft values, but for example by the inner offset of a child container.  
// Moving a child container inside a parent is a commonly used method for several scrolling frameworks, including iScroll.  
// By providing an alternate calculation function you can make sure ScrollMagic receives the correct scroll position.  
// Please also bear in mind that your function should return y values for vertical scrolls an x for horizontals.
// get the current scroll Position
var scrollPos = controller.scrollPos();
// set a new scroll position calculation method
controller.scrollPos(function () {
  return this.info("vertical") ? -mychildcontainer.y : -mychildcontainer.x
});

// Get all infos or one in particular about the controller.
// returns the current scroll position (number)
var scrollPos = controller.info("scrollPos");
// returns all infos as an object
var infos = controller.info();

// **Get** or **Set** the current loglevel option value.
// get the current value
var loglevel = controller.loglevel();
// set a new value
controller.loglevel(3);

// **Get** or **Set** the current enabled state of the controller.  
// get the current value
var enabled = controller.enabled();
// disable the controller
controller.enabled(false);

// Destroy the Controller, all Scenes and everything.
// without resetting the scenes
controller = controller.destroy();
// with scene reset
controller = controller.destroy(true);

Changelog:

v2.0.8 (2020-08-15)

  • Added support for GSAP JavaScript animation library 3.

v2.0.7 (2019-05-07)

  • Fixed error in Safari when using setPin
  • Added missing semi-colon to isMobile regex
  • Fixed SVG element detection as Dom Element and related Error on Safari
  • Fixed code selection in examples
  • Pass Scene as this to duration callback
  • Increase fps limit for mobile support(advance) example.
  • Added documentation for responsive duration (e.g. "100%")
  • Updated Section Wipes (natural) to work for large number of sections.
  • Removed warning for pushFollowers in pins with duration 0, unless actively set to true.
  • Fixed some spelling stuff.

v2.0.6 (2018-10-20)

  • Bugfixes

v2.0.5 (2015-04-30)

  • Fixed: a JS error occurred in IE9 see here
  • Fixed: cascading pins of absolutely positioned elements didn't work see here
  • Fixed: scene state wasn't correct at start position see here
  • Fixed: updatePinState was called before scrollOffset update

v2.0.4 (2015-04-08)

  • fixed JS error in IE9

v2.0.0 (2015-02-26)

  • removal of all dependencies (jQuery & GSAP) – ScrollMagic is now stand-alone.
  • new file structure
  • new scene event: add fires when scene is added to a controller
  • new scene event: remove fires when scene is removed from a controller
  • option changes in Scene.addIndicators()
  • several performance tweaks
  • lots more info and warning messages (in the uncompressed development version)

v1.3.0 (2014-11-13)

  • changed AMD loader behavior to export only one object -> {Controller: ScrollMagic, Scene: ScrollScene}
  • added Error message for missing dependencies
  • fixed bubbling of pseudo-resize event of div containers
  • reference bug with AMD loading

v1.2.3 (2014-10-25)

  • fixed: reference bug when using asynchronous loading

v1.2.2 (2014-10-21)

  • fixed: Error message with wrong loading order

v1.2.0 (2014-10-16)

  • AMD loader support
  • added warning for tweens being overwritten
  • better code for mobile clicks 
  • updated draw example to camel case to support Firefox
  • updated parralax sections example to moving divs instead of background position
  • added new references
  • added favicon
  • scroll momentum increased in Firefox over fixed elements 
  • parallax example was juggy in Firefox and Safari -> removed reliance of TweenMax ticker in favor of requestAnimationFrame 
  • bugfix for pinned elements jittering if inside a container, because of the delayed position update in refreshInterval
  • bugfix: div resize event bubbled up to window

v1.1.2 (2014-09-16)

  • fixed a bug with the scrollTo method

v1.1.1 (2014-09-04)

  • Major update.

v1.0.9 (2014-08-19)

  • added new feature `ScrollMagic.scrollTo()`

v1.0.8 (2014-05-27)

  • Feature: add class for pinned element during pin

v1.0.7 (2014-04-15)

  • feature: ScrollScene.startOffset

v1.0.6 (2014-04-05)

  • fixed a bug concerning relative sizing of pinned elements

v1.0.5 (2014-03-24)

  • updates.

This awesome jQuery plugin is developed by janpaepke. For more Advanced Usages, please check the demo page or visit the official website.