ziko-scrolling

v1.0.6

Published

11 days ago

this is smooth-scroll & scroll with elements

0High
0Medium
0Low

ziadmahmoud

scroll smooth

HM_ZM Natural Scroll 🎯

An advanced JavaScript library that provides a smooth and natural scrolling experience with full native scrollbar support and multiple interaction methods.

✨ Features

Smooth & Natural Scrolling using Lerp interpolation technique
Full Native Scrollbar Support with direct interaction capability
Mouse Dragging (Left & Middle Mouse Button)
Click to Scroll - Single click anywhere to scroll
Touch Support for mobile devices with Momentum
Keyboard Shortcuts (Arrow Keys, Page Up/Down, Home, End, Space)
Visual Indicators for scroll direction
Optimized Performance with requestAnimationFrame
GSAP ScrollTrigger Compatible
Fully Customizable

please Discussion me for any issue for use [https://github.com/ZiadMahmoudas] and you can Contribute with me to Declare any thing

📦 Installation

Direct Method

  <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/scroll.min.css">
  <script src="https://unpkg.com/[email protected]/dist/scroll.min.js"></script>
<script>
  const scroll = new HM_ZM();
</script>

NPM (if available)

npm install ziko-scrolling

🚀 Basic Usage

Simple Initialization

const scroll = new HM_ZM();

Custom Configuration

const scroll = new HM_ZM({
  lerp: 0.08,                    // Smoothness speed (0.01 - 0.2)
  wheelMultiplier: 1.2,          // Wheel sensitivity
  touchMultiplier: 2,            // Touch sensitivity
  dragMultiplier: 1.5,           // Drag sensitivity
  clickScrollAmount: 100,        // Click scroll distance
  enableDrag: true,              // Enable dragging
  enableClickScroll: true,       // Enable click to scroll
  enableNativeScrollbar: true,   // Show native scrollbar
  scrollbarInteractive: true,    // Allow scrollbar interaction
  smooth: true,                  // Enable smooth scrolling
  infinite: false                // Infinite scrolling
});

🎮 Control Methods

Programmatic Scrolling

// Scroll to specific position
scroll.scrollTo(500);                    // By pixels
scroll.scrollTo('#section');             // By selector
scroll.scrollTo(element);                // DOM element

// With additional options
scroll.scrollTo('#about', {
  offset: -100,        // Offset
  immediate: false,    // Instant or smooth
  behavior: 'smooth'   // 'smooth' or 'instant'
});

Programmatic Click Scroll

scroll.clickScroll('up');     // Scroll up
scroll.clickScroll('down');   // Scroll down

Programmatic Drag

scroll.dragBy(100);   // Drag by 100 pixels
scroll.dragBy(-50);   // Reverse drag

Update & Settings

// Update calculations (when content changes)
scroll.update();

// Update settings on the fly
scroll.updateSettings(
  0.1,    // lerp
  1.5,    // wheelMultiplier
  2,      // dragMultiplier
  150,    // clickScrollAmount
  true    // enableNativeScrollbar
);

Start & Stop

scroll.stop();   // Stop scrolling
scroll.start();  // Start scrolling

Toggle Native Scrollbar

scroll.toggleNativeScrollbar(true);   // Show
scroll.toggleNativeScrollbar(false);  // Hide

Destroy

scroll.destroy();  // Complete removal and restore default behavior

📊 Getters (Readable Properties)

scroll.scroll         // Current scroll position
scroll.progress       // Progress percentage (0-1)
scroll.velocity       // Scroll velocity
scroll.direction      // Scroll direction (-1 or 1)
scroll.isLocked       // Is scroll locked?
scroll.isDragging     // Is user dragging?
scroll.limit          // Maximum scroll limit

🎨 Visual Customization

The library provides ready-to-use classes for customization:

/* During dragging */
.hm-zm-dragging {
  cursor: grabbing !important;
}

/* During click scrolling */
.hm-zm-click-scrolling {
  cursor: grabbing !important;
}

/* Scrollbar customization */
.hm-zm-natural::-webkit-scrollbar {
  width: 12px;
}

.hm-zm-natural::-webkit-scrollbar-thumb {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 6px;
}

.hm-zm-natural::-webkit-scrollbar-thumb:hover {
  background: linear-gradient(135deg, #764ba2 0%, #667eea 100%);
}

/* Firefox scrollbar */
.hm-zm-natural {
  scrollbar-width: thin;
  scrollbar-color: #667eea rgba(0,0,0,0.1);
}

⌨️ Keyboard Shortcuts

| Key | Function | |-----|----------| | ↑ / ↓ | Scroll by clickScrollAmount | | Page Up / Page Down | Scroll by 90% of screen height | | Home | Return to top | | End | Go to bottom | | Space | Scroll down (Shift+Space for up) |

🖱️ Interaction Methods

1. Mouse Wheel

Smooth scrolling using mouse wheel

2. Left Click Drag

Press and drag anywhere to scroll

3. Middle Mouse Button Drag

Fast drag using middle mouse button

4. Click to Scroll

Click in upper half → Scroll up ⬆️
Click in lower half → Scroll down ⬇️

5. Touch (Mobile)

Smooth drag with momentum for mobile devices

6. Native Scrollbar

Direct interaction with scrollbar

🔧 Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>HM_ZM Natural Scroll Demo</title>
  <style>
    body {
      margin: 0;
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
    }
    
    .section {
      height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      font-size: 4rem;
      font-weight: bold;
    }
  </style>
</head>
<body>
  <div class="section">Section 1</div>
  <div class="section">Section 2</div>
  <div class="section">Section 3</div>
  <div class="section">Section 4</div>

  <script src="hm-zm.js"></script>
  <script>
    const scroll = new HM_ZM({
      lerp: 0.08,
      wheelMultiplier: 1.2,
      enableClickScroll: true,
      enableNativeScrollbar: true
    });

    // Example: Scroll to second section after 2 seconds
    setTimeout(() => {
      scroll.scrollTo('.section:nth-child(2)', {
        offset: -50
      });
    }, 2000);
  </script>
</body>
</html>

🔌 GSAP ScrollTrigger Integration

// Automatically compatible with ScrollTrigger
gsap.registerPlugin(ScrollTrigger);

const scroll = new HM_ZM();

gsap.to('.element', {
  scrollTrigger: {
    trigger: '.element',
    start: 'top center',
    end: 'bottom center',
    scrub: true
  },
  x: 400
});

// Update ScrollTrigger when needed
scroll.update();

📱 Browser Support

✅ Chrome, Edge, Safari, Firefox
✅ Desktop devices
✅ Tablets and mobile phones
✅ Touch screens
✅ All modern browsers

🎯 Use Cases

Portfolio and creative websites
Landing pages
E-commerce stores
Long-form content applications
Websites requiring smooth interactive experience
One-page applications
Storytelling websites
Product showcases

⚙️ Default Settings

{
  lerp: 0.08,                      // Smoothness speed
  wheelMultiplier: 1.2,            // Wheel multiplier
  touchMultiplier: 2,              // Touch multiplier
  middleMouseMultiplier: 2.5,      // Middle mouse multiplier
  dragMultiplier: 1.5,             // Drag multiplier
  clickScrollAmount: 100,          // Click scroll distance
  infinite: false,                 // Infinite scrolling
  smooth: true,                    // Smooth scrolling
  smoothWheel: true,               // Smooth wheel
  smoothTouch: true,               // Smooth touch
  enableDrag: true,                // Allow dragging
  enableClickScroll: true,         // Allow click to scroll
  enableNativeScrollbar: true,     // Show native scrollbar
  scrollbarInteractive: true       // Allow scrollbar interaction
}

🐛 Troubleshooting

Issue: Scrolling is not smooth

Solution: Reduce lerp value (e.g., 0.05)

Issue: Scrollbar doesn't appear

Solution: Make sure enableNativeScrollbar: true

Issue: Click to scroll doesn't work

Solution: Make sure enableClickScroll: true

Issue: ScrollTrigger doesn't work

Solution: Call scroll.update() after content changes

Issue: Performance problems

Solution: Increase lerp value for faster response (e.g., 0.12)

Issue: Drag is too sensitive

Solution: Reduce dragMultiplier value (e.g., 1.0)

📝 Important Notes

Performance: The library uses requestAnimationFrame for optimal performance
Memory: Call destroy() when removing the library to clean up memory
Compatibility: Works with most modern browsers
Update: Call update() after changing content size
ScrollTrigger: Automatically updates ScrollTrigger on scroll
Native Scroll: Preserves native scroll behavior when interacting with scrollbar

🎓 Advanced Examples

Example 1: Track Progress

const scroll = new HM_ZM();

// Display progress percentage
setInterval(() => {
  const progressBar = document.querySelector('.progress-bar');
  progressBar.style.width = `${scroll.progress * 100}%`;
}, 16);

Example 2: Change Settings Based on Screen Size

const scroll = new HM_ZM();

function updateScrollSettings() {
  if (window.innerWidth < 768) {
    // Mobile settings
    scroll.updateSettings(0.12, 1, 1, 80, false);
  } else {
    // Desktop settings
    scroll.updateSettings(0.08, 1.2, 1.5, 100, true);
  }
}

window.addEventListener('resize', updateScrollSettings);
updateScrollSettings();

Example 3: Stop Scrolling When Modal Opens

const scroll = new HM_ZM();

function openModal() {
  scroll.stop();
  // Open modal
}

function closeModal() {
  scroll.start();
  // Close modal
}

Example 4: Scroll to Next Section

const scroll = new HM_ZM();
const sections = document.querySelectorAll('.section');
let currentSection = 0;

document.querySelector('.next-btn').addEventListener('click', () => {
  currentSection = (currentSection + 1) % sections.length;
  scroll.scrollTo(sections[currentSection], {
    offset: -50,
    behavior: 'smooth'
  });
});

Example 5: Custom Scroll Indicators

const scroll = new HM_ZM();

// Update custom indicator based on scroll direction
setInterval(() => {
  const indicator = document.querySelector('.custom-indicator');
  if (scroll.direction > 0) {
    indicator.textContent = 'Scrolling Down ⬇️';
  } else if (scroll.direction < 0) {
    indicator.textContent = 'Scrolling Up ⬆️';
  }
}, 100);

🎨 Styling Tips

Custom Scrollbar Theme

/* Dark theme */
.hm-zm-natural::-webkit-scrollbar-thumb {
  background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
}

/* Light theme */
.hm-zm-natural::-webkit-scrollbar-thumb {
  background: linear-gradient(135deg, #ffeaa7 0%, #fdcb6e 100%);
}

/* Minimal theme */
.hm-zm-natural::-webkit-scrollbar {
  width: 6px;
}

.hm-zm-natural::-webkit-scrollbar-thumb {
  background: rgba(0,0,0,0.3);
  border-radius: 3px;
}

🔬 Performance Tips

Use lerp wisely: Lower values (0.05) = smoother but slower, Higher values (0.15) = faster but less smooth
Disable features you don't need: Set enableDrag: false or enableClickScroll: false if not needed
Call update() sparingly: Only when content actually changes
Avoid heavy DOM operations during scrolling
Use CSS transforms for animations instead of position properties

📚 API Reference

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | lerp | Number | 0.08 | Smoothness interpolation (0.01-0.2) | | wheelMultiplier | Number | 1.2 | Mouse wheel sensitivity | | touchMultiplier | Number | 2 | Touch drag sensitivity | | middleMouseMultiplier | Number | 2.5 | Middle mouse drag sensitivity | | dragMultiplier | Number | 1.5 | Left mouse drag sensitivity | | clickScrollAmount | Number | 100 | Pixels to scroll on click | | infinite | Boolean | false | Enable infinite scrolling | | smooth | Boolean | true | Enable smooth scrolling | | smoothWheel | Boolean | true | Smooth wheel scrolling | | smoothTouch | Boolean | true | Smooth touch scrolling | | enableDrag | Boolean | true | Enable mouse dragging | | enableClickScroll | Boolean | true | Enable click to scroll | | enableNativeScrollbar | Boolean | true | Show native scrollbar | | scrollbarInteractive | Boolean | true | Allow scrollbar interaction |

📄 License

This project is open source and available for free use.

👨‍💻 Developer

Developed by HM_ZM

🌟 Support the Project

If you like this library:

⭐ Star it on GitHub
📢 Share it with friends
🐛 Report bugs
💡 Suggest improvements
🤝 Contribute to the code

🔗 Links

GitHub: [https://github.com/ZiadMahmoudas/H_Z]

📞 Contact

For questions, suggestions, or support:

Email: [[email protected]]
LinkedIn: [https://www.linkedin.com/in/ziad-mahmoud-mohammed/]
GitHub: [https://github.com/ZiadMahmoudas]

Enjoy smooth and natural scrolling experience! 🎯✨

Made with ❤️ by HM_ZM