lenis 1.1.21-dev.0 → 1.1.21
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/LICENSE +8 -8
- package/README.md +354 -329
- package/dist/lenis-react.mjs.map +1 -1
- package/dist/lenis-snap.js.map +1 -1
- package/dist/lenis-snap.min.js.map +1 -1
- package/dist/lenis-snap.mjs.map +1 -1
- package/dist/lenis-vue-nuxt.mjs +14 -0
- package/dist/lenis-vue.mjs +0 -6
- package/dist/lenis-vue.mjs.map +1 -1
- package/dist/lenis.js +1 -1
- package/dist/lenis.js.map +1 -1
- package/dist/lenis.min.js +1 -1
- package/dist/lenis.min.js.map +1 -1
- package/dist/lenis.mjs +1 -1
- package/dist/lenis.mjs.map +1 -1
- package/package.json +91 -89
package/README.md
CHANGED
|
@@ -1,329 +1,354 @@
|
|
|
1
|
-
[](https://www.npmjs.com/package/lenis)
|
|
5
|
-
[](https://www.npmjs.com/package/lenis)
|
|
7
|
-
[![size](https://img.shields.io/bundlephobia/minzip/lenis?label=size&colorA=
|
|
8
|
-
|
|
9
|
-
## Introduction
|
|
10
|
-
|
|
11
|
-
Lenis ("smooth" in latin) is a lightweight, robust, and performant smooth scroll library. It's designed by [@darkroom.engineering](https://twitter.com/darkroomdevs) to be simple to use and easy to integrate into your projects. It's built with performance in mind and is optimized for modern browsers. It's perfect for creating smooth scrolling experiences on your website such as webgl scroll synching, parallax effects and much more, see [ Demo](https://lenis.darkroom.engineering/) and [Showcase](#lenis-in-use).
|
|
12
|
-
|
|
13
|
-
Read our [Manifesto](https://github.com/darkroomengineering/lenis/blob/main/MANIFESTO.md) to learn more about the inspiration behind Lenis.
|
|
14
|
-
|
|
15
|
-
<br/>
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
<br
|
|
34
|
-
|
|
35
|
-
##
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
```js
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
|
154
|
-
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
`
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
|
197
|
-
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
|
206
|
-
|
|
207
|
-
| `
|
|
208
|
-
| `
|
|
209
|
-
| `
|
|
210
|
-
| `
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
213
|
-
| `
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
-
|
|
313
|
-
-
|
|
314
|
-
|
|
315
|
-
<br>
|
|
316
|
-
|
|
317
|
-
##
|
|
318
|
-
|
|
319
|
-
-
|
|
320
|
-
-
|
|
321
|
-
-
|
|
322
|
-
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
1
|
+
[](https://github.com/darkroomengineering/lenis)
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/lenis)
|
|
5
|
+
[](https://www.npmjs.com/package/lenis)
|
|
7
|
+
[](https://bundlephobia.com/package/lenis)
|
|
8
|
+
|
|
9
|
+
## Introduction
|
|
10
|
+
|
|
11
|
+
Lenis ("smooth" in latin) is a lightweight, robust, and performant smooth scroll library. It's designed by [@darkroom.engineering](https://twitter.com/darkroomdevs) to be simple to use and easy to integrate into your projects. It's built with performance in mind and is optimized for modern browsers. It's perfect for creating smooth scrolling experiences on your website such as webgl scroll synching, parallax effects and much more, see [ Demo](https://lenis.darkroom.engineering/) and [Showcase](#lenis-in-use).
|
|
12
|
+
|
|
13
|
+
Read our [Manifesto](https://github.com/darkroomengineering/lenis/blob/main/MANIFESTO.md) to learn more about the inspiration behind Lenis.
|
|
14
|
+
|
|
15
|
+
<br/>
|
|
16
|
+
|
|
17
|
+
- [Sponsors](#sponsors)
|
|
18
|
+
- [Packages](#packages)
|
|
19
|
+
- [Installation](#installation)
|
|
20
|
+
- [Setup](#setup)
|
|
21
|
+
- [Settings](#settings)
|
|
22
|
+
- [Properties](#properties)
|
|
23
|
+
- [Methods](#methods)
|
|
24
|
+
- [Events](#events)
|
|
25
|
+
- [Considerations](#considerations)
|
|
26
|
+
- [Limitations](#limitations)
|
|
27
|
+
- [Troubleshooting](#troubleshooting)
|
|
28
|
+
- [Tutorials](#tutorials)
|
|
29
|
+
- [Plugins](#plugins)
|
|
30
|
+
- [Lenis is Use](#lenis-in-use)
|
|
31
|
+
- [License](#license)
|
|
32
|
+
|
|
33
|
+
<br/>
|
|
34
|
+
|
|
35
|
+
## Sponsors
|
|
36
|
+
|
|
37
|
+
If you like Lenis, please consider [becoming a sponsor](https://github.com/sponsors/darkroomengineering). Your support helps us to smooth the web one library at a time.
|
|
38
|
+
|
|
39
|
+
[](https://smsunarto.com/) [](https://www.ironvelvet.studio/) [](https://www.cachet.studio/) [](https://non-linear.studio/) [](https://www.federic.ooo/)
|
|
40
|
+
|
|
41
|
+
<br>
|
|
42
|
+
|
|
43
|
+
## Packages
|
|
44
|
+
|
|
45
|
+
- [lenis](https://github.com/darkroomengineering/lenis/blob/main/README.md)
|
|
46
|
+
- [lenis/react](https://github.com/darkroomengineering/lenis/blob/main/packages/react/README.md)
|
|
47
|
+
- [lenis/vue](https://github.com/darkroomengineering/lenis/tree/main/packages/vue/README.md)
|
|
48
|
+
- [lenis/snap](https://github.com/darkroomengineering/lenis/tree/main/packages/snap/README.md)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
<br>
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
using a package manager:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm i lenis
|
|
59
|
+
```
|
|
60
|
+
```js
|
|
61
|
+
import Lenis from 'lenis'
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
<br/>
|
|
65
|
+
|
|
66
|
+
using scripts:
|
|
67
|
+
|
|
68
|
+
```html
|
|
69
|
+
<script src="https://unpkg.com/lenis@1.1.21/dist/lenis.min.js"></script>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
<br>
|
|
74
|
+
|
|
75
|
+
## Setup
|
|
76
|
+
|
|
77
|
+
### Basic:
|
|
78
|
+
|
|
79
|
+
```js
|
|
80
|
+
// Initialize Lenis
|
|
81
|
+
const lenis = new Lenis({
|
|
82
|
+
autoRaf: true,
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
// Listen for the scroll event and log the event data
|
|
86
|
+
lenis.on('scroll', (e) => {
|
|
87
|
+
console.log(e);
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Custom raf loop:
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
// Initialize Lenis
|
|
95
|
+
const lenis = new Lenis();
|
|
96
|
+
|
|
97
|
+
// Use requestAnimationFrame to continuously update the scroll
|
|
98
|
+
function raf(time) {
|
|
99
|
+
lenis.raf(time);
|
|
100
|
+
requestAnimationFrame(raf);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
requestAnimationFrame(raf);
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Recommended CSS:
|
|
107
|
+
|
|
108
|
+
import stylesheet
|
|
109
|
+
```js
|
|
110
|
+
import 'lenis/dist/lenis.css'
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
or link the CSS file:
|
|
114
|
+
|
|
115
|
+
```html
|
|
116
|
+
<link rel="stylesheet" href="https://unpkg.com/lenis@1.1.21/dist/lenis.css">
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
or add it manually:
|
|
120
|
+
|
|
121
|
+
[See lenis.css stylesheet](./packages/core/lenis.css)
|
|
122
|
+
|
|
123
|
+
### GSAP ScrollTrigger:
|
|
124
|
+
```js
|
|
125
|
+
// Initialize a new Lenis instance for smooth scrolling
|
|
126
|
+
const lenis = new Lenis();
|
|
127
|
+
|
|
128
|
+
// Synchronize Lenis scrolling with GSAP's ScrollTrigger plugin
|
|
129
|
+
lenis.on('scroll', ScrollTrigger.update);
|
|
130
|
+
|
|
131
|
+
// Add Lenis's requestAnimationFrame (raf) method to GSAP's ticker
|
|
132
|
+
// This ensures Lenis's smooth scroll animation updates on each GSAP tick
|
|
133
|
+
gsap.ticker.add((time) => {
|
|
134
|
+
lenis.raf(time * 1000); // Convert time from seconds to milliseconds
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
// Disable lag smoothing in GSAP to prevent any delay in scroll animations
|
|
138
|
+
gsap.ticker.lagSmoothing(0);
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### React:
|
|
143
|
+
[See documentation for lenis/react](https://github.com/darkroomengineering/lenis/blob/main/packages/react/README.md).
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
<br/>
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
## Settings
|
|
152
|
+
|
|
153
|
+
| Option | Type | Default | Description |
|
|
154
|
+
|--------------------------|-----------------------------|----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
155
|
+
| `wrapper` | `HTMLElement, Window` | `window` | The element that will be used as the scroll container |
|
|
156
|
+
| `content` | `HTMLElement` | `document.documentElement` | The element that contains the content that will be scrolled, usually `wrapper`'s direct child |
|
|
157
|
+
| `eventsTarget` | `HTMLElement, Window` | `wrapper` | The element that will listen to `wheel` and `touch` events |
|
|
158
|
+
| `smoothWheel` | `boolean` | `true` | Smooth the scroll initiated by `wheel` events |
|
|
159
|
+
| `lerp` | `number` | `0.1` | Linear interpolation (lerp) intensity (between 0 and 1) |
|
|
160
|
+
| `duration` | `number` | `1.2` | The duration of scroll animation (in seconds). Useless if lerp defined |
|
|
161
|
+
| `easing` | `function` | `(t) => Math.min(1, 1.001 - Math.pow(2, -10 * t))` | The easing function to use for the scroll animation, our default is custom but you can pick one from [Easings.net](https://easings.net/en). Useless if lerp defined |
|
|
162
|
+
| `orientation` | `string` | `vertical` | The orientation of the scrolling. Can be `vertical` or `horizontal` |
|
|
163
|
+
| `gestureOrientation` | `string` | `vertical` | The orientation of the gestures. Can be `vertical`, `horizontal` or `both` |
|
|
164
|
+
| `syncTouch` | `boolean` | `false` | Mimic touch device scroll while allowing scroll sync (can be unstable on iOS<16) |
|
|
165
|
+
| `syncTouchLerp` | `number` | `0.075` | Lerp applied during `syncTouch` inertia |
|
|
166
|
+
| `touchInertiaMultiplier` | `number` | `35` | Manage the strength of syncTouch inertia |
|
|
167
|
+
| `wheelMultiplier` | `number` | `1` | The multiplier to use for mouse wheel events |
|
|
168
|
+
| `touchMultiplier` | `number` | `1` | The multiplier to use for touch events |
|
|
169
|
+
| `infinite` | `boolean` | `false` | Enable infinite scrolling! `syncTouch: true` is required on touch devices. ([See example](https://codepen.io/ClementRoche/pen/OJqBLod)) |
|
|
170
|
+
| `autoResize` | `boolean` | `true` | Resize instance automatically based on `ResizeObserver`. If `false` you must resize manually using `.resize()` |
|
|
171
|
+
| `prevent` | `function` | `undefined` | Manually prevent scroll to be smoothed based on elements traversed by events. If `true` is returned, it will prevent the scroll to be smoothed. Example: `(node) => node.classList.contains('cookie-modal')` |
|
|
172
|
+
| `virtualScroll` | `function` | `undefined` | Manually modify the events before they get consumed. If `false` is returned, the scroll will not be smoothed. Examples: `(e) => { e.deltaY /= 2 }` (to slow down vertical scroll) or `({ event }) => !event.shiftKey` (to prevent scroll to be smoothed if shift key is pressed) |
|
|
173
|
+
| `overscroll` | `boolean` | `true` | Wether or not to enable overscroll on a nested Lenis instance, similar to CSS overscroll-behavior (https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior) |
|
|
174
|
+
| `autoRaf` | `boolean` | `false` | Wether or not to automatically run `requestAnimationFrame` loop |
|
|
175
|
+
| `anchors` | `boolean | ScrollToOptions` | `false` | Wether or not to enable anchor links. If `true` is passed, it will enable anchor links with default options. If `ScrollToOptions` is passed, it will enable anchor links with the given options. |
|
|
176
|
+
<br/>
|
|
177
|
+
|
|
178
|
+
<!-- `target`: goal to reach
|
|
179
|
+
- `number`: value to scroll in pixels
|
|
180
|
+
- `string`: CSS selector or keyword (`top`, `left`, `start`, `bottom`, `right`, `end`)
|
|
181
|
+
- `HTMLElement`: DOM element
|
|
182
|
+
|
|
183
|
+
<br/>
|
|
184
|
+
|
|
185
|
+
`options`:
|
|
186
|
+
- `offset`(`number`): equivalent to [`scroll-padding-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding-top)
|
|
187
|
+
- `lerp`(`number`): animation lerp intensity
|
|
188
|
+
- `duration`(`number`): animation duration (in seconds)
|
|
189
|
+
- `easing`(`function`): animation easing
|
|
190
|
+
- `immediate`(`boolean`): ignore duration, easing and lerp
|
|
191
|
+
- `lock`(`boolean`): whether or not to prevent user from scrolling until target reached
|
|
192
|
+
- `onComplete`(`function`): called when target is reached -->
|
|
193
|
+
|
|
194
|
+
## Properties
|
|
195
|
+
|
|
196
|
+
| Property | Type | Description |
|
|
197
|
+
|-------------------------|-------------------|----------------------------------------------------------------------------|
|
|
198
|
+
| `animatedScroll` | `number` | Current scroll value |
|
|
199
|
+
| `dimensions` | `object` | Dimensions instance |
|
|
200
|
+
| `direction` | `number` | `1`: scrolling up, `-1`: scrolling down |
|
|
201
|
+
| `emitter` | `object` | Emitter instance |
|
|
202
|
+
| `options` | `object` | Instance options |
|
|
203
|
+
| `targetScroll` | `number` | Target scroll value |
|
|
204
|
+
| `time` | `number` | Time elapsed since instance creation |
|
|
205
|
+
| `actualScroll` | `number` | Current scroll value registered by the browser |
|
|
206
|
+
| `lastVelocity` | `number` | last scroll velocity |
|
|
207
|
+
| `velocity` | `number` | Current scroll velocity |
|
|
208
|
+
| `isHorizontal` (getter) | `boolean` | Whether or not the instance is horizontal |
|
|
209
|
+
| `isScrolling` (getter) | `boolean, string` | Whether or not the scroll is being animated, `smooth`, `native` or `false` |
|
|
210
|
+
| `isStopped` (getter) | `boolean` | Whether or not the user should be able to scroll |
|
|
211
|
+
| `limit` (getter) | `number` | Maximum scroll value |
|
|
212
|
+
| `progress` (getter) | `number` | Scroll progress from `0` to `1` |
|
|
213
|
+
| `rootElement` (getter) | `HTMLElement` | Element on which Lenis is instanced |
|
|
214
|
+
| `scroll` (getter) | `number` | Current scroll value (handles infinite scroll if activated) |
|
|
215
|
+
| `className` (getter) | `string` | `rootElement` className |
|
|
216
|
+
|
|
217
|
+
<br/>
|
|
218
|
+
|
|
219
|
+
## Methods
|
|
220
|
+
|
|
221
|
+
| Method | Description | Arguments |
|
|
222
|
+
|-----------------------------|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
223
|
+
| `raf(time)` | Must be called every frame for internal usage. | `time`: in ms |
|
|
224
|
+
| `scrollTo(target, options)` | Scroll to target. | `target`: goal to reach<ul><li>`number`: value to scroll in pixels</li><li>`string`: CSS selector or keyword (`top`, `left`, `start`, `bottom`, `right`, `end`)</li><li>`HTMLElement`: DOM element</li></ul>`options`<ul><li>`offset`(`number`): equivalent to [`scroll-padding-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding-top)</li><li>`lerp`(`number`): animation lerp intensity</li><li>`duration`(`number`): animation duration (in seconds)</li><li>`easing`(`function`): animation easing</li><li>`immediate`(`boolean`): ignore duration, easing and lerp</li><li>`lock`(`boolean`): whether or not to prevent the user from scrolling until the target is reached</li><li>`force`(`boolean`): reach target even if instance is stopped</li><li>`onComplete`(`function`): called when the target is reached</li><li>`userData`(`object`): this object will be forwarded through `scroll` events</li></ul> |
|
|
225
|
+
| `on(id, function)` | `id` can be any of the following [instance events](#instance-events) to listen. | |
|
|
226
|
+
| `stop()` | Pauses the scroll | |
|
|
227
|
+
| `start()` | Resumes the scroll | |
|
|
228
|
+
| `resize()` | Compute internal sizes, it has to be used if `autoResize` option is `false`. | |
|
|
229
|
+
| `destroy()` | Destroys the instance and removes all events. | |
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
## Events
|
|
234
|
+
|
|
235
|
+
| Event | Callback Arguments |
|
|
236
|
+
|------------------|---------------------------|
|
|
237
|
+
| `scroll` | Lenis instance |
|
|
238
|
+
| `virtual-scroll` | `{deltaX, deltaY, event}` |
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
<br/>
|
|
242
|
+
|
|
243
|
+
## Considerations
|
|
244
|
+
|
|
245
|
+
### Nested scroll
|
|
246
|
+
|
|
247
|
+
#### Using Javascript
|
|
248
|
+
|
|
249
|
+
```html
|
|
250
|
+
<div id="modal">scrollable content</div>
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
```js
|
|
254
|
+
const lenis = new Lenis({
|
|
255
|
+
prevent: (node) => node.id === 'modal',
|
|
256
|
+
})
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
[See example](https://codepen.io/ClementRoche/pen/emONGYN)
|
|
260
|
+
|
|
261
|
+
#### Using HTML
|
|
262
|
+
|
|
263
|
+
```html
|
|
264
|
+
<div data-lenis-prevent>scrollable content</div>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
[See example](https://codepen.io/ClementRoche/pen/PoLdjpw)
|
|
268
|
+
|
|
269
|
+
prevent wheel events only
|
|
270
|
+
|
|
271
|
+
```html
|
|
272
|
+
<div data-lenis-prevent-wheel>scrollable content</div>
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
prevent touch events only
|
|
276
|
+
|
|
277
|
+
```html
|
|
278
|
+
<div data-lenis-prevent-touch>scrollable content</div>
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
### Anchor links
|
|
284
|
+
By default Lenis will prevent anchor links click while scrolling, to fix that you must set `anchors: true`.
|
|
285
|
+
|
|
286
|
+
```js
|
|
287
|
+
new Lenis({
|
|
288
|
+
anchors: true
|
|
289
|
+
})
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
You can also use `scrollTo` options.
|
|
293
|
+
```js
|
|
294
|
+
new Lenis({
|
|
295
|
+
anchors: {
|
|
296
|
+
offset: 100,
|
|
297
|
+
onComplete: ()=>{
|
|
298
|
+
console.log('scrolled to anchor')
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
})
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
<br>
|
|
305
|
+
|
|
306
|
+
## Limitations
|
|
307
|
+
|
|
308
|
+
- no support for CSS scroll-snap, you must use ([lenis/snap](https://github.com/darkroomengineering/lenis/tree/main/packages/snap/README.md))
|
|
309
|
+
- capped to 60fps on Safari ([source](https://bugs.webkit.org/show_bug.cgi?id=173434)) and 30fps on low power mode
|
|
310
|
+
- smooth scroll will stop working over iframe since they don't forward wheel events
|
|
311
|
+
- position fixed seems to lag on MacOS Safari pre-M1 ([source](https://github.com/darkroomengineering/lenis/issues/103))
|
|
312
|
+
- touch events may behave unexpectedly when `syncTouch` is enabled on iOS < 16
|
|
313
|
+
- nested scroll containers require proper configuration to work correctly
|
|
314
|
+
|
|
315
|
+
<br>
|
|
316
|
+
|
|
317
|
+
## Troubleshooting
|
|
318
|
+
- Make sure you use the latest version of [Lenis](https://www.npmjs.com/package/lenis?activeTab=versions)
|
|
319
|
+
- Include recommended CSS.
|
|
320
|
+
- Remove GSAP ScrollTrigger.
|
|
321
|
+
- Remove Lenis and be sure that your element/page is scrollable anyway.
|
|
322
|
+
- Be sure to use `autoRaf: true` or to manually call `lenis.raf(time)`.
|
|
323
|
+
|
|
324
|
+
<br>
|
|
325
|
+
|
|
326
|
+
## Tutorials
|
|
327
|
+
|
|
328
|
+
- [Scroll Animation Ideas for Image Grids](https://tympanus.net/Development/ScrollAnimationsGrid/) by [Codrops](https://tympanus.net/codrops)
|
|
329
|
+
- [How to Animate SVG Shapes on Scroll](https://tympanus.net/codrops/2022/06/08/how-to-animate-svg-shapes-on-scroll) by [Codrops](https://tympanus.net/codrops)
|
|
330
|
+
- [The BEST smooth scrolling library for your Webflow website! (Lenis)](https://www.youtube.com/watch?v=VtCqTLRRMII) by [Diego Toda de Oliveira](https://www.diegoliv.works/)
|
|
331
|
+
- [Easy smooth scroll in @Webflow with Lenis + GSAP ScrollTrigger tutorial](https://www.youtube.com/watch?v=gRKuzQTXq74) by [También Studio](https://www.tambien.studio/)
|
|
332
|
+
|
|
333
|
+
<br>
|
|
334
|
+
|
|
335
|
+
## Plugins
|
|
336
|
+
|
|
337
|
+
- [r3f-scroll-rig](https://github.com/14islands/r3f-scroll-rig) by [14islands](https://14islands.com/)
|
|
338
|
+
- [locomotive-scroll](https://github.com/locomotivemtl/locomotive-scroll) by [Locomotive](https://locomotive.ca/)
|
|
339
|
+
|
|
340
|
+
<br>
|
|
341
|
+
|
|
342
|
+
## Lenis in use
|
|
343
|
+
|
|
344
|
+
- [DeSo](https://deso.com) by [Studio Freight](https://www.studiofreight.com/)
|
|
345
|
+
- [Sculpting Harmony](https://gehry.getty.edu/) by [Resn](https://resn.co.nz/)
|
|
346
|
+
- [Superpower](https://superpower.com/)
|
|
347
|
+
- [Daylight Computer](https://daylightcomputer.com/) by [Basement Studio](https://basement.studio/)
|
|
348
|
+
- [Lifeworld by Olafur Eliasson](https://lifeworld.wetransfer.com/) by Nicolas Garnier, Simon Riisnæs Dagfinrud, Lumír Španihel, Everton Guilherme, Diana Alcausin, Cristiana Sousa
|
|
349
|
+
|
|
350
|
+
<br/>
|
|
351
|
+
|
|
352
|
+
## License
|
|
353
|
+
|
|
354
|
+
MIT © [darkroom.engineering](https://github.com/darkroomengineering)
|