Skip to content

How smooth scroll should be - smooth full-page scrolling library and demo

License

Notifications You must be signed in to change notification settings

appcrafts/lenis-smooth-scroll

 
 

Repository files navigation

LENIS

npm downloads size

Introduction

Lenis 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 synching, parallax effects and much more. See Demo and Showcase.


Sponsorship

If you like Lenis, please consider sponsoring us. Your support helps us maintain the project and continue to improve it.


Packages


Installation

JavaScript

using a package manager:

npm i lenis
import Lenis from 'lenis'

using scripts:

<script src="https://unpkg.com/lenis@1.1.13/dist/lenis.min.js"></script> 

Setup

Basic:

const lenis = new Lenis()

lenis.on('scroll', (e) => {
  console.log(e)
})

function raf(time) {
  lenis.raf(time)
  requestAnimationFrame(raf)
}

requestAnimationFrame(raf)

Recommended CSS:

html.lenis, html.lenis body {
  height: auto;
}

.lenis.lenis-smooth {
  scroll-behavior: auto !important;
}

.lenis.lenis-smooth [data-lenis-prevent] {
  overscroll-behavior: contain;
}

.lenis.lenis-stopped {
  overflow: hidden;
}

.lenis.lenis-smooth iframe {
  pointer-events: none;
}

or link the CSS file:

<link rel="stylesheet" href="https://unpkg.com/lenis@1.1.13/dist/lenis.css">

or import it:

import 'lenis/dist/lenis.css'

GSAP ScrollTrigger:

const lenis = new Lenis()

lenis.on('scroll', (e) => {
  console.log(e)
})

lenis.on('scroll', ScrollTrigger.update)

gsap.ticker.add((time)=>{
  lenis.raf(time * 1000)
})

gsap.ticker.lagSmoothing(0)

React:

See documentation for lenis/react.


Instance settings

Option Type Default Description
wrapper HTMLElement, Window window The element that will be used as the scroll container
content HTMLElement document.documentElement The element that contains the content that will be scrolled, usually wrapper's direct child
eventsTarget HTMLElement, Window wrapper The element that will listen to wheel and touch events
smoothWheel boolean true Smooth the scroll initiated by wheel events
lerp number 0.1 Linear interpolation (lerp) intensity (between 0 and 1)
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
orientation string vertical The orientation of the scrolling. Can be vertical or horizontal
gestureOrientation string vertical The orientation of the gestures. Can be vertical, horizontal or both
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
touchInertiaMultiplier number 35 Manage the the strength of syncTouch inertia
wheelMultiplier number 1 The multiplier to use for mouse wheel events
touchMultiplier number 1 The multiplier to use for touch events
infinite boolean false Enable infinite scrolling! syncTouch: true is required on touch devices. (See example)
autoResize boolean true Resize instance automatically based on ResizeObserver. If false you must resize manually using .resize()
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')
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)

Instance Props

Property Type Description
animatedScroll number Current scroll value
dimensions object Dimensions instance
direction number 1: scrolling up, -1: scrolling down
emitter object Emitter instance
options object Instance options
targetScroll number Target scroll value
time number Time elapsed since instance creation
actualScroll number Current scroll value registered by the browser
lastVelocity number last scroll velocity
velocity number Current scroll velocity
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
limit (getter) number Maximum scroll value
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)
className (getter) string rootElement className

Instance Methods

Method Description Arguments
raf(time) Must be called every frame for internal usage. time: in ms
scrollTo(target, options) Scroll to target. target: goal to reach
  • number: value to scroll in pixels
  • string: CSS selector or keyword (top, left, start, bottom, target): goal to reach
    • number: value to scroll in pixels
    • string: CSS selector or keyword (top, left, start, bottom, right, end)
    • HTMLElement: DOM element
    options
    • offset(number): equivalent to scroll-padding-top
    • lerp(number): animation lerp intensity
    • duration(number): animation duration (in seconds)
    • easing(function): animation easing
    • immediate(boolean): ignore duration, easing and lerp
    • lock(boolean): whether or not to prevent the user from scrolling until the target is reached
    • force(boolean): reach target even if instance is stopped
    • onComplete(function): called when the target is reached
    • userData(object): this object will be forwarded through scroll events
on(id, function) id can be any of the following instance events to listen.
stop() Pauses the scroll
start() Resumes the scroll
resize() Compute internal sizes, it has to be used if autoResize option is false.
destroy() Destroys the instance and removes all events.

Instance Events

Event Callback Arguments
scroll Lenis instance
virtual-scroll {deltaX, deltaY, event}

Considerations

Nested scroll

Using Javascript

<div id="modal">scrollable content</div>
const lenis = new Lenis({
  prevent: (node) => node.id === 'modal',
})

Using HTML

<div data-lenis-prevent>scrollable content</div>

prevent wheel events only

<div data-lenis-prevent-wheel>scrollable content</div>

prevent touch events only

<div data-lenis-prevent-touch>scrollable content</div>

See modal example

Anchor links

<a href="#anchor" onclick="lenis.scrollTo('#anchor')">scroll to anchor</a>

Limitations

  • no support for CSS scroll-snap (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)

Tutorials


Plugins


Lenis in use


Authors

This set of hooks is curated and maintained by the darkroom.engineering team:


License

The MIT License.

About

How smooth scroll should be - smooth full-page scrolling library and demo

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 44.8%
  • TypeScript 28.8%
  • SCSS 21.4%
  • CSS 3.2%
  • Other 1.8%