Natural Sticky

Quick Start

Install via NPM

npm install natural-sticky

Or use via CDN (just 1.0KB!)

<script src="https://cdn.jsdelivr.net/npm/natural-sticky/dist/natural-sticky.top.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    const header = document.querySelector('.my-header');
    // Default behavior (traditional sticky)
    window.naturalStickyTop(header);
    
    // Floating elements mode
    window.naturalStickyTop(header, { reserveSpace: false });
    
    // Fine-tune with scrollThreshold and snapEagerness
    window.naturalStickyTop(header, {
      snapEagerness: 2.0,
      scrollThreshold: 10,  // Only activate on medium-speed scrolling
      reserveSpace: true    // Traditional sticky (default)
    });
  });
</script>

With a bundler

import { naturalStickyTop, naturalStickyBottom } from 'natural-sticky';

// For headers (traditional sticky by default)
const headerInstance = naturalStickyTop(document.querySelector('.header'));

// For footers with floating elements mode
const footerInstance = naturalStickyBottom(document.querySelector('.footer'), {
  reserveSpace: false
});

// Fine-tune all parameters
const customHeader = naturalStickyTop(document.querySelector('.header'), {
  snapEagerness: 2.0,   // More eager snapping to prevent visual gaps
  scrollThreshold: 15,  // Only activate on moderate to fast scrolling
  reserveSpace: true    // Traditional sticky (default)
});

// Clean up when needed
headerInstance.destroy();
footerInstance.destroy();

Why Natural Sticky?

Traditional sticky headers use CSS transitions or JavaScript animations that can feel jarring and disconnected from the user's scroll behavior. Natural Sticky takes a different approach:

• No animations - Elements move with the natural flow of scrolling
• Perfect synchronization - Movement speed matches scroll speed exactly
• Minimal footprint - Less than 1.2KB total, zero dependencies
• Universal compatibility - Works everywhere modern JavaScript runs

The secret is in switching between position: sticky and position: relative (or position: fixed and position: absolute for floating elements) at exactly the right moments, letting the browser's native scrolling handle all the movement naturally.

Choose your positioning style

The reserveSpace parameter (default: true) controls how elements behave:

• true (default) - Traditional sticky behavior that preserves layout space
• false - Floating elements that don't take up layout space when hidden

Fine-tuning with snapEagerness

The snapEagerness parameter (default: 1.0) lets you balance between natural movement and gap prevention:

• 0.0 - Pure natural movement, may show gaps on fast scrolling
• 1.0 - Balanced behavior (default)
• 2.0 - More eager snapping to prevent gaps
• 3.0+ - Magnetic effect with intentional snap behavior

Controlling activation with scrollThreshold

The new scrollThreshold parameter (default: 0) controls when the natural scroll-in effect activates based on scroll speed:

• 0 - Always activate (current behavior)
• 5-10 - Gentle threshold, filters out very slow scrolling
• 15-20 - Moderate threshold, requires deliberate scrolling
• 25-30+ - High threshold, only fast scrolling activates

Perfect for creating more intentional user interactions. Headers might use lower thresholds (always accessible), while footers might use higher thresholds (only appear during deliberate navigation).