StickyState

To ensure the polyfill and state classes work correctly, your CSS must include definitions for the base sticky class and the fallback fixed positioning. The is-sticky class is used to trigger the sticky state styles. If you customize className, stateClassName, fixedClass, or absoluteClass in the JavaScript options, ensure your CSS selectors match those values.

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

.sticky.sticky-fixed.is-sticky {
  position: fixed;
  -webkit-backface-visibility: hidden;
  -moz-backface-visibility: hidden;
  backface-visibility: hidden;
}

.sticky.sticky-fixed.is-sticky:not([style*="margin-top"]) {
  margin-top: 0 !important;
}
.sticky.sticky-fixed.is-sticky:not([style*="margin-bottom"]) {
  margin-bottom: 0 !important;
}

.sticky.sticky-fixed.is-absolute{
  position: absolute;
}

You can install StickyState using npm to add sticky state detection and polyfill support for position:sticky to your project. It is dependency-free and supports IE9+.

npm install sticky-state

StickyState provides an event API to react to elements entering or leaving the sticky state. You can use the .on() method to attach listeners for sticky:on and sticky:off events. The event object e contains the target element.

var StickyState = require('sticky-state');
new StickyState(document.querySelectorAll('.sticky'))
  .on('sticky:on', function(e){console.log('sticky:on', e.target);})
  .on('sticky:off', function(e){console.log('sticky:off' ,e.target);});

Since StickyState extends EventDispatcher, you can listen to events triggered when the element enters or leaves the sticky state. The element target is passed to the event dispatcher.

Events:

• sticky:on: Fired when the element becomes sticky.
• sticky:off: Fired when the element is no longer sticky.

const sticky = new StickyState(el);

sticky.on('sticky:on', () => {
  console.log('Element is now sticky!');
});

sticky.on('sticky:off', () => {
  console.log('Element is no longer sticky.');
});

To manage sticky behavior and polyfill position: sticky for an element, instantiate StickyState with the target DOM element and an optional configuration object. If you pass a NodeList as the first argument, the library will automatically create a StickyStateCollection for all elements in the list (excluding the first one).

import StickyState from './sticky-state.js';

const el = document.querySelector('.my-sticky-element');
const options = {
  className: 'my-sticky-class',
  stateClassName: 'is-active'
};

const sticky = new StickyState(el, options);

You can programmatically enable or disable the sticky logic for an instance using the disable(value) method. Passing true will stop all sticky calculations and class applications.

const sticky = new StickyState(el);

// Disable sticky behavior
sticky.disable(true);

// Re-enable sticky behavior
sticky.disable(false);

To prevent memory leaks and remove all scroll and resize event listeners, call destroy() when the element is removed from the DOM or the sticky behavior is no longer needed.

const sticky = new StickyState(el);

// Later, when cleaning up:
sticky.destroy();

Use getStickyState() to retrieve the current calculated state of the element. This is useful for manual logic checks outside of event listeners.

const state = sticky.getStickyState();
// Returns: { sticky: boolean, absolute: boolean }

if (state.sticky) {
  // Do something while sticky
}