Skip to content

Latest commit

 

History

History
248 lines (179 loc) · 20.5 KB

README-v1.md

File metadata and controls

248 lines (179 loc) · 20.5 KB
Raw

LENIS

npm version

Introduction

This is our take on smooth scroll, lightweight, hard working, smooth as butter scroll. See Demo


Features

  • Performant
  • Lightweight (<4Kb gzipped)
  • Run scroll in main thread
  • Accessibility (CMD+F page search, keyboard navigation, keep scroll position on page refresh, etc.)
  • External RAF
  • SSR proof
  • Custom scroll easing and 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.1KB 26.08KB 3.6KB

Installing

using package manager:

$ npm i @studio-freight/lenis
import Lenis from '@studio-freight/lenis'

using scripts:

<script src="https://cdn.jsdelivr.net/gh/studio-freight/[email protected]/bundled/lenis.js"></script>

Setup

Basic setup

const lenis = new Lenis()

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

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

requestAnimationFrame(raf)

Instance settings

Option Type Default Description
wrapper `HTMLElement Window` window
content HTMLElement document.documentElement The element that contains the content that will be scrolled, usually wrapper's direct child
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
smoothWheel boolean true Whether or not to enable smooth scrolling for mouse wheel events
smoothTouch boolean false Whether or not to enable smooth scrolling for touch events. Note: We have disabled it by default because touch devices native smoothness is impossible to mimic
wheelMultiplier number 1 The multiplier to use for mouse wheel events
touchMultiplier number 2 The multiplier to use for touch events
normalizeWheel boolean true Normalize wheel inputs across browsers
infinite boolean false Enable infinite scrolling!

Instance Methods

Method Description Arguments
raf(time) Must be called every frame for internal usage. time: in ms
scrollTo(target, options) Scroll to a target. 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 user from scrolling until target reached
  • onComplete(function): called when target is reached
on(id, function) id can be any of the following instance events to listen.
stop() Pauses the scroll
start() Resumes the scroll
destroy() Destroys the instance and remove all events.

Instance Events

Event Callback Arguments
scroll scroll: returns scroll position.
limit: returns scroll limit.
velocity: returns scroll velocity.
direction: returns 1 or -1.

Considerations

Make sure scroll-behavior is set to auto or not set at all

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

Keep html elements default sized, this is necessary for Webflow implementation (see issue).

html.lenis {
  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>
.lenis.lenis-smooth [data-lenis-prevent] {
  overscroll-behavior: contain;
}

Manually use lenis.scrollTo('#anchor') on anchor link click (see issue)

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

Hide overflow when lenis is stopped

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

GSAP ScrollTrigger integration

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

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

Limitations

  • no support for CSS scroll-snap
  • capped to 60fps on Safari (source)
  • 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

-react-lenis


Lenis in use


Authors

This set of hooks is curated and maintained by the Studio Freight Darkroom team:


License

The MIT License.