Introducing ScrollMagic 2.0

If you’re desperate to generate beautiful scroll animations in your next project, then look no further. ScrollMagic is a JavaScript library to help you create “magical” scroll interactions which effortlessly react to the user’s current scroll position and trigger animations or synchronized events.

ScrollMagic recently underwent some big changes, so here’s a quick walk-through discussing the changes and improvements since its rebirth.

What’s New?

Dependencies that were once core components of ScrollMagic, like GreenSock (GSAP) and jQuery, have been removed entirely from the library. As of 2.0.0 everything that adds features on top of ScrollMagic is treated as a plugin, finally making ScrollMagic a standalone library (6KB gzipped)!

The Changelog contains many other facets that have been adjusted, should you choose to dive deeper. In case you don’t have the time, here’s a list highlighting some of the changes:

Removal of dependencies and introducing plugins

Controllers are now instantiated using ScrollMagic.Controller()

Scenes are now defined as ScrollMagic.Scene()

Removal of triggerOffset

Removal of pinClass (this can be achieved with setClassToggle in 2.0)

pushfollowers default value is set to false

New events: add and remove

Renamed .parent to .controller

Debug extension renamed to plugins/scene.addIndicators and can be added before the controller and works even when scenes are removed and re-added.

New method removeIndicators

Performance Tweaks

Performance tweaks improving the speed of ScrollMagic were suggested by Paul Irish in regards to updating RAF (request animation frame). Instead of listening directly to the scroll event, a technique called “debouncing” was originally used. This means that everything which should be executed on Scroll is actually executed in a timeout (delay). When onScroll had been triggered the only thing that changed was a variable such as wasScrolled = true and inspected for in the timeout function. Originally the debounce function was called on RAF and constantly looked for the wasScrolled var in a loop.

Now, instead of a loop, it’s just scheduling to check on the next RAF when a scroll event is triggered. All this means that when no scroll is happening, no loop is running!

Responsive Durations

Responsive durations have to be one of my favorite improvements to the library besides the performance boosts. The Scene duration can now accept a percentage value string like "100%". The scroll will be calculated in relation to the size of the scroll’s container. ScrollMagic will use the container’s height for vertically scrolling systems and its width for horizontally scrolling containers.

var scene = new ScrollMagic.Scene({
duration: "100%"
});

Script Loading

Script order is quite a bit different now, since libraries like GSAP have been separated as opposed to being part of the ScrollMagic core. This means that anytime you desire a library like TweenMax you’ll need to load the main GSAP library first, followed by the core ScrollMagic lib, then finally the ScrollMagic plugin you’ve chosen.

Remember to always load the main GSAP library first, then the ScrollMagic plugins.

The script call for the GSAP plugin is ScrollMagic’s new plugin that contains the GSAP tween functionality formerly integrated into ScrollMagic. Jan has also integrated velocity.js for those that don’t desire the functionality GSAP provides.

Defining Controllers

A controller is a way to “control scenes.” It’s a class which is needed once per scroll container and written slightly different in 2.0.

Let’s compare the way controllers are instantiated now, with how they were in the old version:

Old way

var controller = new ScrollMagic();

New way

var controller = new ScrollMagic.Controller();

Scenes

The scene is the location of your motion/animation. It defines where the controller should react and how. It’s also another example of where syntax has changed slightly.

New Way

Updating Tips

When speaking with ScrollMagic’s creator Jan Paepke, I learned an awesome time-saving tip to help migrate from your old ScrollMagic code to the new

First perform a “Search and Replace” in your text editor for “ScrollMagic” and replace the string with “SM_TMP” in all your files.

Next replace “ScrollScene” with “ScrollMagic.Scene”.

Lastly, replace “SM_TMP” with “ScrollMagic.Controller”.

Note: Make sure you don’t include ScrollMagic’s source files in your search–only apply it to your own code. It’s an extra step, but is more secure because there are situations where you may have spaces before the brackets.