- A number of pixels.
- percentage string
'50%'. A percentage of the viewport's height.
- The function must return a number of pixels, as if you were using a number offset. The function is re-evaluated whenever a trigger point is recalculated, allowing for changes in layout.
- 'bottom-in-view' string
- This is a shortcut, an alias for a function offset that will trigger the handler when the bottom of the element hits the bottom of the viewport.
- 'right-in-view' string
- This is a shortcut, an alias for a function offset that will trigger the handler when the right of the element hits the right of the viewport. This is only useful in conjunction with the horizontal 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.
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.
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.
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.
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.
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:
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:
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.
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.
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,
'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:
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.