jQuery Waypoints

First thing's first, to get started with Waypoints, download the plugin and include it after you've included jQuery.

<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/waypoints.min.js"></script>

You'll now have access to the .waypoint method on your jQuery objects.

The simplest way to use Waypoints is to call .waypoint and pass in a function.

$('#example-basic').waypoint(function() {
  notify('Basic example callback triggered.');
});

This example causes a notification whenever the top of #example-basic hits the top of the viewport. The callback triggers when you pass this point both scrolling up and scrolling down.

More often than not we want to perform different actions depending on which direction the user is scrolling. Waypoints passes this direction as a parameter to the callback function.

$('#example-direction').waypoint(function(direction) {
  notify('Direction example triggered scrolling ' + direction);
});

Here the notification reads "Direction example triggered scrolling down" or "Direction example triggered scrolling up".

What if you want your waypoint to trigger in a location other than when the top of your element hits the top of the viewport? The waypoint function takes a second argument, an options object. One of the most useful options is offset, which tells Waypoints how far from the top of the window the callback should fire. This can be expressed in pixels…

$('#example-offset-pixels').waypoint(function() {
  notify('100 pixels from the top');
}, { offset: 100 });

…as a percentage of the viewport's height…

$('#example-offset-percent').waypoint(function() {
  notify('25% from the top');
}, { offset: '25%' });

…or as a function. The function needs to return a number. The following example will fire when the bottom of the element hits the top of the viewport.

$('#example-offset-function').waypoint(function() {
  notify('Element bottom hit window top');
}, {
  offset: function() {
    return -$(this).height();
  }
});

Let's say you have a div with overflow:scroll, and you want a waypoint inside of this scrollable element. The context option lets you do this. Scroll the box below.

$('#example-context').waypoint(function() {
  notify('Hit top of context');
}, { context: '.example-scroll-div' });

Not all sites scroll vertically. You can create a waypoint on the horizontal axis with the horizontal option. This project page uses horizontal waypoints when the user navigates between high-level sections.

$('.panel').waypoint(function(direction) {
  $body.toggleClass(this.id + '-visible', direction === 'right');
}, {
  offset: '50%',
  horizontal: true
});

As you can see, when horizontal is set to true the direction passed to the callback changes from "down" and "up" to "right" and "left".

You can also create multiple waypoints on the same HTML element. Each waypoint can have its own options. The horizontal example above isn't the only waypoint created on the .panel elements.

$('.panel').waypoint(function(direction) {
  $body.toggleClass(this.id + '-visible', direction === 'left');
}, {
  offset: '-50%',
  horizontal: true
});

CoffeeScript authors may find passing a function followed by an options object to be a bit clumsy. There is another way to pass the waypoints callback, using the handler option. If you provide a handler option, you only need to pass the options object.

/* In JavaScript */
$('#example-handler').waypoint({
  handler: function() {
    notify('Handler option used');
  },
  offset: '50%'
});

# In CoffeeScript
$('#example-handler').waypoint
  handler: ->
    notify 'Handler option used'
  offset: '50%'

If you've got these basics under control, take a look at the docs for more information on all of the options and methods available in Waypoints.

If you're looking to implement one of a number of common scroll-based UI patterns, give the shortcuts section a try.

.waypoint
- default options
- disable
- enable
- destroy
- prev
- next
$.waypoints
- refresh
- viewportHeight
- above
- below
- left
- right
- disable
- enable
- destroy
- extendFn

.waypoint([callback], [options])

callback

type

function, optional
options

type

object, optional

Calling the waypoint function on a set of elements registers them as waypoints. You can pass in a callback function…

$('.thing').waypoint(function(direction) {
  // do stuff
});

…an options object…

$('.thing').waypoint({
  handler: function(direction) {
    // do stuff
  }
});

…or both…

$('.thing').waypoint(function(direction) {
  // do stuff
}, { offset: 50 })

…but you must pass something. Attempting to call waypoint without parameters or without a callback function will result in an error.

$('.thing').waypoint(); // error

The waypoint callback function takes one parameter, direction. For vertical waypoints direction may be 'up' or 'down'. For horizontal waypoints, 'left' or 'right'.

$('.thing').waypoint(function(direction) {
  alert(direction); // up, down, left, or right
});

The options object lets you define where in the viewport to trigger the waypoint, whether the waypoint should be on the horizontal axis, and much more.

$.fn.waypoint.defaults = {
  context: window,
  continuous: true,
  enabled: true,
  horizontal: false,
  offset: 0,
  triggerOnce: false
}

context

string, HTMLElement, or jQuery object

default: window

The context defines which scrollable element the waypoint belongs to and acts within. The default, window, means the waypoint offset is calculated with relation to the whole viewport. You can set this to another element to use the waypoints within that element. It accepts a selector string, raw HTML element, or jQuery object.

$('.something-scrollable .thing').waypoint({
  context: '.something-scrollable'
});

continuous

boolean

default: true

If true, and multiple waypoints are triggered in one scroll, this waypoint will trigger even if it is not the last waypoint reached. If false, it will only trigger if it is the last waypoint.

enabled

boolean

default: true

If false, this waypoint will be created but will be disabled from triggering. You must call enable to turn it back on.

handler

function

default: undefined

The waypoint's callback function can be passed in as the value of the handler option instead of as the first parameter to .waypoint. This is generally much nicer for users writing CoffeeScript.

$('.thing').waypoint({
  handler: function(direction) {
    // do stuff
  }
});

horizontal

boolean

default: false

Default waypoints live on the vertical axis. Their offset is calculated in relation to the top of the viewport and they listen for vertical scroll changes. If horizontal is set to true, offset is calculated in relation to the left of the viewport and listens for horizontal scroll changes.

$('.thing').waypoint({
  horizontal: true,
  offset: 50 // when the left side of this element reaches
             // 50px from the left side of the viewport.
});

offset

number, string, or function

default: 0

This option determines how far the top of the element must be from the top of the viewport to trigger the callback function. If offset is a number, it refers to the number of pixels between the viewport top and element top. The default of 0 means the waypoint triggers when the top of the element hits the top of the viewport. A value of 250 would trigger when the element is 250px from the top of the viewport.

$('.thing').waypoint({
  offset: 250
});

A string value with a percentage refers to a percentage of the height of the viewport. A value of '50%' would trigger the waypoint when the top of the element reaches the dead middle of the screen.

$('.thing').waypoint({
  offset: '50%'
});

Pixel and percentage values can also accept negative values, which behave as you may expect, triggering the waypoint when the top of the element goes a distance past the top of the viewport.

The offset may also be defined by a function. This function needs to return a number. The this keyword within the function is the raw HTML element of the waypoint. This example sets the waypoint to trigger when the middle of the element hits the top of the viewport.

$('.thing').waypoint({
  offset: function() {
    return -$(this).height() / 2;
  }
});

Vertical waypoints may also use the value 'bottom-in-view'. This is a shortcut for a common function that sets the waypoint to trigger when the bottom of the element hits the bottom of the viewport.

$('.thing').waypoint({
  offset: 'bottom-in-view'
});

triggerOnce

boolean

default: false

If true, the waypoint will destroy itself after its first trigger. This is the same as calling .waypoint('destroy') at the end of the callback function.

.waypoint('disable')

Temporarily disables the waypoint callback function from firing. The waypoint can be re-enabled by calling enable.

$('.thing').waypoint('disable');

.waypoint('enable')

Re-enables a previously disabled waypoint.

$('.thing').waypoint('enable');

.waypoint('destroy')

Destroys all waypoints associated with these elements.

$('.thing').waypoint('destroy');

.waypoint('prev', [axis], [context])

axis

type

string, optional

allowed

'vertical', 'horizontal'

default

'vertical'
context

type

string, HTMLElement, or jQuery object, optional

default

window

Returns a jQuery object containing the previous waypoint, as measured by the waypoints' trigger locations.

$('#thing').waypoint(...);
$('#thing-farther-down').waypoint(...);
$('#thing-farther-down').waypoint('prev');
// returns #thing jQuery object

.waypoint('next', [axis], [context])

axis

type

string, optional

allowed

'vertical', 'horizontal'

default

'vertical'
context

type

string, HTMLElement, or jQuery object, optional

default

window

Returns a jQuery object containing the previous waypoint, as measured by the waypoints' trigger locations.

$('#thing').waypoint(...);
$('#thing-farther-down').waypoint(...);
$('#thing').waypoint('next');
// returns #thing-farther-down jQuery object

$.waypoints([contextSelector])

contextSelector

type

string, optional

default

window

Returns an object with two keys, vertical and horizontal. Each of these key values is an HTMLElement array containing all waypoint elements on that axis. If contextSelector is provided, it only returns elements with a context matching that context selector. If no parameter is supplied, all waypoint elements are returned.

$('.thing').waypoint(...);
$.waypoints();
// returns {
//   vertical: [(all .thing elements)]
//   horizontal: []
// }

$.waypoints('refresh')

This will force a recalculation of each waypoint’s trigger point based on its offset option. This is called automatically whenever the window is resized or new waypoints are added. If your project is changing the DOM or page layout without doing one of these things, you may want to manually call it.

$.waypoints('refresh');

$.waypoints('viewportHeight')

Return the height of the viewport, adjusting for inconsistencies that come with calling $(window).height() in iOS. When writing offset functions that use the window's height, using this is recommended.

$.waypoints('viewportHeight');

$.waypoints('above', [contextSelector])

contextSelector

type

string, optional

default

window

Returns an array of HTMLElements. This array contains all waypoint elements with trigger points that lie above the current scroll position of the contextSelector element.

$('.things').waypoint(...);
$.waypoints('above');
// returns all "things" above current scroll position

$.waypoints('below', [contextSelector])

contextSelector

type

string, optional

default

window

Returns an array of HTMLElements. This array contains all waypoint elements with trigger points that lie below the current scroll position of the contextSelector element.

$('.things').waypoint(...);
$.waypoints('below');
// returns all "things" below current scroll position

$.waypoints('left', [contextSelector])

contextSelector

type

string, optional

default

window

Returns an array of HTMLElements. This array contains all waypoint elements with trigger points that lie to the left of the current scroll position of the contextSelector element.

$('.things').waypoint(...);
$.waypoints('left');
// returns all "things" left of current scroll position

$.waypoints('right', [contextSelector])

contextSelector

type

string, optional

default

window

Returns an array of HTMLElements. This array contains all waypoint elements with trigger points that lie to the right of the current scroll position of the contextSelector element.

$('.things').waypoint(...);
$.waypoints('right');
// returns all "things" right of current scroll position

$.waypoints('disable')

Disables all waypoints.

$.waypoints('enable')

Re-enables all waypoints.

$.waypoints('destroy')

Destroys all waypoints.

$.waypoints('extendFn', name, method)

name

type

string, required
method

type

function, required

Adds method to the .waypoint namespace under the name key. Shortcuts use this to add their methods to jQuery Waypoints.

$.waypoints('extendFn', 'alert', function(msg) {
  alert(msg + this.id);
});
$('#thing').waypoint('alert', 'Foo: ');
// Alerts "Foo: thing"

jQuery Waypoints

New in 2.0

Horizontals

Multiples

Shortcuts

Revised API

Shortcuts

Examples

.waypoint([callback], [options])

callback

options

.waypoint('disable')

.waypoint('enable')

.waypoint('destroy')

.waypoint('prev', [axis], [context])

axis

context

.waypoint('next', [axis], [context])

axis

context

$.waypoints([contextSelector])

contextSelector

$.waypoints('refresh')

$.waypoints('viewportHeight')

$.waypoints('above', [contextSelector])

contextSelector

$.waypoints('below', [contextSelector])

contextSelector

$.waypoints('left', [contextSelector])

contextSelector

$.waypoints('right', [contextSelector])

contextSelector

$.waypoints('disable')

$.waypoints('enable')

$.waypoints('destroy')

$.waypoints('extendFn', name, method)

name

method