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({
  lerp: 0.1,
  smooth: true,
  direction: 'vertical',
})

//get scroll value
lenis.on('scroll', ({ scroll, limit, velocity, direction, progress }) => {
  console.log({ scroll, limit, velocity, direction, progress })
})

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

requestAnimationFrame(raf)

Using custom scroll container

const lenis = new Lenis({
  lerp: 0.1,
  smooth: true,
  direction: 'vertical',
  wrapper: NodeElement, // element that has overflow
  content: NodeElement, // usually wrapper's direct child
})

Methods

• raf() : must be called every frame for internal function.
• scrollTo(target, {offset}) : 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%;
}

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

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.