Waypoints

offset option

After the handler, the offset is probably the most important and used option. By default, the handler is triggered when the top of an element hits the top of the viewport. The offset changes the location of that trigger point. This option accepts several different types of values. Let's look at each of them.

Number Offset

A number offset represents the number of pixels from the top of the viewport where the handler should trigger. The default, 0, means the handler triggers when the top of the element hits the top of the viewport. If we set this to 25, it will trigger when the top of the element is 25px from the top of the window.

var waypoint = new Waypoint({
  element: document.getElementById('number-offset'),
  handler: function(direction) {
    notify('25px from top')
  },
  offset: 25
})

Number offsets can be negative. An offset of -25 triggers the handler when the top of the element is 25px above the top of the viewport, out of sight.

var waypoint = new Waypoint({
  element: document.getElementById('number-offset-negative'),
  handler: function(direction) {
    notify('25px past the top')
  },
  offset: -25
})

Percentage Offset

A percentage offset refers to a percentage of the window's height. An offet of '50%' will trigger when the top of the element is 50% of the way from the top of the window, or simply put, hits the middle of the window.

var waypoint = new Waypoint({
  element: document.getElementById('percentage-offset'),
  handler: function(direction) {
    notify('50% from the top')
  },
  offset: '50%'
})

Just like number offsets, percentages can be negative. Also like number offsets, negatives indicate the top of the element is a certain percentage of the window height beyond the top of the viewport.

var waypoint = new Waypoint({
  element: document.getElementById('percentage-offset-negative'),
  handler: function(direction) {
    notify('50% past the top')
  },
  offset: '-50%'
})

Function Offset

Function offsets allow for dynamic, complex, creative offsets that depend on runtime values. Let's say we had a waypoint that we wanted to trigger when the bottom of the element hit the top of the window. Let's also say that element has a height of 100px. Easy enough:

offset: -100

But what if we didn't know the height of the element? Maybe it contains user controlled content and could be any height. We might be tempted to do this:

offset: -myElement.clientHeight

This may work, but what if the height of the element changes during a user's time browsing? Perhaps they resized their browser and the element is now taller. If we used the offset above, the waypoint's trigger point would not adjust. This is where function offsets come in.

var waypoint = new Waypoint({
  element: document.getElementById('function-offset'),
  handler: function(direction) {
    notify('Bottom of element hit top of viewport')
  },
  offset: function() {
    return -this.element.clientHeight
  }
})

This offset function will now stay up to date with the element's height as the browser resizes. This is because resizing the browser triggers a refresh all, which forces the recalculation of every waypoint's trigger point. Trigger points are only calculated during a refresh, which occurs when a new waypoint is created, the browser is resized, or a refresh method is manually called. If you change the layout of your page or manipulate the DOM in a way that may effect a waypoint's trigger point, you should call refresh manually.

bottom-in-view Offset

One of the most common needs when using Waypoints is to detect when the entire element is in view, or more precisely, when the bottom of the element hits the bottom of the window. Because it's so common, a shortcut string is included, 'bottom-in-view'.

var waypoint = new Waypoint({
  element: document.getElementById('bottom-in-view-example'),
  handler: function(direction) {
    notify('Bottom of element hit bottom of viewport')
  },
  offset: 'bottom-in-view'
})

right-in-view Offset

'right-in-view' is the horizontal analog to the 'bottom-in-view' alias. It is a shortcut for a function offset, and triggers when the right of the element hits the right edge of the viewport. Here we'll use a custom context, just to make it easier on this site's design:

<div id="overflow-scroll-offset">
  <div id="horizontal-waypoint-offset">right-in-view offset</div>
</div>

var waypoint = new Waypoint({
  element: document.getElementById('horizontal-waypoint-offset'),
  handler: function(direction) {
    notify('right-in-view waypoint triggered')
  },
  context: document.getElementById('overflow-scroll-offset'),
  horizontal: true,
  offset: 'right-in-view'
})

As you can see in the above example, the offset is calculated in relation to the bounding box of the scrollable context element. This is true of all the different possible offset value types.