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
- 2. Quick Start
- 3. Activation Rules
- 4. Configuration (HTML Attributes)
- 5. Multiple Instances
- 6. Global API
- 7. Console Logging
- 8. Troubleshooting
- 9. License
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>npm install @rethink-js/rt-smooth-scrollThen bundle or load dist/index.min.js as appropriate for your build setup.
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.
The library is activated when:
- The attribute
rt-smooth-scrollexists 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).
Add to <html> or <body> to enable:
<body rt-smooth-scroll></body>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:
durationandeasingare useless iflerpis 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:
lineareaseInQuadeaseOutQuadeaseInOutQuadeaseInCubiceaseOutCubiceaseInOutCubiceaseInOutSineeaseOutExpo
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) |
You may pass additional Lenis options via:
<body
rt-smooth-scroll
rt-smooth-scroll-options-json='{"overscroll":true}'
></body>| 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) |
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.
After initialization, access:
window.rtSmoothScroll;| 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;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.
- 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.
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.
Ensure you’ve enabled either:
- the root attribute (
rt-smooth-scroll), or - one or more instance elements.
If using a custom rt-smooth-scroll-lenis-src, confirm the URL points to a valid Lenis build.
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