@rethink-js/rt-smooth-scroll 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +248 -1
- package/dist/index.js +1 -1
- package/dist/index.min.js +1 -1
- package/package.json +18 -2
package/README.md
CHANGED
|
@@ -1 +1,248 @@
|
|
|
1
|
-
# rt-smooth-scroll
|
|
1
|
+
# rt-smooth-scroll
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@rethink-js/rt-smooth-scroll)
|
|
6
|
+
[](https://www.jsdelivr.com/package/npm/@rethink-js/rt-smooth-scroll)
|
|
7
|
+
[](https://bundlephobia.com/package/@rethink-js/rt-smooth-scroll)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
|
|
10
|
+
`rt-smooth-scroll` is a lightweight JavaScript library that seamlessly integrates the **Lenis smooth scroll engine** into your sites with:
|
|
11
|
+
|
|
12
|
+
- **Automatic Lenis loading** (no extra installs/styles needed)
|
|
13
|
+
- **Zero-config defaults** that work out of the box
|
|
14
|
+
- Support for **multiple smooth scroll instances**
|
|
15
|
+
- A clean global API under `window.rtSmoothScroll`
|
|
16
|
+
- Automatic resize + mutation observation for reliable reflow handling
|
|
17
|
+
- Per-instance configuration via HTML attributes
|
|
18
|
+
- Console logs showing each instance’s final resolved config
|
|
19
|
+
|
|
20
|
+
**Lenis GitHub:** https://github.com/studio-freight/lenis
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
# Table of Contents
|
|
25
|
+
|
|
26
|
+
- [1. Installation](#1-installation)
|
|
27
|
+
- [1.1 CDN (jsDelivr)](#11-cdn-jsdelivr)
|
|
28
|
+
- [1.2 npm](#12-npm)
|
|
29
|
+
- [2. Quick Start](#2-quick-start)
|
|
30
|
+
- [3. Activation Rules](#3-activation-rules)
|
|
31
|
+
- [4. Configuration (HTML Attributes)](#4-configuration-html-attributes)
|
|
32
|
+
- [5. Multiple Instances](#5-multiple-instances)
|
|
33
|
+
- [6. Global API](#6-global-api)
|
|
34
|
+
- [7. Console Logging](#7-console-logging)
|
|
35
|
+
- [8. Troubleshooting](#8-troubleshooting)
|
|
36
|
+
- [9. License](#9-license)
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 1. Installation
|
|
41
|
+
|
|
42
|
+
### 1.1 CDN (jsDelivr)
|
|
43
|
+
|
|
44
|
+
```html
|
|
45
|
+
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### 1.2 npm
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm install @rethink-js/rt-smooth-scroll
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Then bundle or load `dist/index.min.js` as appropriate for your build setup.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 2. Quick Start
|
|
59
|
+
|
|
60
|
+
Add the script to your page. With no configuration provided, `rt-smooth-scroll` will:
|
|
61
|
+
|
|
62
|
+
- Enable itself automatically
|
|
63
|
+
- Apply recommended default settings to `<body>`
|
|
64
|
+
- Load Lenis from CDN
|
|
65
|
+
- Create a root smooth scroll instance
|
|
66
|
+
- Expose the global API
|
|
67
|
+
|
|
68
|
+
Example:
|
|
69
|
+
|
|
70
|
+
```html
|
|
71
|
+
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## 3. Activation Rules
|
|
77
|
+
|
|
78
|
+
The library is activated when:
|
|
79
|
+
|
|
80
|
+
- The attribute `rt-smooth-scroll` exists on `<html>` or `<body>` **OR**
|
|
81
|
+
- You place one or more elements with `rt-smooth-scroll-instance`
|
|
82
|
+
|
|
83
|
+
If neither is present and no instance elements are found, it **auto-enables** itself on `<body>` with defaults.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 4. Configuration (HTML Attributes)
|
|
88
|
+
|
|
89
|
+
### Root Mode
|
|
90
|
+
|
|
91
|
+
Add to `<html>` or `<body>` to enable:
|
|
92
|
+
|
|
93
|
+
```html
|
|
94
|
+
<body rt-smooth-scroll></body>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Global Options
|
|
98
|
+
|
|
99
|
+
Place on `<html>` or `<body>` to configure defaults:
|
|
100
|
+
|
|
101
|
+
```html
|
|
102
|
+
<body
|
|
103
|
+
rt-smooth-scroll
|
|
104
|
+
rt-smooth-scroll-lerp="0.2"
|
|
105
|
+
rt-smooth-scroll-wheel-multiplier="1"
|
|
106
|
+
rt-smooth-scroll-easing="easeOutCubic"
|
|
107
|
+
></body>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Core attributes:**
|
|
111
|
+
|
|
112
|
+
| Attribute | Description |
|
|
113
|
+
| -------------------------------------- | --------------------------- |
|
|
114
|
+
| `rt-smooth-scroll-duration` | Lenis `duration` value |
|
|
115
|
+
| `rt-smooth-scroll-lerp` | Lenis `lerp` value |
|
|
116
|
+
| `rt-smooth-scroll-orientation` | Scroll orientation |
|
|
117
|
+
| `rt-smooth-scroll-gesture-orientation` | Gesture orientation |
|
|
118
|
+
| `rt-smooth-scroll-normalize-wheel` | Normalize wheel input |
|
|
119
|
+
| `rt-smooth-scroll-wheel-multiplier` | Multiplies wheel delta |
|
|
120
|
+
| `rt-smooth-scroll-sync-touch` | Sync touch behavior |
|
|
121
|
+
| `rt-smooth-scroll-touch-multiplier` | Multiplies touch delta |
|
|
122
|
+
| `rt-smooth-scroll-infinite` | Enable infinite scroll mode |
|
|
123
|
+
| `rt-smooth-scroll-easing` | Named easing function |
|
|
124
|
+
|
|
125
|
+
**Easing options include:**
|
|
126
|
+
|
|
127
|
+
- `linear`
|
|
128
|
+
- `easeInQuad`
|
|
129
|
+
- `easeOutQuad`
|
|
130
|
+
- `easeInOutQuad`
|
|
131
|
+
- `easeInCubic`
|
|
132
|
+
- `easeOutCubic`
|
|
133
|
+
- `easeInOutCubic`
|
|
134
|
+
- `easeInOutSine`
|
|
135
|
+
- `easeOutExpo`
|
|
136
|
+
|
|
137
|
+
### Per-Instance Configuration
|
|
138
|
+
|
|
139
|
+
Add attributes to any scroll container:
|
|
140
|
+
|
|
141
|
+
```html
|
|
142
|
+
<div
|
|
143
|
+
rt-smooth-scroll-instance
|
|
144
|
+
rt-smooth-scroll-id="panel"
|
|
145
|
+
rt-smooth-scroll-content=".scroll-content"
|
|
146
|
+
rt-smooth-scroll-lerp="0.18"
|
|
147
|
+
></div>
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
| Attribute | Description |
|
|
151
|
+
| --------------------------- | ---------------------------- |
|
|
152
|
+
| `rt-smooth-scroll-instance` | Marks scroll container |
|
|
153
|
+
| `rt-smooth-scroll-id` | Optional instance identifier |
|
|
154
|
+
| `rt-smooth-scroll-content` | Selector inside container |
|
|
155
|
+
|
|
156
|
+
### Advanced JSON
|
|
157
|
+
|
|
158
|
+
You may pass additional Lenis options via:
|
|
159
|
+
|
|
160
|
+
```html
|
|
161
|
+
<body
|
|
162
|
+
rt-smooth-scroll
|
|
163
|
+
rt-smooth-scroll-options-json='{"overscroll":true}'
|
|
164
|
+
></body>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## 5. Multiple Instances
|
|
170
|
+
|
|
171
|
+
`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.
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## 6. Global API
|
|
176
|
+
|
|
177
|
+
After initialization, access:
|
|
178
|
+
|
|
179
|
+
```js
|
|
180
|
+
window.rtSmoothScroll;
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Common methods:
|
|
184
|
+
|
|
185
|
+
| Method | Description |
|
|
186
|
+
| -------------- | -------------------------------- |
|
|
187
|
+
| `ids()` | Array of registered instance ids |
|
|
188
|
+
| `get(id)` | Returns Lenis instance |
|
|
189
|
+
| `start(id?)` | Start scroll |
|
|
190
|
+
| `stop(id?)` | Stop scroll |
|
|
191
|
+
| `toggle(id?)` | Toggle scroll |
|
|
192
|
+
| `resize(id?)` | Trigger Lenis resize |
|
|
193
|
+
| `destroy(id?)` | Remove instance |
|
|
194
|
+
|
|
195
|
+
**Default root Lenis instance** is also exposed as:
|
|
196
|
+
|
|
197
|
+
```js
|
|
198
|
+
window.lenis;
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## 7. Console Logging
|
|
204
|
+
|
|
205
|
+
On startup, each instance logs:
|
|
206
|
+
|
|
207
|
+
- Instance ID
|
|
208
|
+
- Wrapper element
|
|
209
|
+
- Content element
|
|
210
|
+
- Final resolved options
|
|
211
|
+
|
|
212
|
+
This helps you confirm exactly what configuration is applied in the browser.
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## 8. Troubleshooting
|
|
217
|
+
|
|
218
|
+
### Scroll feels laggy
|
|
219
|
+
|
|
220
|
+
- Lower `lerp` (e.g., `0.18–0.3`) for snappier response.
|
|
221
|
+
- Avoid combining duration and lerp unintentionally.
|
|
222
|
+
|
|
223
|
+
### Instance not initialized
|
|
224
|
+
|
|
225
|
+
Ensure you’ve enabled either:
|
|
226
|
+
|
|
227
|
+
- the root attribute (`rt-smooth-scroll`), or
|
|
228
|
+
- one or more instance elements.
|
|
229
|
+
|
|
230
|
+
### Lenis fails to load
|
|
231
|
+
|
|
232
|
+
If using a custom `rt-smooth-scroll-lenis-src`, confirm the URL points to a valid Lenis build.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## 9. License
|
|
237
|
+
|
|
238
|
+
MIT License
|
|
239
|
+
|
|
240
|
+
Package: `@rethink-js/rt-smooth-scroll`
|
|
241
|
+
<br>
|
|
242
|
+
GitHub: [https://github.com/Rethink-JS/rt-smooth-scroll](https://github.com/Rethink-JS/rt-smooth-scroll)
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
by **Rethink JS**
|
|
247
|
+
<br>
|
|
248
|
+
[https://github.com/Rethink-JS](https://github.com/Rethink-JS)
|
package/dist/index.js
CHANGED
package/dist/index.min.js
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
/*! @rethink-js/rt-smooth-scroll v1.0.
|
|
1
|
+
/*! @rethink-js/rt-smooth-scroll v1.0.2 | MIT */
|
|
2
2
|
(()=>{(function(){var p="rtSmoothScroll";if(window[p]&&window[p].__initialized)return;function O(o,n){return!o||!o.hasAttribute(n)?null:o.getAttribute(n)}function z(o){var n=document.documentElement,t=document.body,e=O(n,o);return e!==null||(e=O(t,o),e!==null)?e:null}function q(o){var n=document.documentElement,t=document.body;return!!(n&&n.hasAttribute(o)||t&&t.hasAttribute(o))}function g(o,n){if(o==null)return n;var t=String(o).trim().toLowerCase();return t===""||t==="true"||t==="1"||t==="yes"||t==="y"||t==="on"?!0:t==="false"||t==="0"||t==="no"||t==="n"||t==="off"?!1:n}function y(o,n){if(o==null)return n;var t=Number(o);return Number.isFinite(t)?t:n}function A(o,n){if(o==null)return n;var t=String(o);return t.length?t:n}function m(o){return o<0?0:o>1?1:o}function j(o){var n=String(o||"").trim();if(!n)return null;var t={linear:function(e){return m(e)},easeInQuad:function(e){return e=m(e),e*e},easeOutQuad:function(e){return e=m(e),e*(2-e)},easeInOutQuad:function(e){return e=m(e),e<.5?2*e*e:1-Math.pow(-2*e+2,2)/2},easeInCubic:function(e){return e=m(e),e*e*e},easeOutCubic:function(e){return e=m(e),1-Math.pow(1-e,3)},easeInOutCubic:function(e){return e=m(e),e<.5?4*e*e*e:1-Math.pow(-2*e+2,3)/2},easeInOutSine:function(e){return e=m(e),-(Math.cos(Math.PI*e)-1)/2},easeOutExpo:function(e){return e=m(e),e===1?1:1-Math.pow(2,-10*e)}};return t[n]||null}function x(o){if(!o)return!1;for(var n=0;n<o.attributes.length;n++){var t=o.attributes[n].name;if(t&&t.indexOf("rt-smooth-scroll-")===0)return!0}return!1}function P(){var o=document.body,n=document.documentElement;if(o){var t=document.querySelectorAll("[rt-smooth-scroll-instance]"),e=t&&t.length>0;!q("rt-smooth-scroll")&&!e&&o.setAttribute("rt-smooth-scroll","");var f=x(n)||x(o);if(!(f||e)){var h={"rt-smooth-scroll-lerp":"0.25","rt-smooth-scroll-orientation":"vertical","rt-smooth-scroll-gesture-orientation":"vertical","rt-smooth-scroll-normalize-wheel":"true","rt-smooth-scroll-wheel-multiplier":"1","rt-smooth-scroll-easing":"easeOutCubic","rt-smooth-scroll-smooth-touch":"true","rt-smooth-scroll-sync-touch":"true","rt-smooth-scroll-sync-touch-lerp":"0","rt-smooth-scroll-touch-inertia-multiplier":"10","rt-smooth-scroll-touch-multiplier":"2"};for(var v in h)!n.hasAttribute(v)&&!o.hasAttribute(v)&&o.setAttribute(v,h[v])}}}function E(o){var n="rt-smooth-scroll-";function t(w){var S=o(w);return S!=null?S:z(w)}var e=t(n+"duration"),f=t(n+"lerp"),h=e!=null&&String(e).trim()!=="",v=f!=null&&String(f).trim()!=="",s=y(e,1.15),b=y(f,.25);h&&!v&&(b=0);var I=A(t(n+"orientation"),"vertical"),T=A(t(n+"gesture-orientation"),"vertical"),C=g(t(n+"normalize-wheel"),!0),_=y(t(n+"wheel-multiplier"),1),L=g(t(n+"smooth-touch"),!0),F=g(t(n+"sync-touch"),!0),N=y(t(n+"sync-touch-lerp"),0),R=y(t(n+"touch-inertia-multiplier"),10),i=y(t(n+"touch-multiplier"),2),r=g(t(n+"infinite"),!1),u=A(t(n+"easing"),"easeOutCubic"),a=j(u),c={lerp:b,orientation:I,gestureOrientation:T,normalizeWheel:C,wheelMultiplier:_,smoothTouch:L,syncTouch:F,syncTouchLerp:N,touchInertiaMultiplier:R,touchMultiplier:i,infinite:r};b===0&&(c.duration=s),a&&(c.easing=a);var l=t(n+"options-json");if(l)try{var d=JSON.parse(l);if(d&&typeof d=="object")for(var M in d)c[M]=d[M]}catch(w){}return c}function Q(o){return new Promise(function(n,t){if(typeof window.Lenis!="undefined")return n();var e=document.querySelector('script[data-rt-lenis="true"]');if(e){e.addEventListener("load",function(){n()}),e.addEventListener("error",function(h){t(h)});return}var f=document.createElement("script");f.src=o,f.async=!0,f.dataset.rtLenis="true",f.onload=function(){n()},f.onerror=function(h){t(h)},document.head.appendChild(f)})}function D(){P();var o=q("rt-smooth-scroll"),n=document.querySelectorAll("[rt-smooth-scroll-instance]"),t=o||n&&n.length>0;if(!t)return;var e=A(z("rt-smooth-scroll-lenis-src"),"https://cdn.jsdelivr.net/npm/lenis@1.3.16/dist/lenis.min.js"),f=g(z("rt-smooth-scroll-observe-resize"),!0),h=g(z("rt-smooth-scroll-observe-mutations"),!0),v=y(z("rt-smooth-scroll-resize-debounce-ms"),0),s={destroyed:!1,rafId:0,instances:{},order:[],observers:{},resizeTimers:{}};function b(i){var r=s.instances[i];if(!(!r||s.destroyed)){if(v>0){clearTimeout(s.resizeTimers[i]),s.resizeTimers[i]=setTimeout(function(){var u=s.instances[i];!u||s.destroyed||u.resize()},v);return}r.resize()}}function I(){function i(r){if(!s.destroyed){for(var u=0;u<s.order.length;u++){var a=s.order[u],c=s.instances[a];c&&c.raf(r)}s.rafId=requestAnimationFrame(i)}}s.rafId=requestAnimationFrame(i)}function T(i,r){if(!(!r||r===window)){var u=null,a=null;f&&typeof ResizeObserver!="undefined"&&(u=new ResizeObserver(function(){b(i)}),u.observe(r)),h&&typeof MutationObserver!="undefined"&&(a=new MutationObserver(function(){b(i)}),a.observe(r,{childList:!0,subtree:!0})),s.observers[i]={ro:u,mo:a}}}function C(i){var r=s.observers[i];r&&(r.ro&&r.ro.disconnect(),r.mo&&r.mo.disconnect(),delete s.observers[i])}function _(i){var r={};for(var u in i)if(Object.prototype.hasOwnProperty.call(i,u)){var a=i[u];typeof a=="function"?r[u]="[Function]":r[u]=a}return r}function L(i,r,u,a){var c=a||{};r&&(c.wrapper=r),u&&(c.content=u);var l=new window.Lenis(c);s.instances[i]=l,s.order.push(i),r&&r!==window&&T(i,r),i==="root"&&(window.lenis=l);try{console.log("[rt-smooth-scroll] instance:",i,{wrapper:r===window?"window":r,content:u||null,options:_(c)})}catch(d){}return l}function F(i){var r=O(i,"rt-smooth-scroll-content");if(r){var u=i.querySelector(r);if(u)return u}return i.firstElementChild||i}function N(){function i(r,u){if(typeof r=="string"&&r.length){var a=s.instances[r];a&&u(r,a);return}for(var c=0;c<s.order.length;c++){var l=s.order[c],d=s.instances[l];d&&u(l,d)}}return{__initialized:!0,ids:function(){return s.order.slice()},get:function(r){return s.instances[r]||null},start:function(r){i(r,function(u,a){a.start()})},stop:function(r){i(r,function(u,a){a.stop()})},toggle:function(r,u){i(r,function(a,c){if(typeof u=="boolean"){u?c.stop():c.start();return}c.isStopped?c.start():c.stop()})},resize:function(r){i(r,function(u){b(u)})},destroy:function(r){if(s.destroyed)return;function u(a){clearTimeout(s.resizeTimers[a]),C(a);var c=s.instances[a];if(c){try{c.destroy()}catch(d){}delete s.instances[a]}var l=s.order.indexOf(a);if(l>=0&&s.order.splice(l,1),a==="root")try{delete window.lenis}catch(d){window.lenis=void 0}}if(typeof r=="string"&&r.length){u(r);return}for(;s.order.length;)u(s.order[0]);s.destroyed=!0,s.rafId&&cancelAnimationFrame(s.rafId)}}}function R(i){window.disableScroll=function(){i.stop(),document.body&&document.body.classList.add("no-scroll")},window.enableScroll=function(){i.start(),document.body&&document.body.classList.remove("no-scroll")}}Q(e).then(function(){if(!s.destroyed){if(o&&!s.instances.root){var i=E(function(){return null});L("root",window,document.documentElement,i)}for(var r=document.querySelectorAll("[rt-smooth-scroll-instance]"),u=0,a=0;a<r.length;a++){var c=r[a],l=O(c,"rt-smooth-scroll-id");if(l||(u++,l="instance-"+u),!s.instances[l]){var d=F(c),M=E(function(S){return O(c,S)});L(l,c,d,M)}}I();var w=N();window[p]=w,R(w),window.addEventListener("resize",function(){w.resize()})}}).catch(function(){})}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",D):D(),window[p]=window[p]||{__initialized:!0,ids:function(){return[]},get:function(){return null}}})();})();
|
|
3
3
|
//# sourceMappingURL=index.min.js.map
|
package/package.json
CHANGED
|
@@ -1,7 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rethink-js/rt-smooth-scroll",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.0.2",
|
|
4
|
+
"description": "Lightweight smooth scrolling powered by Lenis with automatic loading, attribute config, and multi-instance support.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"smooth-scroll",
|
|
7
|
+
"lenis",
|
|
8
|
+
"scroll",
|
|
9
|
+
"javascript",
|
|
10
|
+
"ui",
|
|
11
|
+
"animation",
|
|
12
|
+
"interactive",
|
|
13
|
+
"scrolling",
|
|
14
|
+
"rt-smooth-scroll",
|
|
15
|
+
"rethink-js"
|
|
16
|
+
],
|
|
17
|
+
"author": "Rethink JS <opensource@rethink-js.org> (https://github.com/Rethink-JS)",
|
|
5
18
|
"license": "MIT",
|
|
6
19
|
"repository": {
|
|
7
20
|
"type": "git",
|
|
@@ -22,6 +35,9 @@
|
|
|
22
35
|
"build": "node scripts/build.mjs",
|
|
23
36
|
"prepublishOnly": "npm run build"
|
|
24
37
|
},
|
|
38
|
+
"publishConfig": {
|
|
39
|
+
"access": "public"
|
|
40
|
+
},
|
|
25
41
|
"devDependencies": {
|
|
26
42
|
"esbuild": "^0.27.2"
|
|
27
43
|
}
|