@rethink-js/rt-smooth-scroll

v1.1.0

Published

19 days ago

Lightweight smooth scrolling powered by Lenis with automatic loading, attribute config, and multi-instance support.

0High
0Medium
0Low

druhin13

smooth-scroll lenis scroll javascript ui animation interactive scrolling rt-smooth-scroll rethink-js

rt-smooth-scroll

rt-smooth-scroll is a lightweight JavaScript library that seamlessly integrates the Lenis smooth scroll engine into your sites with:

Automatic Lenis loading (no extra installs needed)
Zero-config defaults (Lenis defaults, unless you override via attributes)
Support for multiple smooth scroll instances
A clean global API under window.rtSmoothScroll
Optional resize + mutation observation (useful for wrapper instances)
Per-instance configuration via HTML attributes
Console logs showing each instance’s final resolved config

Lenis (GitHub): https://github.com/darkroomengineering/lenis

1. Installation

1.1 CDN (jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>

1.2 npm

npm install @rethink-js/rt-smooth-scroll

Then bundle or load dist/index.min.js as appropriate for your build setup.

2. Quick Start

Add the script to your page. With no configuration provided, rt-smooth-scroll will:

Activate itself automatically (if you didn’t explicitly opt out)
Load Lenis from CDN
Create a root smooth scroll instance
Expose the global API

Example:

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>

Note: If you do not set any rt-smooth-scroll-* config attributes, the root instance uses Lenis defaults.

3. Activation Rules

The library is activated when:

The attribute rt-smooth-scroll exists on <html> or <body> OR
You place one or more elements with rt-smooth-scroll-instance

If neither is present and no instance elements are found, it auto-enables itself on <body> by adding rt-smooth-scroll (so you get a working root instance by default).

4. Configuration (HTML Attributes)

Root Mode

Add to <html> or <body> to enable:

<body rt-smooth-scroll></body>

Global Options

Place on <html> or <body> to configure defaults:

<body
  rt-smooth-scroll
  rt-smooth-scroll-lerp="0.2"
  rt-smooth-scroll-wheel-multiplier="1"
  rt-smooth-scroll-easing="easeOutCubic"
></body>

Important Lenis behavior:

duration and easing are useless if lerp is defined (this is how Lenis works).

Core attributes:

| Attribute | Description | | ------------------------------------------- | ------------------------------------------------------------ | | rt-smooth-scroll-duration | Lenis duration (only applies when lerp is not used) | | rt-smooth-scroll-lerp | Lenis lerp (0 → 1) | | rt-smooth-scroll-orientation | Lenis orientation | | rt-smooth-scroll-gesture-orientation | Lenis gestureOrientation | | rt-smooth-scroll-normalize-wheel | Lenis normalizeWheel | | rt-smooth-scroll-wheel-multiplier | Lenis wheelMultiplier | | rt-smooth-scroll-smooth-touch | Lenis smoothTouch | | rt-smooth-scroll-sync-touch | Lenis syncTouch | | rt-smooth-scroll-sync-touch-lerp | Lenis syncTouchLerp | | rt-smooth-scroll-touch-inertia-multiplier | Lenis touchInertiaMultiplier | | rt-smooth-scroll-touch-multiplier | Lenis touchMultiplier | | rt-smooth-scroll-infinite | Lenis infinite | | rt-smooth-scroll-easing | Named easing function (only applies when lerp is not used) |

Easing options included:

linear
easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInOutSine
easeOutExpo

Per-Instance Configuration

Add attributes to any scroll container:

<div
  rt-smooth-scroll-instance
  rt-smooth-scroll-id="panel"
  rt-smooth-scroll-content=".scroll-content"
  rt-smooth-scroll-lerp="0.18"
></div>

| Attribute | Description | | --------------------------- | -------------------------------------------------------------- | | rt-smooth-scroll-instance | Marks scroll container | | rt-smooth-scroll-id | Optional instance identifier | | rt-smooth-scroll-content | Selector inside container (defaults to first child if omitted) |

Advanced JSON

You may pass additional Lenis options via:

<body
  rt-smooth-scroll
  rt-smooth-scroll-options-json='{"overscroll":true}'
></body>

Lenis Loader / Observer Controls

| Attribute | Description | | ------------------------------------- | ------------------------------------------------------------------------------ | | rt-smooth-scroll-lenis-src | Override Lenis CDN URL | | rt-smooth-scroll-observe-resize | Enable ResizeObserver for wrapper instances (default: true if supported) | | rt-smooth-scroll-observe-mutations | Enable MutationObserver for wrapper instances (default: true if supported) | | rt-smooth-scroll-resize-debounce-ms | Debounce resize calls (default: 0) |

5. Multiple Instances

rt-smooth-scroll supports any number of independent Lenis instances on a page. Each instance has its own wrapper + content and can be controlled individually via API.

6. Global API

After initialization, access:

window.rtSmoothScroll;

Common methods:

| Method | Description | | -------------- | -------------------------------- | | ids() | Array of registered instance ids | | get(id) | Returns Lenis instance | | start(id?) | Start scroll | | stop(id?) | Stop scroll | | toggle(id?) | Toggle scroll | | resize(id?) | Trigger Lenis resize | | destroy(id?) | Remove instance |

Default root Lenis instance is also exposed as:

window.lenis;

7. Console Logging

On startup, each instance logs:

Instance ID
Wrapper element
Content element
Final resolved options

This helps you confirm exactly what configuration is applied in the browser.

8. Troubleshooting

Scroll feels laggy / too delayed

Increase rt-smooth-scroll-lerp (e.g. 0.2 → 0.35) for a snappier response.
Decrease rt-smooth-scroll-lerp (e.g. 0.1 → 0.05) for a smoother/heavier feel.
Leave rt-smooth-scroll-wheel-multiplier="1" unless you have a strong reason to change perceived speed.

Duration / easing doesn’t seem to do anything

Lenis treats duration and easing as useless if lerp is defined. If you want time-based behavior, ensure you’re not effectively running in lerp-mode.

Instance not initialized

Ensure you’ve enabled either:

the root attribute (rt-smooth-scroll), or
one or more instance elements.

Lenis fails to load

If using a custom rt-smooth-scroll-lenis-src, confirm the URL points to a valid Lenis build.

9. License

MIT License

Package: @rethink-js/rt-smooth-scroll GitHub: https://github.com/Rethink-JS/rt-smooth-scroll

by Rethink JS https://github.com/Rethink-JS