🚧 Still in WIP, API might change with new releases 🚧
This is our take on smooth scroll, lightweight, hard working, smooth as butter scroll. See Demo
- Performant
- Lightweight (~2Kb gzipped)
- Run scroll in main thread
- Accessibility (CMD+F page search, keyboard navigation, keep scroll position on page refresh, etc.)
- External RAF
- SSR proof
- Not opinionated
- Tree-shakeable
- Custom scroll easing/duration
| Feature | Locomotive-scroll | GSAP ScrollSmoother | Lenis |
|---|---|---|---|
| Native scrollbar | ❌ | ✅ | ✅ |
| Native scroll inputs | ❌ | ✅ | ❌ |
| Normalize scroll experience | ✅ | ❌ | ✅ |
| Accessibility | ❌ | ❌ | ✅ |
| CSS Sticky | ❌ | ❌ | ✅ |
| IntsersectionObserver | ❌ | ❌ | ✅ |
| Open source | ✅ | ❌ | ✅ |
| Built-in animation system | ✅ | ✅ | ❌ |
| Size (gzip) | 12.33KB | 26.08KB | 2.13kb |
using package manager:
$ npm i @studio-freight/lenisusing scripts:
<script src="https://cdn.jsdelivr.net/gh/studio-freight/[email protected]/bundled/lenis.js"></script>
Basic setup
import Lenis from '@studio-freight/lenis'
const lenis = new Lenis({
duration: 1.2,
easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)), // https://www.desmos.com/calculator/brs54l4xou
direction: 'vertical', // vertical, horizontal
gestureDirection: 'vertical', // vertical, horizontal, both
smooth: true,
mouseMultiplier: 1,
smoothTouch: false,
touchMultiplier: 2,
infinite: false,
})
//get scroll value
lenis.on('scroll', ({ scroll, limit, velocity, direction, progress }) => {
console.log({ scroll, limit, velocity, direction, progress })
})
function raf(time) {
lenis.raf(time)
requestAnimationFrame(raf)
}
requestAnimationFrame(raf)Using custom scroll container
const lenis = new Lenis({
wrapper: NodeElement, // element which has overflow
content: NodeElement, // usually wrapper's direct child
})| Option | Type | Default | Description |
|---|---|---|---|
wrapper |
NodeElement |
window |
Default element which has overflow |
content |
NodeElement |
document.body |
wrapper's direct child |
duration |
number |
1.2 |
Specifies the duration of the animation |
easing |
function |
(t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)) |
Specifies the rate of change of a specific value, our default is custom but you can pick one from Easings.net |
direction |
string |
vertical |
vertical or horizontal scrolling. |
gestureDirection |
string |
vertical |
vertical, horizontal or both. |
smooth |
boolean |
true |
Enable or disable 'smoothness' |
mouseMultiplier |
number |
1 |
This value is passed directly to Virtual Scroll |
smoothTouch |
boolean |
false |
Enable or disable 'smoothness' while scrolling using touch. Note: We have disabled it by default because touch devices native smoothness is impossible to mimic |
touchMultiplier |
number |
string |
This value is passed directly to Virtual Scroll |
infinite |
boolean |
false |
Enable infinite scrolling! |
| Method | Description | Arguments |
|---|---|---|
raf(time) |
Must be called every frame for internal usage. | |
scrollTo(target,{offset, duration, easing, immediate}) |
Scroll to a target. | target: can be Number, NodeElement or String (CSS selector).offset : Number equivalent to scroll-padding-top.duration : Number scroll duration in seconds.easing : Function.immediate : ignore duration and easing. |
on(id,callback({scroll,limit,velocity,direction})) |
id can be any of the following instance events to listen. |
|
stop() |
To pause the scroll | |
start() |
To resume the scroll | |
destroy() |
To destroy the instance and remove all events. |
| Event | Callback Arguments |
|---|---|
scroll |
scroll: returns scroll position. limit: returns scroll limit. velocity: returns scroll velocity. direction: returns 1 or -1. |
Make sure scroll-behavior is set to initial or not set at all (thanks @thagxt)
html {
scroll-behavior: initial;
}Keep html and body elements default sized (see this issue)
html,
body {
min-height: 100%;
height: auto;
}Use data-lenis-prevent attribute on nested scroll elements. In addition, we advise you to add overscroll-behavior: contain on this element.
<div data-lenis-prevent>scroll content</div>Manually use lenis.scrollTo('#anchor') on anchor link click (see this issue)
<a href="#anchor" onclick="lenis.scrollTo('#anchor')">scroll to anchor</a>- no support of CSS scroll-snap
- can only run 60fps maximum on Safari (source)
- Scroll Animation Ideas for Image Grids by Codrops
- How to Animate SVG Shapes on Scroll by Codrops
- The BEST smooth scrolling library for your Webflow website! (Lenis) by Diego Toda de Oliveira
- Easy smooth scroll in @Webflow with Lenis + GSAP ScrollTrigger tutorial by También Studio
- Wyre by Studio Freight
- Lunchbox by Studio Freight
- Easol by Studio Freight
- Repeat by Studio Freight
- Dragonfly by Studio Freight
- Yuga Labs by Antinomy Studio
- Quentin Hocde's Portfolio by Quentin Hocde
- Houses Of by Félix P. & Shelby Kay
- Shelby Kay's Portfolio by Shelby Kay
- Heights Agency Portfolio by Francesco Michelini
- Goodship by Studio Freight
- Flayks' Portfolio by Félix P. & Shelby Kay
- Matt Rothenberg's portfolio by Matt Rothenberg
- Edoardo Lunardi's portfolio by Edoardo Lunardi
This set of hooks is curated and maintained by the Studio Freight Darkroom team:
- Clement Roche (@clementroche_) – Studio Freight
- Guido Fier (@uido15) – Studio Freight
- Leandro Soengas (@lsoengas) - Studio Freight
- Franco Arza (@arzafran) - Studio Freight