aeo/alice

jQuery plugin for monitoring and reacting to vertical scroll position

Alice.js

A Javascript library for attaching callbacks to vertical scroll positions. Functionality can be triggered based on the user scrolling (up or down) past a specific point, only once past a point in a specific direction, while the scroll position is within a certain range, or via custom tests.

Alice will attach herself as a jQuery plugin if jQuery exists. If jQuery does not exist, Alice will create an object alice in the global namespace.

With jQuery:

$.alice.after(function() {
  // Do something after 80 pixels
}, 80);

Without jQuery:

alice.after(function() {
  // Do something after 80 pixels
}, 80);

For the remainder of the documentation, the examples will be shown using syntax with jQuery.

Usage

Alice comes with several fancy helper methods help you get started writing cool stuff immediately.

At

The at method is simplest way to use Alice. The method takes a pair of arguments: a function to run once the window is scrolled past a specific top position and the top position (in pixels).

var myElement = $(".attached");

var callback = function( diff, goingDown ) {
      myElement.css("position", goingDown ? "fixed" : "absolute");
    }
  , scrollPosition = 320
;

$.alice.at(callback, scrollPosition);

Note that this example leveraged the goingDown argument. This second argument, goingDown, is (a boolean value) regarding whether the window is scrolling up or down at the moment the callback triggers.

After

The after method takes three arguments: a function to run once the window is scrolled past a specific top position, the top position (in pixels), and a (boolean) flag representing whether the callback should run repeatedly (or only once) after the window is scrolled past the specified position.

var myElement = $(".attached");

var callback = function( diff, goingDown ) {
      myElement.css("position", "fixed");
    }
  , scrollPosition = 320
  , repeat = false
;

$.alice.after(callback, scrollPosition, repeat);

Before

The before method is exactly the same as the after method except it works in the opposite direction.

var myElement = $(".attached");

var callback = function( diff, goingDown ) {
      myElement.css("position", "absolute");
    }
  , scrollPosition = 320
  , repeat = false
;

$.alice.before(callback, scrollPosition, repeat);

Range

The range method is basically a combination of after and before, and thus requires an additional top position to be defined. For this method, the callback function will run when the window is scrolled between the two given positions (ie. after the first position but before the second position).

var myElement = $(".flyAcross");

var callback = function( diff, goingDown ) {
      var leftAdjust = 200 * diff / (scrollPositionEnd - scrollPositionStart) - 100;
      myElement.css("left", diff + "%");
    }
  , scrollPositionStart = 320
  , scrollPositionEnd = 720
  , repeat = true
;

$.alice.range(callback, scrollPositionStart, scrollPositionEnd, repeat);

Note that this example leveraged the diff argument. The diff argument is the relative scroll position (in pixels) from scrollPositionStart.

Getting Alice

There are multiple production distributions of Alice. The standard build assumes that your application is already using the jQuery and lo-dash/underscore libraries, and that you would like the helper methods (at, after, before, and range) included.

Alice + helper methods:

• Using jQuery and underscore (1.1k)
• Using jQuery but not underscore (1.4k)
• Standalone (1.9k)

Core-only versions:

• Using jQuery and underscore (.5k)
• Standalone (1.3k)

License

* Copyright (c) 2012 Jacob Swartwood & American Eagle Outfitters Inc.
* Licensed under the MIT license