@rethink-js/rt-smooth-scroll 1.0.2 → 1.2.0

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.
Files changed (6) hide show
  1. package/README.md +131 -65
  2. package/dist/index.js +313 -148
  3. package/dist/index.js.map +2 -2
  4. package/dist/index.min.js +2 -2
  5. package/dist/index.min.js.map +3 -3
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -9,15 +9,16 @@
9
9
 
10
10
  `rt-smooth-scroll` is a lightweight JavaScript library that seamlessly integrates the **Lenis smooth scroll engine** into your sites with:
11
11
 
12
- - **Automatic Lenis loading** (no extra installs/styles needed)
13
- - **Zero-config defaults** that work out of the box
12
+ - **Automatic Lenis loading** (no extra installs needed)
13
+ - **Zero-config defaults** (Lenis defaults, unless you override via attributes)
14
14
  - Support for **multiple smooth scroll instances**
15
15
  - A clean global API under `window.rtSmoothScroll`
16
- - Automatic resize + mutation observation for reliable reflow handling
16
+ - **Smart Scroll-To actions** with indexed selectors and dynamic offsets
17
+ - **Automatic Anchor Link Conversion** (hijack native links for smooth scrolling)
17
18
  - Per-instance configuration via HTML attributes
18
19
  - Console logs showing each instance’s final resolved config
19
20
 
20
- **Lenis GitHub:** https://github.com/studio-freight/lenis
21
+ **Lenis (GitHub):** https://github.com/darkroomengineering/lenis
21
22
 
22
23
  ---
23
24
 
@@ -29,11 +30,13 @@
29
30
  - [2. Quick Start](#2-quick-start)
30
31
  - [3. Activation Rules](#3-activation-rules)
31
32
  - [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)
33
+ - [5. Scroll-To Actions](#5-scroll-to-actions)
34
+ - [6. Anchor Link Conversion](#6-anchor-link-conversion)
35
+ - [7. Multiple Instances](#7-multiple-instances)
36
+ - [8. Global API](#8-global-api)
37
+ - [9. Console Logging](#9-console-logging)
38
+ - [10. Troubleshooting](#10-troubleshooting)
39
+ - [11. License](#11-license)
37
40
 
38
41
  ---
39
42
 
@@ -42,7 +45,7 @@
42
45
  ### 1.1 CDN (jsDelivr)
43
46
 
44
47
  ```html
45
- <script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>
48
+ <script src="[https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js](https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js)"></script>
46
49
  ```
47
50
 
48
51
  ### 1.2 npm
@@ -59,8 +62,7 @@ Then bundle or load `dist/index.min.js` as appropriate for your build setup.
59
62
 
60
63
  Add the script to your page. With no configuration provided, `rt-smooth-scroll` will:
61
64
 
62
- - Enable itself automatically
63
- - Apply recommended default settings to `<body>`
65
+ - Activate itself automatically (if you didn’t explicitly opt out)
64
66
  - Load Lenis from CDN
65
67
  - Create a root smooth scroll instance
66
68
  - Expose the global API
@@ -68,9 +70,11 @@ Add the script to your page. With no configuration provided, `rt-smooth-scroll`
68
70
  Example:
69
71
 
70
72
  ```html
71
- <script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js"></script>
73
+ <script src="[https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js](https://cdn.jsdelivr.net/npm/@rethink-js/rt-smooth-scroll@latest/dist/index.min.js)"></script>
72
74
  ```
73
75
 
76
+ > Note: If you do not set any `rt-smooth-scroll-*` config attributes, the root instance uses **Lenis defaults**.
77
+
74
78
  ---
75
79
 
76
80
  ## 3. Activation Rules
@@ -80,7 +84,7 @@ The library is activated when:
80
84
  - The attribute `rt-smooth-scroll` exists on `<html>` or `<body>` **OR**
81
85
  - You place one or more elements with `rt-smooth-scroll-instance`
82
86
 
83
- If neither is present and no instance elements are found, it **auto-enables** itself on `<body>` with defaults.
87
+ 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).
84
88
 
85
89
  ---
86
90
 
@@ -107,22 +111,29 @@ Place on `<html>` or `<body>` to configure defaults:
107
111
  ></body>
108
112
  ```
109
113
 
114
+ Important Lenis behavior:
115
+
116
+ - `duration` and `easing` are **useless if `lerp` is defined** (this is how Lenis works).
117
+
110
118
  **Core attributes:**
111
119
 
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:**
120
+ | Attribute | Description |
121
+ | ------------------------------------------- | ------------------------------------------------------------ |
122
+ | `rt-smooth-scroll-duration` | Lenis `duration` (only applies when `lerp` is not used) |
123
+ | `rt-smooth-scroll-lerp` | Lenis `lerp` (0 → 1) |
124
+ | `rt-smooth-scroll-orientation` | Lenis `orientation` |
125
+ | `rt-smooth-scroll-gesture-orientation` | Lenis `gestureOrientation` |
126
+ | `rt-smooth-scroll-normalize-wheel` | Lenis `normalizeWheel` |
127
+ | `rt-smooth-scroll-wheel-multiplier` | Lenis `wheelMultiplier` |
128
+ | `rt-smooth-scroll-smooth-touch` | Lenis `smoothTouch` |
129
+ | `rt-smooth-scroll-sync-touch` | Lenis `syncTouch` |
130
+ | `rt-smooth-scroll-sync-touch-lerp` | Lenis `syncTouchLerp` |
131
+ | `rt-smooth-scroll-touch-inertia-multiplier` | Lenis `touchInertiaMultiplier` |
132
+ | `rt-smooth-scroll-touch-multiplier` | Lenis `touchMultiplier` |
133
+ | `rt-smooth-scroll-infinite` | Lenis `infinite` |
134
+ | `rt-smooth-scroll-easing` | Named easing function (only applies when `lerp` is not used) |
135
+
136
+ **Easing options included:**
126
137
 
127
138
  - `linear`
128
139
  - `easeInQuad`
@@ -147,32 +158,92 @@ Add attributes to any scroll container:
147
158
  ></div>
148
159
  ```
149
160
 
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 |
161
+ | Attribute | Description |
162
+ | --------------------------- | -------------------------------------------------------------- |
163
+ | `rt-smooth-scroll-instance` | Marks scroll container |
164
+ | `rt-smooth-scroll-id` | Optional instance identifier |
165
+ | `rt-smooth-scroll-content` | Selector inside container (defaults to first child if omitted) |
166
+
167
+ ---
168
+
169
+ ## 5. Scroll-To Actions
155
170
 
156
- ### Advanced JSON
171
+ You can trigger a smooth scroll to any element, position, or specific instance using the `rt-smooth-scroll-to` attribute on any clickable element.
157
172
 
158
- You may pass additional Lenis options via:
173
+ ### Basic Usage
159
174
 
160
175
  ```html
161
- <body
162
- rt-smooth-scroll
163
- rt-smooth-scroll-options-json='{"overscroll":true}'
164
- ></body>
176
+ <button rt-smooth-scroll-to="#footer">Go to Footer</button>
177
+
178
+ <button rt-smooth-scroll-to="top">Back to Top</button>
179
+
180
+ <button rt-smooth-scroll-to="500">Go to 500px</button>
181
+ ```
182
+
183
+ ### Indexed Selectors
184
+
185
+ You can target elements by class order (1-based index) using `.class(N)` syntax.
186
+
187
+ ```html
188
+ <button rt-smooth-scroll-to=".section(2)">Go to Section 2</button>
189
+ ```
190
+
191
+ ### Customization Attributes
192
+
193
+ You can customize the scroll behavior for specific triggers.
194
+
195
+ | Attribute | Description |
196
+ | ---------------------------- | ------------------------------------------------------------------ |
197
+ | `rt-smooth-scroll-offset` | Offset in pixels. **Supports selectors!** (See below) |
198
+ | `rt-smooth-scroll-duration` | Override scroll duration for this action |
199
+ | `rt-smooth-scroll-immediate` | Jump instantly (true/false) |
200
+ | `rt-smooth-scroll-lock` | Lock scroll during animation |
201
+ | `rt-smooth-scroll-force` | Force scroll even if stopped |
202
+ | `rt-smooth-scroll-target-id` | **Explicitly** target a specific scroll instance ID (e.g. "panel") |
203
+
204
+ ### Dynamic Element Offsets
205
+
206
+ Instead of hardcoding pixels, you can pass a selector to `rt-smooth-scroll-offset`. The library will calculate that element's `offsetHeight` and apply it as a **negative offset** (perfect for sticky headers).
207
+
208
+ ```html
209
+ <button rt-smooth-scroll-to="#about" rt-smooth-scroll-offset="#nav">
210
+ About
211
+ </button>
165
212
  ```
166
213
 
167
214
  ---
168
215
 
169
- ## 5. Multiple Instances
216
+ ## 6. Anchor Link Conversion
217
+
218
+ You can automatically convert standard `<a>` tags (e.g., `<a href="#contact">`) into smooth scroll triggers without manually adding attributes to every link.
219
+
220
+ ### Enable Conversion
221
+
222
+ Add this attribute to your `<body>` or `<html>` tag:
223
+
224
+ ```html
225
+ <body rt-smooth-scroll rt-smooth-scroll-anchor-links="true"></body>
226
+ ```
227
+
228
+ ### How it works
229
+
230
+ 1. **Auto-Detection:** Finds all links pointing to a hash on the current page.
231
+ 2. **Hijacking:** Converts them to use the `rt-smooth-scroll-to` logic.
232
+ 3. **Clean URLs:** Removes the `href` attribute so the browser URL bar does **not** update (no `#hash` in URL), keeping your history clean.
233
+ 4. **Accessibility:** Automatically restores `tabindex="0"`, `role="button"`, `cursor: pointer`, and keyboard `Enter` key support.
234
+
235
+ ---
236
+
237
+ ## 7. Multiple Instances
170
238
 
171
239
  `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
240
 
241
+ **Context Awareness:**
242
+ If a `rt-smooth-scroll-to` button is placed **inside** a nested scroll instance, it will automatically control that parent instance, not the root window, unless you explicitly override it with `rt-smooth-scroll-target-id`.
243
+
173
244
  ---
174
245
 
175
- ## 6. Global API
246
+ ## 8. Global API
176
247
 
177
248
  After initialization, access:
178
249
 
@@ -182,15 +253,16 @@ window.rtSmoothScroll;
182
253
 
183
254
  ### Common methods:
184
255
 
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 |
256
+ | Method | Description |
257
+ | ------------------ | ------------------------------------------------------------------- |
258
+ | `ids()` | Array of registered instance ids |
259
+ | `get(id)` | Returns Lenis instance |
260
+ | `start(id?)` | Start scroll |
261
+ | `stop(id?)` | Stop scroll |
262
+ | `toggle(id?)` | Toggle scroll |
263
+ | `resize(id?)` | Trigger Lenis resize |
264
+ | `refreshAnchors()` | Manually re-run anchor link conversion (useful for dynamic content) |
265
+ | `destroy(id?)` | Remove instance |
194
266
 
195
267
  **Default root Lenis instance** is also exposed as:
196
268
 
@@ -200,7 +272,7 @@ window.lenis;
200
272
 
201
273
  ---
202
274
 
203
- ## 7. Console Logging
275
+ ## 9. Console Logging
204
276
 
205
277
  On startup, each instance logs:
206
278
 
@@ -213,27 +285,21 @@ This helps you confirm exactly what configuration is applied in the browser.
213
285
 
214
286
  ---
215
287
 
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
288
+ ## 10. Troubleshooting
224
289
 
225
- Ensure you’ve enabled either:
290
+ ### Scroll feels laggy / too delayed
226
291
 
227
- - the root attribute (`rt-smooth-scroll`), or
228
- - one or more instance elements.
292
+ - **Increase** `rt-smooth-scroll-lerp` (e.g. `0.2 → 0.35`) for a snappier response.
293
+ - **Decrease** `rt-smooth-scroll-lerp` (e.g. `0.1 → 0.05`) for a smoother/heavier feel.
294
+ - Leave `rt-smooth-scroll-wheel-multiplier="1"` unless you have a strong reason to change perceived speed.
229
295
 
230
- ### Lenis fails to load
296
+ ### Duration / easing doesn’t seem to do anything
231
297
 
232
- If using a custom `rt-smooth-scroll-lenis-src`, confirm the URL points to a valid Lenis build.
298
+ 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.
233
299
 
234
300
  ---
235
301
 
236
- ## 9. License
302
+ ## 11. License
237
303
 
238
304
  MIT License
239
305