pimdewit/lenis

How smooth scroll should be

Introduction

🚧 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

Features

• Performant
• Lightweight (~2Kb gzipped)
• Run scroll in main thread
• Accessibility (CMD+F page search, Tab and arrow navigation, keep scroll position on page refresh, etc.)
• External RAF
• SSR proof

Installing

just the usual:

$ npm i @studio-freight/lenis

or replace npm with your package manager of choice :)

Setup

Basic setup

import Lenis from '@studio-freight/lenis'

const lenis = new Lenis({
  duration: 1.2,
  easing: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)), // https://easings.net
  smooth: true,
  direction: 'vertical',
})

//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({
  duration: 1.2,
  easing: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)), // https://easings.net
  smooth: true,
  direction: 'vertical',
  wrapper: NodeElement, // element that has overflow
  content: NodeElement, // usually wrapper's direct child
})

Methods

• raf(time) : must be called every frame for internal function.
• scrollTo(target, {offset, immediate, duration, easing}) : scroll to a target.
  • target : can be Number, NodeElement or String (CSS selector).
  • offset : Number equivalent to scroll-padding-top.
• on(id, callback) : execute a function on event.
  • id : event to listen.
    • scroll : return scroll position.
  • callback({scroll, limit}) : function to execute.
• stop() : pause the scroll
• start() : resume the scroll
• destroy() : destroy the instance, remove all events.

Considerations

Things to consider if you want to add Lenis to your codebase will be listed here.

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 {
  width: 100%;
  min-height: 100%;
}

Stop wheel event propagation on elements with overflow (see this issue)

<div onwheel="event.stopPropagation()">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>

Lenis in use

• Wyre by Studio Freight
• Scroll Animation Ideas for Image Grids by Codrops
• Lunchbox by Studio Freight
• How to Animate SVG Shapes on Scroll by Codrops
• Easol by Studio Freight
• Repeat by Studio Freight
• Dragonfly by Studio Freight
• Yuga Labs by Antinomy Studio

Authors

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

License

The MIT License.