Natural Sticky

Quick Start

Option 1: CDN Usage

<!-- For headers (1.2KB minified) -->
<script src="https://cdn.jsdelivr.net/npm/natural-sticky/dist/natural-sticky.top.min.js"></script>

<!-- For footers (1.3KB minified) -->
<script src="https://cdn.jsdelivr.net/npm/natural-sticky/dist/natural-sticky.bottom.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>

Option 2: Install and Import

npm install natural-sticky

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();

Configuration

reserveSpace (boolean, default: true)

Controls positioning behavior:

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

Live Demos: Floating Elements Demo → | Minimal Floating Header →

snapEagerness (number, default: 1.0)

Balances natural movement vs 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

Live Demos: SnapEagerness Side-by-Side → | SnapEagerness Comparison →

scrollThreshold (number, default: 0)

Controls activation 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).

Live Demos: ScrollThreshold Side-by-Side → | ScrollThreshold Comparison →

Events

Natural Sticky dispatches events when elements change state, enabling dynamic interfaces that respond to scroll behavior:

const header = document.querySelector('.header');
naturalStickyTop(header);

// Listen for state changes
header.addEventListener('natural-sticky', (event) => {
  const currentState = event.detail.state; // 'home', 'sticky', or 'relative'
  
  // Apply different styles based on state
  header.classList.remove('state-home', 'state-sticky', 'state-relative');
  header.classList.add(`state-${currentState}`);
  
  console.log(`Header is now: ${currentState}`);
});

Live Demo: Event System Demo →

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 - 1.2KB for headers, 1.3KB for footers, zero dependencies
• Universal compatibility - Works everywhere modern JavaScript runs