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, 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 |

Installing

using package manager:

$ npm i @studio-freight/lenis

using scripts:

<script src="https://cdn.jsdelivr.net/gh/studio-freight/lenis@latest/bundled/lenis.js"></script>

Setup

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
})

Instance settings

| Option | Type | Default | Description | | ------------------ | ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | wrapper | NodeElement | window | Default element which has overflow | | content | NodeElement | document | 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! |

Methods

• raf(time) : must be called every frame for internal function.
• 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) : execute a function on event.
  • id : event to listen.
    • scroll : return scroll position.
  • callback(e) : 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>

Plugins

• Loconative-scroll by Quentin Hocde

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
• Quentin Hocde's Portfolio by Quentin Hocde
• Houses Of by Félix P. & Shelby Kay
• Shelby Kay's Portfolio by Shelby Kay

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.