Waypoints

Sticky Elements

This shortcut requires the jQuery build of Waypoints.

First, include the shortcut script after the main Waypoints script.

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

The Sticky Elements shortcut is used to make an element "stick" to the top of the page once a user has scrolled past it. It packages some best practices around accomplishing this, working around edge cases that can come up, and exposes it as a new class, Waypoint.Sticky. To create a sticky element, instantiate this new class with the desired element:

var sticky = new Waypoint.Sticky({
  element: $('.basic-sticky-example')[0]
})

When you create a new instance of Sticky, a few things happen.

• A wrapper is created around your element. This wrapper remains in a static position on the page, acting as an empty placeholder for that element in the document flow while the real element gains and loses fixed positioning. This wrapper element is the actual element that is used in the underlying Waypoint.
• The wrapper height is set. This ensures the wrapper is the same height as the element it wraps, even when that element becomes fixed. This prevents the page layout from shifting when it does.
• Adds a class to the sticky element when it hits the top of the window. This class is what you must style using CSS to give the sticky element fixed positioning.

Creating a sticky element using this shortcut does not…

• Give elements fixed positioning. You must do this in CSS. In most cases this simple snippet seen below is enough to get the job done, but this may vary depending on your design.

  .stuck {
    position:fixed;
    top:0;
  }

• Adjust for the wrapper. Other CSS properties such as margin may have an effect on the layout of your site and cause content shifts when losing/gaining fixed positioning. You may be better off moving margins off of the element and onto the wrapper.

Options

direction

Default: 'down right'.

This is a space separated list of directions in which the stuckClass should be applied. The default directions handle the most common case for both vertical and horizontal waypoints: You start at the top and wish to add the stuck state when scrolling down and reaching the element (right for horizontal waypoints.) In the rare case that you wish to start in a stuck state and lose fixed positioning as you scroll down to the element's natural position, this could be changed to 'up' (or 'left' for the horizontal analog.)

stuckClass

Default: 'stuck'.

This is a string, a class name that is applied to the sticky element when it is reached. This class is your CSS hook into styling the sticky element in its stuck state. Apply fixed positioning to this class.

wrapper

Default: '<div class="sticky-wrapper" />'.

This is the string of HTML that will be wrapped around the target sticky element. If this options is set to false, no wrapper will be created and the existing parent of the sticky element will be used as the wrapper.

sticky.destroy()

An instance of Sticky has one method, destroy. Calling destroy will destroy the waypoint, remove the stuck class, and get rid of the wrapper that was created around your sticky element, returning the DOM to the state it was in before the Sticky was created.

Let's look at destroying the Sticky we created earlier.

$('.destroy-sticky').on('click', function() {
  sticky.destroy() 
})

Destroy Sticky