Observe CSS position: sticky elements getting stuck or unstuck.

It implements the "Sticky Events" pattern using sentinels and IntersectionObserver, allowing you to react to changes in the sticky state of an element.

npm install @bramus/sticky-observer

1. Import StickyObserver in your project.
2. Call StickyObserver.observe() with a CSS selector for the elements you want to watch.
3. Listen for the sticky-change event on the observer instance.

import { StickyObserver } from '@bramus/sticky-observer';

// Initialize and observe elements matching the selector
const observer = StickyObserver.observe('h2');

// Listen for state changes
observer.addEventListener('sticky-change', (e: Event) => {
  const { target, stuck } = e.detail;

  console.log(`Element is now ${stuck ? 'stuck' : 'unstuck'}:`, target);
});

For the observer to work correctly, the parent container of your sticky element must be positioned (e.g., position: relative).

If the parent is statically positioned, StickyObserver will automatically set position: relative on it and log a warning to the console.

Static method to create a new observer instance.

• selector (string): CSS selector for the element(s) to observe.
• options (StickyObserverOptions): Optional configuration object.

Returns a StickyObserver instance.

The StickyObserver instance extends EventTarget and dispatches the following event:

Fired when the sticky state of an observed element changes.

• Event Type: CustomEvent<StickyChangeDetail>
• detail property:
  • target: The HTMLElement that changed state.
  • stuck: boolean indicating if the element is currently stuck.

Stops observing all elements and disconnects the internal IntersectionObservers.

observer.disconnect();

This library injects two "sentinel" elements into the parent of the sticky element:

1. A Top Sentinel placed before the element (at the start of the parent).
2. A Bottom Sentinel placed after the element (at the end of the parent).

It uses IntersectionObserver to track when these sentinels intersect with the viewport (or container). Based on the intersection logic, it determines whether the element is currently in a "stuck" state.

Reference: An event for CSS position:sticky

MIT