Skip to content

Commit b270d33

Browse files
Druhin13Druhin13
committed
feat: upgrade to version 1.2.0 with new features and improvements
- Added support for resolving target elements from string selectors. - Introduced a new function to convert anchor links for smooth scrolling. - Enhanced option reading and parsing for better flexibility. - Improved event listeners for scroll actions, including keyboard accessibility. - Updated documentation and comments for clarity. - Minor optimizations and code cleanup for better maintainability.
1 parent d75e737 commit b270d33

5 files changed

Lines changed: 514 additions & 196 deletions

File tree

‎README.md‎

Lines changed: 94 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@
1313
- **Zero-config defaults** (Lenis defaults, unless you override via attributes)
1414
- Support for **multiple smooth scroll instances**
1515
- A clean global API under `window.rtSmoothScroll`
16-
- Optional resize + mutation observation (useful for wrapper instances)
16+
- **Smart Scroll-To actions** with indexed selectors and dynamic offsets
17+
- **Automatic Anchor Link Conversion** (hijack native links for smooth scrolling)
1718
- Per-instance configuration via HTML attributes
1819
- Console logs showing each instance’s final resolved config
1920

@@ -29,11 +30,13 @@
2930
- [2. Quick Start](#2-quick-start)
3031
- [3. Activation Rules](#3-activation-rules)
3132
- [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)
3740

3841
---
3942

@@ -42,7 +45,7 @@
4245
### 1.1 CDN (jsDelivr)
4346

4447
```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>
4649
```
4750

4851
### 1.2 npm
@@ -67,7 +70,7 @@ Add the script to your page. With no configuration provided, `rt-smooth-scroll`
6770
Example:
6871

6972
```html
70-
<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>
7174
```
7275

7376
> Note: If you do not set any `rt-smooth-scroll-*` config attributes, the root instance uses **Lenis defaults**.
@@ -161,35 +164,86 @@ Add attributes to any scroll container:
161164
| `rt-smooth-scroll-id` | Optional instance identifier |
162165
| `rt-smooth-scroll-content` | Selector inside container (defaults to first child if omitted) |
163166

164-
### Advanced JSON
167+
---
168+
169+
## 5. Scroll-To Actions
170+
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.
165172

166-
You may pass additional Lenis options via:
173+
### Basic Usage
167174

168175
```html
169-
<body
170-
rt-smooth-scroll
171-
rt-smooth-scroll-options-json='{"overscroll":true}'
172-
></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>
212+
```
213+
214+
---
215+
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>
173226
```
174227

175-
### Lenis Loader / Observer Controls
228+
### How it works
176229

177-
| Attribute | Description |
178-
| ------------------------------------- | ------------------------------------------------------------------------------ |
179-
| `rt-smooth-scroll-lenis-src` | Override Lenis CDN URL |
180-
| `rt-smooth-scroll-observe-resize` | Enable `ResizeObserver` for wrapper instances (default: `true` if supported) |
181-
| `rt-smooth-scroll-observe-mutations` | Enable `MutationObserver` for wrapper instances (default: `true` if supported) |
182-
| `rt-smooth-scroll-resize-debounce-ms` | Debounce resize calls (default: `0`) |
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.
183234

184235
---
185236

186-
## 5. Multiple Instances
237+
## 7. Multiple Instances
187238

188239
`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.
189240

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+
190244
---
191245

192-
## 6. Global API
246+
## 8. Global API
193247

194248
After initialization, access:
195249

@@ -199,15 +253,16 @@ window.rtSmoothScroll;
199253

200254
### Common methods:
201255

202-
| Method | Description |
203-
| -------------- | -------------------------------- |
204-
| `ids()` | Array of registered instance ids |
205-
| `get(id)` | Returns Lenis instance |
206-
| `start(id?)` | Start scroll |
207-
| `stop(id?)` | Stop scroll |
208-
| `toggle(id?)` | Toggle scroll |
209-
| `resize(id?)` | Trigger Lenis resize |
210-
| `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 |
211266

212267
**Default root Lenis instance** is also exposed as:
213268

@@ -217,7 +272,7 @@ window.lenis;
217272

218273
---
219274

220-
## 7. Console Logging
275+
## 9. Console Logging
221276

222277
On startup, each instance logs:
223278

@@ -230,7 +285,7 @@ This helps you confirm exactly what configuration is applied in the browser.
230285

231286
---
232287

233-
## 8. Troubleshooting
288+
## 10. Troubleshooting
234289

235290
### Scroll feels laggy / too delayed
236291

@@ -242,27 +297,18 @@ This helps you confirm exactly what configuration is applied in the browser.
242297

243298
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.
244299

245-
### Instance not initialized
246-
247-
Ensure you’ve enabled either:
248-
249-
- the root attribute (`rt-smooth-scroll`), or
250-
- one or more instance elements.
251-
252-
### Lenis fails to load
253-
254-
If using a custom `rt-smooth-scroll-lenis-src`, confirm the URL points to a valid Lenis build.
255-
256300
---
257301

258-
## 9. License
302+
## 11. License
259303

260304
MIT License
261305

262-
Package: `@rethink-js/rt-smooth-scroll` <br>
306+
Package: `@rethink-js/rt-smooth-scroll`
307+
<br>
263308
GitHub: [https://github.com/Rethink-JS/rt-smooth-scroll](https://github.com/Rethink-JS/rt-smooth-scroll)
264309

265310
---
266311

267-
by **Rethink JS** <br>
312+
by **Rethink JS**
313+
<br>
268314
[https://github.com/Rethink-JS](https://github.com/Rethink-JS)

0 commit comments

Comments
 (0)