SyrupJS

A smooth scroll engine with customizable velocity for buttery scrolling animations. Perfect for landing pages and "Back to Top" buttons.

Features

• 🍯 Customizable Velocity - Control how slow or smooth your scrolling is
• 🎨 Multiple Easing Functions - Choose from various easing curves
• ⚡ RequestAnimationFrame Powered - Smooth 60fps animations
• 🎯 Element & Position Scrolling - Scroll to any element or exact position
• 📱 Lightweight - No dependencies, pure JavaScript
• 🛑 Cancellable - Cancel ongoing scroll animations

Installation

npm install syrupjs

Quick Start

// Using the default instance
const { syrup } = require('syrupjs');

// Scroll to top
syrup.scrollToTop();

// Scroll to element
syrup.scrollToElement('#about-section');

// Scroll to specific position
syrup.scrollTo(500);

API Reference

Default Instance

const { syrup } = require('syrupjs');

The default instance comes with sensible defaults:

• Velocity: 0.08
• Easing: easeOutCubic

Custom Instance

const { SyrupJS } = require('syrupjs');

const customSyrup = new SyrupJS({
  velocity: 0.05,  // Slower scrolling
  easing: 'easeInOutQuad'  // Different easing
});

Methods

scrollTo(targetY, duration)

Scroll to a specific Y position.

syrup.scrollTo(1000);        // Auto-calculated duration
syrup.scrollTo(1000, 1500); // Custom duration (1.5 seconds)

scrollToElement(element, offset, duration)

Scroll to an element.

syrup.scrollToElement('#section-2');
syrup.scrollToElement('.my-class', 100); // With 100px offset
syrup.scrollToElement(document.getElementById('my-element'));

scrollToTop(duration)

Scroll to the top of the page.

syrup.scrollToTop();
syrup.scrollToTop(800); // Custom duration

setVelocity(velocity)

Update velocity setting (0.01 - 0.2).

syrup.setVelocity(0.02); // Very slow and smooth
syrup.setVelocity(0.15); // Fast scrolling

setEasing(easingType)

Update easing function.

syrup.setEasing('linear');
syrup.setEasing('easeInCubic');
syrup.setEasing('easeInOutQuart');

cancelScroll()

Cancel any ongoing scroll animation.

syrup.cancelScroll();

isCurrentlyScrolling()

Check if currently scrolling.

if (syrup.isCurrentlyScrolling()) {
  console.log('Scrolling in progress...');
}

Easing Functions

Available easing functions:

• linear
• easeInQuad, easeOutQuad, easeInOutQuad
• easeInCubic, easeOutCubic, easeInOutCubic
• easeInQuart, easeOutQuart, easeInOutQuart
• easeInQuint, easeOutQuint, easeInOutQuint

Velocity Guide

• 0.01 - 0.03: Very slow, syrupy smooth
• 0.04 - 0.08: Smooth and pleasant (default)
• 0.09 - 0.15: Moderate speed
• 0.16 - 0.20: Fast scrolling

Examples

Back to Top Button

document.getElementById('back-to-top').addEventListener('click', () => {
  syrup.scrollToTop(1000); // 1 second animation
});

Smooth Navigation

document.querySelectorAll('a[href^="#"]').forEach(anchor => {
  anchor.addEventListener('click', (e) => {
    e.preventDefault();
    const target = anchor.getAttribute('href');
    syrup.scrollToElement(target, 80); // 80px offset for fixed headers
  });
});

Custom Slow Scrolling

const slowSyrup = new SyrupJS({ velocity: 0.03 });
slowSyrup.scrollToElement('#hero');

Development

npm install
npm test

License

MIT