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
- it provides a wiki that digs deeply into fundementals of position: sticky and position: fixed and it works with them.

---

Installation  
Setup  
Usage  
Feature  
Options  
Examples  
Debugging  
Notes  
Contributing  
Wiki

---

Installing from a package manager

yarn

``sh

yarn add stickybits

`

pnpm

`sh

pnpm i stickybits

`

npm

`sh

npm i stickybits

`

Setup

Add dist/stickybits.min.js

Or as a module with import stickybits from 'stickybits'

Basic Usage

`javascript
stickybits("selector");
`

$3

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

---

Key Note: Stickybits expects and works best when the element that will become sticky is wrapped within a parent element that defines when the element starts being sticky and stops being sticky. See below for visual reference.

`html







`

---

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 provide more feature richness to the Stickybits experience, a .js-is-sticky--change CSS class is added after the Stickybit element is sticky for a certain duration of scroll. By default this duration of scrolling is the height of the Stickybit element. The scroll duration for when .js-is-sticky--change is added can be modified by providing a number for customStickyChangeNumber option.

To use useStickyClasses:

`javascript
stickybits("selector", { useStickyClasses: true });
`

Then, in css you can do:

`css
.some-sticky-element.js-is-sticky {
background-color: red;
}
.some-sticky-element.js-is-sticky--change {
height: 50px;
}
.some-sticky-element.js-is-stuck {
background-color: green;
}
`

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

Options

$3

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:

`javascript
stickybits("selector", { verticalPosition: "bottom" });
`

$3

By default, if Stickybits uses window scrolling to define Sticky Elements. An element besides window can be used if window is undefined by selecting the desired scrolling element with the scrollEl option. For more custom sticky featuring, the scrollEl option can be used. However, those implementations require the implementing developers support.

To have Stickybit use an selector besides window:

`javascript
stickybits("selector", { scrollEl: "an-id" });
`

$3

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:

`javascript
stickybits("selector", { stickyBitStickyOffset: 20 });
`

$3

To _cleanup_ an instance of Stickybits:

`javascript
const stickybitsInstancetoBeCleanedup = stickybits("selector");
stickybitsInstancetoBeCleanedup.cleanup();
`

$3

To _update_ the calculations of an instance of Stickybits:

`javascript
const stickybitsInstancetoBeUpdated = stickybits("selector");
stickybitsInstancetoBeUpdated.update();
`

Re-calculates each Stickybits instance's offsets (stickyStart, stickyStop).
If the Stickybits implementer would like re-calculate offsets when the DOM window is resized or when the url changes. .update() can be invoked within an event listener.

`javascript
const stickybitsInstancetoBeUpdated = stickybits("selector");
stickybitsInstancetoBeUpdated.update({ stickyBitStickyOffset: 20 });
`

#### More Stickybits Update Examples

`javascript
// when the window is resized
const stickybitsInstancetoBeUpdated = stickybits("selector");
window.addEventListener("resize", () => {
stickybitsInstancetoBeUpdated.update();
});
// when the url hash changes
window.addEventListener("hashchange", () => {
stickybitsInstancetoBeUpdated.update();
});
`

Note: .update does not re-initialize classnames or pre-set calculations. Perhaps the update value can help you with that (see the paragraph below).

#### StickBits Update Props

Props can be updated to each instance by passing then into the .update function as an object.

`javascript
// .update({ someProp: somePropValue })
const stickybitsInstancetoBeUpdated = stickybits("selector");
stickybitsInstancetoBeUpdated.update({ stickyBitStickyOffset: 20 });
`

$3

To use StickyBits without inline styles except for position: sticky or position: fixed:

`javascript
stickybits("selector", { noStyles: true });
`

$3

To use custom CSS classes for Stickybits, add the appropriate properties and values.

parentClass:

`javascript
stickybits("selector", { parentClass: "new-parent-classname" });
`

stickyClass:

`javascript
stickybits("selector", { stickyClass: "new-sticky-classname" });
`

stuckClass:

`javascript
stickybits("selector", { stuckClass: "new-stuck-classname" });
`

$3

To not use position: sticky ever, add the following key value to a stickybit initalization.

parentClass:

`javascript
stickybits("selector", { useFixed: true });
`

To change all of the CSS classes

`javascript
stickybits("selector", {
parentClass: "new-parent-classname",
stickyClass: "new-sticky-classname",
stuckClass: "new-stuck-classname",
stickyChangeClass: "new-sticky-change-classname"
});
`

$3

To not use offsetTop provide the optional boolean useGetBoundingClientRect.
This feature is optimal when dealing with things like CSS calc which can throw off offsetTop calculations. Read more about this functionality here.

`javascript
stickybits("selector", { useGetBoundingClientRect: true });
`

\* For jQuery and Zepto support, read the jQuery notes below.

$3

If you want to take control of how styles and classes are applied to elements
provide a function applyStyle. This is useful for example if you want to
integrate with a framework or view library and want to delegate DOM
manipulations to it.

`javascript
stickybits("selector", {
applyStyle: ({ classes, styles }, instance) => {
// Apply styles and classes to your element
}
});
`

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})
- Clean Stickybits ie: const stickything = stickybits('selector'); stickything.cleanup();
- Update ie: const stickything = stickybits('selector') stickything.update()
- Update props ie: const stickything = stickybits('selector') stickything.update({ stickyBitStickyOffset: 20 })
- Use Fixed ie: const stickything = stickybits('selector', {useFixed: true})
- Use GetBoundingClientRect ie: const stickything = stickybits('selector', {useGetBoundingClientRect: true})
- As a jQuery or Zepto Plugin ie: $('selector').stickybits()

---

$3

- Custom vertical position (at bottom of parent element)
- NoStyles Stickybits ie: stickybits('selector', {noStyles: true});
- With Custom Classes ie: stickybits('selector', {parentClass: 'js-parent-test'})
- ScrollEl ie: stickybits('selector', {scrollEl: 'a-custom-scroll-el'}) or stickybits('selector', {scrollEl: 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

$3

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. These Classes can be modified as desired. See the _With Custom Classes_ example above.

- 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

$3

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.

$3

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!

$3

Basic

`javascript
$("selector").stickybits();
`

With scrollEl

`javascript
$("selector").stickybits({ scrollEl: "#scrollEl" });

// or

const el = document.querySelector("#scrollEl");
$("selector").stickybits({ scrollEl: el });
`

With .update

`javascript
const instance = $("selector").stickybits();
instance.update();
`

With useStickyClasses

`javascript
$("selector").stickybits({ useStickyClasses: true });
`

With verticalPosition

`javascript
$("selector").stickybits({ verticalPosition: "bottom" });
`

With stickyBitStickyOffset

`javascript
$("selector").stickybits({ stickyBitStickyOffset: 20 });
`

Debugging

Stickybits 2.0 provides the same API but with more debugging feedback.

To view the Stickybits API in it's simpliest form:

`javascript
const stickybit = stickybits("a selection");
console.log(stickybit);
`

For more debugging and managing Stickybits, view the wiki.

---

$3

Stickybits provides both version and userAgent properties which were added to offer insight into the browser and Stickybits.

These utility properties can be accessed as direct child properties of the instantiated Stickybits item.

`javascript
const stickybit = stickybits("a selection");
stickybit.version; // will show the version of stickybits being used
stickybit.userAgent; // will show which userAgent stickybits is detecting
`

Browser Compatibility

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

Contributing

Please contribute to Stickybits by filing an issue, responding to issues, adding to the wiki, or reaching out socially—etc.

Stickybits is a utility. It may often not be needed! With shared understanding of position: sticky and position: fixed along with product awareness, Stickybits can improve as can a shared understanding of the "sticky element issue". Is this paragraph over-reaching? Yes! Help improve it.

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`.

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.

$3

- Frank Merema
- Daniel Ruf
- Nestor Vera
- K. Vanberendonck
- Alexey Ukolov
- Martin Barksten