stickybits

Make things get sticky …in a good way

---

---

StickyBits 🍬

Stickybits is a lightweight alternative to position: sticky polyfills. It works perfectly for things like sticky headers.

Stickybits is awesome because:

• it can add a CSS Sticky Class (.js-is-sticky) when position: sticky elements become active and a CSS Stuck Class (.js-is-stuck) when they become stuck. See useStickyClasses.
• it loosely mimics position: sticky to consistently stick elements vertically across multiple platforms
• it does not have the jumpiness that plugins that are built around position: fixed have because it tries to support position: sticky first.
• in its simplest use case, a scroll event listener will not be used if position: sticky is supported.
• it is super simple & lightweight

---

Installation   Setup   Usage   Feature   Options   Examples   Notes

---

Installing from a package manager

yarn

yarn add stickybits

npm

npm install stickybits --save

bower

bower install stickybits --save

Setup

Add dist/stickybits.min.js

Or as a module with import shave from 'shave'

Basic Usage

stickybits('selector');

By default, a selected stickybits element will:

• Stick elements to the top of the viewport when scrolled to vertically.
• Stick elements at the bottom of their parent element when scrolled past.

useStickyClasses Feature

Stickybits allows customers to add CSS to elements when they become sticky and when they become stuck at the bottom of their parent element.

By default, if position: sticky is supported, StickyBits will exit allowing the browser to manage stickiness and avoid adding a scroll event listener.

If the useStickyClasses argument is set to true then even if a browser supports position: sticky, StickyBits will still add a scroll event listener to add and remove sticky CSS Classes. This option is available so that CSS styles can use when StickyBits elements become sticky or stuck at the bottom of their parent.

To use useStickyClasses:

stickybits('selector', {useStickyClasses: true});

Then, in css you can do:

.some-sticky-element .js-is-sticky {
  background-color: red;
}
.some-sticky-element .js-is-stuck {
  background-color: green;
}

View add css classes for more information on StickyBits CSS Classes.

Options

Vertical Layout Position

By default, a StickyBits element will stick to the top of the viewport when vertically scrolled to.

Stickybits loosely works for bottom positioning as well.

To have a StickyBits element stick to the bottom:

stickybits('selector', {verticalPosition: 'bottom'});

Custom Scroll Element

By default, if Stickybits uses a scroll event (if position: sticky is not supported or if we use the option useStickyClasses) it uses window.

To have Stickybit use an selector besides window:

const scrollEl = document.getElementById('an-id');
stickybits('selector', {scrollEl: scrollEl});

* Note: This selector is not selected automatically so the specific element need to be passed in.

StickyBit Sticky Offset

By default, a StickyBits element will have a 0px sticky layout top offset. This means that the element will stick flush to the top of the viewport.

To have a StickyBits element stick with a 20px offset to its vertical layout position:

stickybits('selector', {stickyBitStickyOffset: 20});

StickyBits Cleanup

To cleanup an instance of Stickybits:

const stickybitsInstancetoBeCleanedup = stickbits('selector');
stickybitsInstancetoBeCleanedup.cleanup();

For jQuery and Zepto support, read in the jQuery notes below.

Examples

• Basic Usage
• Basic usage but with multiple instances of the same selector
• Custom vertical top offset ie: stickybits('selector', {stickyBitStickyOffset: 20})
• UseStickyClasses ie: stickybits('selector', {useStickyClasses: true})
• ScrollEl ie: stickybits('selector', {scrollEl: document.querySelectorAll('a-custom-scroll-el')})
• Clean Stickybits ie: const stickything = stickybits('selector'); stickything.cleanup();
• As a jQuery or Zepto Plugin ie: $('selector').stickybits();

---

Examples extended

• Custom vertical position (at bottom of parent element)
• If you have Stickybits examples, please submit an issue with a link to it. 🙏

---

Have another example or question? Feel free to comment. 🙌

Notes

CSS Class Usage

3 CSS classes will be added and removed by Stickybits if position: sticky is not supported or if the useStickyClasses: true option is added to the plugin call.

• js-is-sticky if the selected element is sticky.
• js-is-stuck if the selected element is stopped at the bottom of its parent.
• js-stickybit-parent so that styles can easily be added to the parent of a Stickybits element

Not a Polyfill

Stickybits is not a Shim or Polyfill for position: sticky because full support would require more code. This plugin makes elements vertically sticky very similarly to position: fixed but in a sticky sort of way. Read more about position sticky here or follow its browser implementation here.

Stickybits is a no dependency JavaScript plugin. It provides the smallest API possible in both features and kb size to deliver working sticky elements. This means that opinionated featuring is left out as much as possible and that it works with minimal effort in Frameworks.

CSS when position: sticky is not supported

Sticky Start and Sticky Stop: Because Stickybits is minimal, when position: sticky is not supported Stickybits will use position: fixed which is relative to the browser window. If the StickyBits parent element has a height recognized by the browser, Stickybits will take care of the sticky top and sticky bottom invocation. If the parent's height is not recognized by the browser there will be issues.

Left and Right Positioning: With position: fixed the Stickybit element will work relative to the browser window by default. To work with this issue, there are several options. Some are noted here. More solutions to come!

jQuery and Zepto Usage

Basic

$('selector').stickybits();

With scrollEl

const $scrollEl = $('#scrollEl')[0];
$('selector').stickybits({scrollEl: scrollEl});

* Note: because StickyBits is not jQuery specific, in order to pass in a selector for scrollEl, add a [0] to the the selector.

With useStickyClasses

$('selector').stickybits({useStickyClasses: true});

With customVerticalPosition

$('selector').stickybits({customVerticalPosition: true});

With stickyBitStickyOffset

$('selector').stickybits({stickyBitStickyOffset: 20});

Browser Compatibility

Stickybits works in all modern browsers including Internet Explorer 9 and above. Please file and issue with browser compatibility quirks.

Thanks

This plugin was heavily influenced by Filament Group's awesome Fixed-sticky jQuery plugin. Thanks to them for getting my mind going on this a while back. Thanks to Peloton Cycle's Frame Throttle for an insightful solve for optimizing frame throttling.

Contributions: Much browser and documentation debugging has be done by kvanberendonck. Architecture discussions and Pull Request help has been provided by Jacob Kelley, Brian Gonzalez, and Matt Young. It is much appreciated!

---

Created and maintained by Jeff Wainwright with Dollar Shave Club Engineering.