position: sticky
Polyfill for CSS 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
andmargin-bottom
behavior, works with table cellsremoved 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 stickyfilljs --save
Yarn
yarn add stickyfilljs
Raw ES6 module
Old fashioned
Download minified production ES5 script:
Include it on your page:
Usage
First things first, make sure your stickies work in the browsers that support them natively, e.g.:
...
Then apply the polyfill:
JS:
var elements = document;Stickyfill;
or JS + jQuery:
var elements = ;Stickyfill;
Also worth having a clearfix:
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
) foroverflow
,overflow-x
, oroverflow-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 withoverflow: auto
andoverflow: scroll
, but often causes confusion withoverflow: hidden
. Keep this in mind, folks!
Check out the test page to understand stickies better.
API
Stickyfill
Stickyfill.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.
Stickyfill.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).
Stickyfill.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.
Stickyfill.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.
Stickyfill.remove(elementList)
elementList
– iterable element list (NodeList
, jQuery collection, etc.) or single HTMLElement
.
Removes stickies associated with the elements in the list.
Stickyfill.removeAll()
Removes all existing stickies.
Stickyfill.stickies
Array of existing Sticky instances.
Stickyfill.Sticky
Sticky class. You can use it directly if you want:
const 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 Stickyfill:
- 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
Stickyfill 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 Stickyfill 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, runnpm install
(oryarn
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/strickyfill.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
.