Polyfill for CSS position: sticky

The most accurate sticky polyfill out in the wild.

Check out the demo and use cases test page.

What it does

• supports top-positioned stickies,

• works in IE9+,

• disables itself in older IEs and in browsers with native position: sticky support,

• mimics original position: sticky behavior:

  • uses parent node as a boundary box,
  • behaves nicely with horizontal page scrolling,
  • only works on elements with specified top,
  • mimics native top and margin-bottom behavior,
  • ~~works with table cells~~ removed for consistency until Firefox makes a native implementation

What it doesn't

• doesn't support left, right, bottom or combined stickies,
• doesn't work in overflowed blocks,
• doesn't parse your CSS! Launch it manually.

Installation

NPM

npm install polysticky --save

Yarn

yarn add polysticky

Raw ES6 module

polysticky.es6.js

Old fashioned

Download minified production ES5 script:

polysticky.min.js

Include it on your page:

<script src="path/to/polysticky.min.js"></script>

Usage

First things first, make sure your stickies work in the browsers that support them natively, e.g.:

<div class="sticky">
    ...
</div>

.sticky {
    position: -webkit-sticky;
    position: sticky;
    top: 0;
}

Then apply the polyfill:

JS:

var elements = document.querySelectorAll('.sticky');
PolySticky.add(elements);

or JS + jQuery:

var elements = $('.sticky');
PolySticky.add(elements);

Also worth having a clearfix:

.sticky:before,
.sticky:after {
    content: '';
    display: table;
}

Pro tips

• top specifies sticky’s position relatively to the top edge of the viewport. It accepts negative values, too.
• You can push sticky’s bottom limit up or down by specifying positive or negative margin-bottom.
• Any non-default value (not visible) for overflow, overflow-x, or overflow-y on any of the ancestor elements anchors the sticky to the overflow context of that ancestor. Simply put, scrolling the ancestor will cause the sticky to stick, scrolling the window will not. This is expected with overflow: auto and overflow: scroll, but often causes confusion with overflow: hidden. Keep this in mind, folks!

Check out the test page to understand stickies better.

API

PolySticky

PolySticky.addOne(element)

element – HTMLElement or iterable element list (NodeList, jQuery collection, etc.). First element of the list is used.

Adds the element as a sticky. Returns new Sticky instance associated with the element.

If there’s a sticky associated with the element, returns existing Sticky instance instead.

PolySticky.add(elementList)

elementList – iterable element list (NodeList, jQuery collection, etc.) or single HTMLElement.

Adds the elements as stickies. Skips the elements that have stickies associated with them.

Returns an array of Sticky instances associated with the elements (both existing and new ones).

PolySticky.refreshAll()

Refreshes all existing stickies, updates their parameters and positions.

All stickies are automatically refreshed after window resizes and device orientations changes.

There’s also a fast but not very accurate layout change detection that triggers this method. Call this method manually in case automatic detection fails.

PolySticky.removeOne(element)

element – HTMLElement or iterable element list (NodeList, jQuery collection, etc.). First element of the list is used.

Removes sticky associated with the element.

PolySticky.remove(elementList)

elementList – iterable element list (NodeList, jQuery collection, etc.) or single HTMLElement.

Removes stickies associated with the elements in the list.

PolySticky.removeAll()

Removes all existing stickies.

PolySticky.forceSticky()

Force-enable the polyfill, even if the browser supports position: sticky natively.

PolySticky.stickies

Array of existing Sticky instances.

PolySticky.Sticky

Sticky class. You can use it directly if you want:

const sticky = new PolySticky.Sticky(element);

Throws an error if there’s a sticky already bound to the element.

Sticky.refresh()

Refreshes the sticky, updates its parameters and position.

Sticky.remove()

Removes the sticky. Restores the element to its original state.

Feature requests

TL;DR

These features will never be implemented in PolySticky:

• Callbacks for sticky state changes
• Switching classes between different sticky states
• Other features that add non-standard functionality

If your request isn’t about one of these, you are welcome to create an issue. Please check existing issues before creating new one.

Some reasoning

PolySticky is a polyfill. This means that it implements a feature (sticky positioning in this case) that already exists in some browsers natively, and allows to use this feature in the browsers that don’t support it yet and older versions of the browsers that didn’t support it at the time. This is its only purpose.

This also means that PolySticky does nothing in the browsers that do support sticky positioning. Which, in turn, means that those browsers won’t support any additional non-standard features.

Bug reports

Check existing issues before creating new one. Please provide a live reproduction of a bug.

Contributing

Prerequisites

• Install Git 😱
• Install node
• Install grunt-cli
• Clone the repo, cd into the repo folder, run npm install (or yarn if you are fancy).

Ok, you are all set.

Building and testing

cd into the repo folder and run grunt. It will build the project from /src/polysticky.js into /dist and run the watcher that will rebuild the project every time you change something in the source file.

Make changes to the source file. Stick to ES6 syntax.

Open /test/index.html in a browser that doesn’t support position: sticky to check that everything works as expected. Compare the results to the same page in a browser that supports position: sticky.

Commit the changes. DO NOT commit the files in the /dist folder. DO NOT change the version in package.json.

Make a pull request 👍

Adding / removing / updating npm packages

Use Yarn, dont’t forget to commit yarn.lock.

Using PolySticky?

🍻 Buy original author a beer

License

MIT license.