$.fn.waypoint

The waypoint namespace extension to the jQuery effin’ object. This is the meat of the plugin, calling .waypoint on one or more elements and registering handlers for when the elements have been reached.

This is how you register an element as a waypoint. When the user scrolls past that element it triggers waypoint.reached, a custom event. Since the parameters for creating a waypoint are optional, we have a few different possible signatures. Let’s look at each of them.

someElements.waypoint();

Calling .waypoint with no parameters will register the elements as waypoints using the default options. The elements will fire the waypoint.reached event, but calling it in this way does not bind any handler to the event. You can bind to the event yourself, as with any other event, like so:

someElements.bind('waypoint.reached', function(event, direction) {
   // make it rain
});

You will usually want to create a waypoint and immediately bind a function to waypoint.reached, and can do so by passing a handler as the first argument to .waypoint:

someElements.waypoint(function(event, direction) {
   if (direction === 'down') {
      // do this on the way down
   }
   else {
      // do this on the way back up through the waypoint
   }
});

This will still use the default options, which will trigger the waypoint when the top of the element hits the top of the window. We can pass .waypoint an options object to customize things:

someElements.waypoint(function(event, direction) {
   // do something amazing
}, {
   offset: '50%'  // middle of the page
});

You can also pass just an options object.

someElements.waypoint({
   offset: 100  // 100px from the top
});

This behaves like .waypoint(), in that it registers the elements as waypoints but binds no event handlers.

Calling .waypoint on an existing waypoint will extend the previous options. If the call includes a handler, it will be bound to waypoint.reached without unbinding any other handlers.

Passing the string 'destroy' to .waypoint will unbind all waypoint.reached event handlers on those elements and unregisters them as waypoints.

Passing the string 'remove' to .waypoint unregisters the elements as waypoints and wipes any custom options, but leaves the waypoint.reached events bound. Calling .waypoint again in the future would reregister the waypoint and the old handlers would continue to work.

An offset of 250 would trigger the waypoint when the top of the element is 250px from the top of the viewport. Negative values for any offset work as you might expect. A value of -100 would trigger the waypoint when the element is 100px above the top of the window.

offset: '100%'

A string percentage will determine the pixel offset based on the height of the window. When resizing the window, this offset will automatically be recalculated without needing to call $.waypoints('refresh').

// The bottom of the element is in view
offset: function() {
   return $.waypoints('viewportHeight') - $(this).outerHeight();
}

Offset can take a function, which must return a number of pixels from the top of the window. The this value will always refer to the raw HTML element of the waypoint. As with % values, functions are recalculated automatically when the window resizes. For more on recalculating offsets, see $.waypoints('refresh').

An offset value of 'bottom-in-view' will act as an alias for the function in the example above, as this is a common usage.

offset: 'bottom-in-view'

You can see this alias in use on the scroll analytics example page.

The triggerOnce flag, if true, will destroy the waypoint after the first trigger. This is just a shortcut for calling .waypoint('destroy') within the waypoint handler. This is useful in situations such as scroll analytics, where you only want to record an event once for each page visit.

The context option lets you use Waypoints within an element other than the window. You can define the context with a selector string and the waypoint will act within the nearest ancestor that matches this selector.

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

You can see this in action on the dial controls example.

The handler option gives authors an alternative way to bind functions when creating a waypoint. In place of:

$('.item').waypoint(function(event, direction) {
   // make things happen
});

You may instead write:

$('.item').waypoint({
   handler: function(event, direction) {
      // make things happen
   }
});

$.waypoints

This will return a jQuery object with a collection of all registered waypoint elements.

$('.post').waypoint();
$('.ad-unit').waypoint(function(event, direction) {
   // Passed an ad unit
});
console.log($.waypoints());

The example above would log a jQuery object containing all .post and .ad-unit elements.

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, new waypoints are added, or a waypoint’s options are modified. If your project is changing the DOM or page layout without doing one of these things, you may want to manually call this refresh.

This will return the height of the viewport, adjusting for inconsistencies that come with calling $(window).height() in iOS. Recommended for use within any offset functions.