Waypoints

Waypoint Class

Waypoints are created by instantiating this class. How you instantiate a waypoint depends on which build you use (jQuery, Zepto, or no-framework dependency.) All builds support instantiation using new on the globally exposed Waypoint class.

new Waypoint(options)

var waypoint = new Waypoint({
  element: document.getElementById('new-operator'),
  handler: function(direction) {
    notify(this.id + ' hit')
  }
})

If you're using the jQuery or Zepto builds, extensions for those frameworks are provided to match the framework style. A waypoint method is exposed on the jQuery/Zepto prototypes.

$.fn.waypoint(options)

var waypoints = $('#options-only').waypoint({
  handler: function(direction) {
    notify(this.element.id + ' hit')
  }
})

In the example above, waypoints will be an array of Waypoint instances, one for each of the elements matching the selector. In this case, an array containing only one waypoint using the lone #options-only element. Notice that the element option is no longer needed with the jQuery or Zepto builds, as elements are provided by the matched selector.

The jQuery and Zepto builds also allow you to pass the handler as the first argument to waypoint.

$.fn.waypoint(handler, options)

var waypoints = $('#handler-first').waypoint(function(direction) {
  notify(this.element.id + ' hit 25% from top of window') 
}, {
  offset: '25%'
})

In this method signature, because the matched selector removes the need for the element option, and the first parameter takes care of the handler option, there are no remaining required options properties and you can omit the options parameter entirely if you want default behavior.

var waypoints = $('#handler-only').waypoint(function(direction) {
  notify(this.element.id + ' hit') 
})

Properties

adapter

This property gives you the instance of the adapter wrapped around the DOM element of this waypoint. Most Waypoints users should use the element property to access this element, but adapter is useful for developers writing Waypoints extensions or scripts that are intended to be used across all the different framework builds of Waypoints.

var waypoint = new Waypoint({
  element: document.getElementById('adapter-property-example'),
  handler: function(direction) {
    notify('Using jQuery Adapter: ' + !!this.adapter.$element)
  },
  offset: '25%'
})

context

This property gives you the instance of Waypoint.Context that the waypoint belongs to.

var waypoint = new Waypoint({
  element: document.getElementById('context-property-example'),
  handler: function(direction) {
    notify('Context: ' + this.context.element)
  },
  offset: '25%'
})

element

Easily the most useful property of a waypoint is its DOM element. With this property we gain access to that element within the handler.

var waypoint = new Waypoint({
  element: document.getElementById('element-property-example'),
  handler: function(direction) {
    notify('Waypoint element id: ' + this.element.id)
  },
  offset: '25%'
})

group

This property gives you the instance of Waypoint.Group that the waypoint belongs to. This property should be the only way you access a group.

var waypoint = new Waypoint({
  element: document.getElementById('group-property-example'),
  handler: function(direction) {
    notify('Group: ' + this.group.name)
  },
  offset: '25%'
})

options

The options property of a waypoint is the result of merging the default options object with the options object passed in on instantiation. The properties of this object have little practical use inside a handler, but inspecting this object may be useful in debugging to ensure that the waypoint received the options you intended.

var waypoint = new Waypoint({
  element: document.getElementById('options-property-example'),
  handler: function(direction) {
    notify('Offset option: ' + this.options.offset)
  },
  offset: '50%'
})

triggerPoint

This property is the result of the most recent offset calculation. It is the scroll value, in pixels, where the handler triggers. In the simplest example, when the offset is the default of 0, triggerPoint will be identical to the element's offset top.

You should never set the triggerPoint directly on a waypoint, but it is a useful property to inspect when debugging why a waypoint may not be triggering at the location you expect.

var waypoint = new Waypoint({
  element: document.getElementById('trigger-point-example'),
  handler: function(direction) {
    notify('Trigger point: ' + this.triggerPoint)
  },
  offset: 'bottom-in-view'
})