Introduction
Lenis ("smooth" in latin) is a lightweight, robust, and performant smooth scroll library. It's designed by @darkroom.engineering 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 syncing, parallax effects, and much more, see Demo and Showcase.
Read our Manifesto to learn more about the inspiration behind Lenis.
Features
- Lightweight & dependency-free — the whole library is a few KB with zero runtime dependencies
- Runs on native scroll — wraps the browser's own scroll, so position: sticky, anchor links, and accessibility keep working
- Any axis — smooth vertical, horizontal, and nested scrolling from a single instance
- Built for sync — drives WebGL scroll scenes, GSAP ScrollTrigger, and parallax off one loop
- Framework adapters — first-class packages for React, Vue, and Framer
- Scroll snapping — the snap plugin aligns sections without fighting the smooth scroll
If you’ve used Lenis and it made your site feel just a little more alive, consider sponsoring.
Your support helps us smooth out the internet one library at a time—and lets us keep building tools that care about the details most folks overlook.
Packages
Installation
Using a package manager:
npm i lenis
# or
yarn add lenis
# or
pnpm add lenis
import Lenis from 'lenis'
Using scripts:
<script src="https://unpkg.com/[email protected]/dist/lenis.min.js"></script>
Setup
Basic:
// Initialize Lenis
const lenis = new Lenis({
autoRaf: true,
});
// Listen for the scroll event and log the event data
lenis.on('scroll', (e) => {
console.log(e);
});
Custom raf loop:
// Initialize Lenis
const lenis = new Lenis();
// Use requestAnimationFrame to continuously update the scroll
function raf(time) {
lenis.raf(time);
requestAnimationFrame(raf);
}
requestAnimationFrame(raf);
Recommended CSS:
Import stylesheet:
import 'lenis/dist/lenis.css'
Or link the CSS file:
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/lenis.css">
Or add it manually:
See lenis.css stylesheet
// Initialize a new Lenis instance for smooth scrolling
const lenis = new Lenis();
// Synchronize Lenis scrolling with GSAP's ScrollTrigger plugin
lenis.on('scroll', ScrollTrigger.update);
// Add Lenis's requestAnimationFrame (raf) method to GSAP's ticker
// This ensures Lenis's smooth scroll animation updates on each GSAP tick
gsap.ticker.add((time) => {
lenis.raf(time * 1000); // Convert time from seconds to milliseconds
});
// Disable lag smoothing in GSAP to prevent any delay in scroll animations
gsap.ticker.lagSmoothing(0);
No-code usage
One line, no build step — just drop this into your HTML:
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/lenis.css">
<script src="https://unpkg.com/[email protected]/dist/lenis.min.js"></script>
<script>new Lenis({ autoRaf: true, autoToggle: true, anchors: true, allowNestedScroll: true, naiveDimensions: true, stopInertiaOnNavigate: true })</script>
That's it, your page now has smooth scrolling and should handle most of the usual issues such as:
- compatibility with other packages
- modals
- smooth anchors
- scroll reset on page change
Settings
| Option |
Type |
Default |
Description |
allowNestedScroll |
boolean |
false |
Automatically allow nested scrollable elements to scroll natively. This is the simplest way to handle nested scroll. ⚠️ Can create performance issues since it checks the DOM tree on every scroll event. If that's a concern, use prevent option instead. |
anchors |
boolean, ScrollToOptions |
false |
Scroll to anchor links when clicked. 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. |
autoRaf |
boolean |
false |
Whether or not to automatically run requestAnimationFrame loop. |
autoResize |
boolean |
true |
Resize instance automatically based on ResizeObserver. If false you must resize manually using .resize(). |
autoToggle |
boolean |
false |
Automatically start or stop the lenis instance based on the wrapper's overflow property, ⚠️ this requires Lenis recommended CSS. Safari > 17.3, Chrome > 116 and Firefox > 128 (https://caniuse.com/?search=transition-behavior). |
content |
HTMLElement |
document.documentElement |
The element that contains the content that will be scrolled, usually wrapper's direct child. |
duration |
number |
1.2 |
The duration of scroll animation (in seconds). Useless if lerp defined. |
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. Useless if lerp defined. |
eventsTarget |
HTMLElement, Window |
wrapper |
The element that will listen to wheel and touch events. |
gestureOrientation |
string |
vertical |
The orientation of the gestures. Can be vertical, horizontal or both. |
infinite |
boolean |
false |
Enable infinite scrolling! syncTouch: true is required on touch devices (See example). |
lerp |
number |
0.1 |
Linear interpolation (lerp) intensity (between 0 and 1). |
naiveDimensions |
boolean |
false |
If true, Lenis will use naive dimensions calculation. ⚠️ Be careful, this has a performance impact. |
orientation |
string |
vertical |
The orientation of the scrolling. Can be vertical or horizontal. |
overscroll |
boolean |
true |
Similar to CSS overscroll-behavior (https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior). |
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'). |
respectReducedMotion |
boolean |
true |
Honor the user's prefers-reduced-motion setting: smoothing is disabled and programmatic scrolls are instant, while scroll keeps running on the main thread (see Reduced motion). |
smoothWheel |
boolean |
true |
Smooth the scroll initiated by wheel events. |
stopInertiaOnNavigate |
boolean |
false |
If true, Lenis will stop inertia when an internal link is clicked. |
syncTouch |
boolean |
false |
Mimic touch device scroll while allowing scroll sync (can be unstable on iOS<16). |
syncTouchLerp |
number |
0.075 |
Lerp applied during syncTouch inertia. |
touchInertiaExponent |
number |
1.7 |
Manage the strength of syncTouch inertia. |
touchMultiplier |
number |
1 |
The multiplier to use for touch events. |
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). |
wheelMultiplier |
number |
1 |
The multiplier to use for mouse wheel events. |
wrapper |
HTMLElement, Window |
window |
The element that will be used as the scroll container. |
|
|
|
|
Properties
| Property |
Type |
Description |
actualScroll |
number |
Current scroll value registered by the browser |
animatedScroll |
number |
Current scroll value |
className (getter) |
string |
rootElement className |
dimensions |
object |
Dimensions instance |
direction |
number |
1: scrolling up, -1: scrolling down |
isHorizontal (getter) |
boolean |
Whether or not the instance is horizontal |
isScrolling (getter) |
boolean, string |
Whether or not the scroll is being animated, smooth, native or false |
isStopped (getter) |
boolean |
Whether or not the user should be able to scroll |
lastVelocity |
number |
Last scroll velocity |
limit (getter) |
number |
Maximum scroll value |
options |
object |
Instance options |
prefersReducedMotion (getter) |
boolean |
Whether the user prefers reduced motion and Lenis is honoring it |
progress (getter) |
number |
Scroll progress from 0 to 1 |
rootElement (getter) |
HTMLElement |
Element on which Lenis is instanced |
scroll (getter) |
number |
Current scroll value (handles infinite scroll if activated) |
targetScroll |
number |
Target scroll value |
time |
number |
Time elapsed since instance creation |
velocity |
number |
Current scroll velocity |
Methods
| Method |
Description |
Arguments |
destroy() |
Destroys the instance and removes all events. |
|
on(id, function) |
id can be any of the following instance events to listen. |
|
raf(time) |
Must be called every frame for internal usage. |
time: in ms |
resize() |
Compute internal sizes, it has to be used if autoResize option is false. |
|
scrollTo(target, options) |
Scroll to target. |
target: goal to reachnumber: value to scroll in pixelsstring: CSS selector or keyword (top, left, start, bottom, right, end)HTMLElement: DOM element
optionsoffset(number): equivalent to scroll-padding-toplerp(number): animation lerp intensityduration(number): animation duration (in seconds)easing(function): animation easingimmediate(boolean): ignore duration, easing and lerplock(boolean): whether or not to prevent the user from scrolling until the target is reachedforce(boolean): reach target even if instance is stoppedonComplete(function): called when the target is reacheduserData(object): this object will be forwarded through scroll events
|
start() |
Resumes the scroll |
|
stop() |
Pauses the scroll |
|
Events
| Event |
Callback Arguments |
scroll |
Lenis instance |
virtual-scroll |
{deltaX, deltaY, event} |
Considerations
The simplest and most reliable way to handle nested scrollable elements is to use the allowNestedScroll option:
const lenis = new Lenis({
allowNestedScroll: true,
})
This automatically detects nested scrollable elements and lets them scroll natively. However, this can create performance issues since Lenis needs to check the DOM tree on every scroll event. If you experience performance problems, use data-lenis-prevent instead.
Using HTML attributes
<div data-lenis-prevent>scrollable content</div>
See example
| Attribute |
Description |
data-lenis-prevent |
Prevent all smooth scroll events |
data-lenis-prevent-wheel |
Prevent wheel events only |
data-lenis-prevent-touch |
Prevent touch events only |
data-lenis-prevent-vertical |
Prevent vertical scroll events only |
data-lenis-prevent-horizontal |
Prevent horizontal scroll events only |
Using Javascript
<div id="modal">scrollable content</div>
const lenis = new Lenis({
prevent: (node) => node.id === 'modal',
})
See example
Anchor links
By default, Lenis will prevent anchor links from working while scrolling. To enable them, you must set anchors: true.
new Lenis({
anchors: true
})
You can also use scrollTo options:
new Lenis({
anchors: {
offset: 100,
onComplete: ()=>{
console.log('scrolled to anchor')
}
}
})
Reduced motion
By default, Lenis honors the user's prefers-reduced-motion setting: when it is set to reduce, smoothing is disabled (lerp is forced to 1 so the scroll tracks the input device 1:1, ignoring duration/easing) and programmatic scrolls (scrollTo, anchor links) jump instantly to their target. Lenis keeps running so WebGL/DOM synchronization stays intact, and the preference is picked up live without a reload. You can check lenis.prefersReducedMotion to adapt your own animations.
You can opt out (not recommended) with:
const lenis = new Lenis({
respectReducedMotion: false,
})
Limitations
- no support for CSS scroll-snap, you must use (lenis/snap)
- capped to 60fps on Safari (source) and 30fps on low power mode
- smooth scroll will stop working over iframe since they don't forward wheel events
- position fixed seems to lag on MacOS Safari pre-M1 (source)
- touch events may behave unexpectedly when
syncTouch is enabled on iOS < 16
- nested scroll containers require proper configuration to work correctly
Troubleshooting
- Make sure you use the latest version of Lenis
- Include the recommended CSS
- If using GSAP ScrollTrigger, ensure proper integration (see GSAP ScrollTrigger setup section)
- Test without Lenis to ensure your element/page is scrollable
- Be sure to use
autoRaf: true or manually call lenis.raf(time) in your animation loop
Tutorials
Plugins
License
MIT © darkroom.engineering
Lenis(拉丁语意为“顺滑”)是 darkroom.engineering 出品的一个轻量级网页平滑滚动库，让页面滚动变得流畅顺滑，同时不会拖累现代浏览器的性能。