lenis Documentation

Technical Documentation: darkroomengineering/lenis

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Introduction Copy Chapter

Lenis ("smooth" in latin) 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 syncing, parallax effects, and much more, see Demo and Showcase.

Read our Manifesto to learn more about the inspiration behind Lenis.

• Features
• Sponsors
• Packages
• Showcase
• Installation
• Setup
• No-code usage
• Settings
• Properties
• Methods
• Events
• Considerations
• Limitations
• Troubleshooting
• Tutorials
• Plugins
• License

Features Copy Chapter

• Lightweight & dependency-free — the whole library is a few KB with zero runtime dependencies
• Runs on native scroll — wraps the browser's own scroll, so position: sticky, anchor links, and accessibility keep working
• Any axis — smooth vertical, horizontal, and nested scrolling from a single instance
• Built for sync — drives WebGL scroll scenes, GSAP ScrollTrigger, and parallax off one loop
• Framework adapters — first-class packages for React, Vue, and Framer
• Scroll snapping — the snap plugin aligns sections without fighting the smooth scroll

Sponsors Copy Chapter

If you’ve used Lenis and it made your site feel just a little more alive, consider sponsoring.

Your support helps us smooth out the internet one library at a time—and lets us keep building tools that care about the details most folks overlook.

Packages Copy Chapter

• lenis
• lenis/react
• lenis/vue
• lenis/framer
• lenis/snap

Installation Copy Chapter

Using a package manager:

npm i lenis
# or
yarn add lenis
# or
pnpm add lenis

import Lenis from 'lenis'

Using scripts:

<script src="https://unpkg.com/[email protected]/dist/lenis.min.js"></script>

Setup Copy Chapter

Basic: Copy Section

// Initialize Lenis
const lenis = new Lenis({
  autoRaf: true,
});

// Listen for the scroll event and log the event data
lenis.on('scroll', (e) => {
  console.log(e);
});

Custom raf loop: Copy Section

// Initialize Lenis
const lenis = new Lenis();

// Use requestAnimationFrame to continuously update the scroll
function raf(time) {
  lenis.raf(time);
  requestAnimationFrame(raf);
}

requestAnimationFrame(raf);

Recommended CSS: Copy Section

Import stylesheet:

import 'lenis/dist/lenis.css'

Or link the CSS file:

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/lenis.css">

Or add it manually:

See lenis.css stylesheet

GSAP ScrollTrigger: Copy Section

// Initialize a new Lenis instance for smooth scrolling
const lenis = new Lenis();

// Synchronize Lenis scrolling with GSAP's ScrollTrigger plugin
lenis.on('scroll', ScrollTrigger.update);

// Add Lenis's requestAnimationFrame (raf) method to GSAP's ticker
// This ensures Lenis's smooth scroll animation updates on each GSAP tick
gsap.ticker.add((time) => {
  lenis.raf(time * 1000); // Convert time from seconds to milliseconds
});

// Disable lag smoothing in GSAP to prevent any delay in scroll animations
gsap.ticker.lagSmoothing(0);

No-code usage Copy Chapter

One line, no build step — just drop this into your HTML:

<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/lenis.css">
<script src="https://unpkg.com/[email protected]/dist/lenis.min.js"></script> 
<script>new Lenis({ autoRaf: true, autoToggle: true, anchors: true, allowNestedScroll: true, naiveDimensions: true, stopInertiaOnNavigate: true })</script>

That's it, your page now has smooth scrolling and should handle most of the usual issues such as:

• compatibility with other packages
• modals
• smooth anchors
• scroll reset on page change

Settings Copy Chapter

Properties Copy Chapter

Methods Copy Chapter

Events Copy Chapter

Considerations Copy Chapter

Nested scroll Copy Section

The simplest and most reliable way to handle nested scrollable elements is to use the allowNestedScroll option:

const lenis = new Lenis({
  allowNestedScroll: true,
})

This automatically detects nested scrollable elements and lets them scroll natively. However, this can create performance issues since Lenis needs to check the DOM tree on every scroll event. If you experience performance problems, use data-lenis-prevent instead.

Using HTML attributes

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

See example

Using Javascript

<div id="modal">scrollable content</div>

const lenis = new Lenis({
  prevent: (node) => node.id === 'modal',
})

See example

Anchor links Copy Section

By default, Lenis will prevent anchor links from working while scrolling. To enable them, you must set anchors: true.

new Lenis({
  anchors: true
})

You can also use scrollTo options:

new Lenis({
  anchors: {
    offset: 100,
    onComplete: ()=>{
      console.log('scrolled to anchor')
    }
  }
})

Reduced motion Copy Section

By default, Lenis honors the user's prefers-reduced-motion setting: when it is set to reduce, smoothing is disabled (lerp is forced to 1 so the scroll tracks the input device 1:1, ignoring duration/easing) and programmatic scrolls (scrollTo, anchor links) jump instantly to their target. Lenis keeps running so WebGL/DOM synchronization stays intact, and the preference is picked up live without a reload. You can check lenis.prefersReducedMotion to adapt your own animations.

You can opt out (not recommended) with:

const lenis = new Lenis({
  respectReducedMotion: false,
})

Limitations Copy Chapter

• no support for CSS scroll-snap, you must use (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)
• touch events may behave unexpectedly when syncTouch is enabled on iOS < 16
• nested scroll containers require proper configuration to work correctly

Troubleshooting Copy Chapter

• Make sure you use the latest version of Lenis
• Include the recommended CSS
• If using GSAP ScrollTrigger, ensure proper integration (see GSAP ScrollTrigger setup section)
• Test without Lenis to ensure your element/page is scrollable
• Be sure to use autoRaf: true or manually call lenis.raf(time) in your animation loop

Tutorials Copy Chapter

• Infinite Scrolling with Lenis by Matt Rothenberg
• Building Smooth Scroll in 2025 with Lenis by Edoardo Lunardi

Plugins Copy Chapter

• r3f-scroll-rig by 14islands
• locomotive-scroll by Locomotive

License Copy Chapter

MIT © darkroom.engineering

Overview (`packages/react/README.md`) Copy Section

lenis/react

Introduction Copy Chapter

lenis/react provides a <ReactLenis> component that creates a Lenis instance and provides it to its children via context. This allows you to use Lenis in your React app without worrying about passing the instance down through props. It also provides a useLenis hook that allows you to access the Lenis instance from any component in your app.

Installation Copy Chapter

npm i lenis

Recommended CSS Copy Chapter

Import the Lenis CSS to ensure proper behavior:

import 'lenis/dist/lenis.css'

Usage Copy Chapter

Basic Copy Section

import { ReactLenis, useLenis } from 'lenis/react'

function App() {
  const lenis = useLenis((lenis) => {
    // called every scroll
    console.log(lenis)
  })

  return (
    <>
      <ReactLenis root />
      { /* content */ }
    </>
  )
}

Props Copy Chapter

• options: Lenis options.
• root: When true, makes the Lenis instance globally accessible via useLenis from anywhere in your app (even outside the provider tree). Lenis will use the default <html> scroll container. When 'asChild', renders wrapper elements for custom scroll containers while still making the instance globally accessible. Default: false.

Hooks Copy Chapter

Once the Lenis context is set (components mounted inside <ReactLenis>) you can use these handy hooks:

useLenis is a hook that returns the Lenis instance

The hook takes three arguments:

• callback: The function to be called whenever a scroll event is emitted
• deps: Trigger callback on change
• priority: Manage callback execution order

Examples Copy Chapter

Custom requestAnimationFrame loop: Copy Section

import { ReactLenis } from 'lenis/react'
import { useEffect, useRef } from 'react'

function App() {
  const lenisRef = useRef()
  
  useEffect(() => {
    function update(time) {
      lenisRef.current?.lenis?.raf(time)
    }
  
    const rafId = requestAnimationFrame(update)
  
    return () => cancelAnimationFrame(rafId)
  }, [])
  
  return (
    <ReactLenis root options={{ autoRaf: false }} ref={lenisRef} />
  )
}

GSAP integration Copy Section

import gsap from 'gsap'
import { ReactLenis } from 'lenis/react'
import { useEffect, useRef } from 'react'

function App() {
  const lenisRef = useRef()
  
  useEffect(() => {
    function update(time) {
      lenisRef.current?.lenis?.raf(time * 1000)
    }
  
    gsap.ticker.add(update)
  
    return () => gsap.ticker.remove(update)
  }, [])
  
  return (
    <ReactLenis root options={{ autoRaf: false }} ref={lenisRef} />
  )
}

Framer Motion integration: Copy Section

import { ReactLenis } from 'lenis/react';
import type { LenisRef } from 'lenis/react';
import { cancelFrame, frame } from 'framer-motion';
import { useEffect, useRef } from 'react';

function App() {
  const lenisRef = useRef<LenisRef>(null)

  useEffect(() => {
    function update(data: { timestamp: number }) {
      const time = data.timestamp
      lenisRef.current?.lenis?.raf(time)
    }

    frame.update(update, true)

    return () => cancelFrame(update)
  }, [])


  return (
    <ReactLenis root options={{ autoRaf: false }} ref={lenisRef} />
  )
}

lenis/react in use Copy Chapter

• @darkroom.engineering/satus Our starter kit.

License Copy Chapter

MIT © darkroom.engineering

Overview (`packages/snap/README.md`) Copy Section

lenis/snap

Introduction Copy Chapter

lenis/snap provides a partial support for CSS scroll snap with Lenis, see Demo

Installation Copy Chapter

npm i lenis

Usage Copy Chapter

Basic Copy Section

import Lenis from 'lenis'
    import Snap from 'lenis/snap'

    const lenis = new Lenis()

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

    requestAnimationFrame(raf)

    const snap = new Snap(lenis)

    // add snaps points
    snap.add(500) // snap at 500px
    snap.add(1000) // snap at 1000px
    snap.add(1500) // snap at 1500px

    // or add an element to snap to
    snap.addElement(document.querySelector('.element'), {
      align: ['start', 'end'], // 'start', 'center', 'end'
    })

    snap.addElement(document.querySelector('.element1'), {
      align: 'center', // 'start', 'center', 'end'
    })

    // or add elements at once
    snap.addElements(document.querySelectorAll('.section'), {
      align: ['start', 'end'], // 'start', 'center', 'end'
    })

Slideshow Copy Section

const snap = new Snap(lenis, {
      type: 'lock',
      distanceThreshold: '100%',
      debounce: 0,
    })

Options Copy Chapter

• type: proximity (default), mandatory see scroll-snap-type or lock.
• distanceThreshold: string | number (default: '50%'). The distance threshold from the snap point to the scroll position. Ignored when type is mandatory. If a percentage, it is relative to the viewport size. If a number, it is absolute.
• debounce: number (default: 500). The debounce time for the snap.
• onSnapStart: function. Callback when snap starts.
• onSnapComplete: function. Callback when snap completes.
• lerp: number Lerp value for snapping. (default: lenis lerp).
• easing: function. Easing function for snapping. (default: lenis easing).
• duration: number. Duration for snapping. (default: lenis duration).

Methods Copy Chapter

• add(value: number): Add a snap point.
• addElement(element: HTMLElement, options: SnapElementOptions = {}): Add an element to snap to.
• addElements(elements: HTMLElement[], options: SnapElementOptions = {}): Add elements at once.
• next(): Go to the next snap point.
• previous(): Go to the previous snap point.
• goTo(index: number): Go to a specific snap point.
• start(): Start the snap.
• stop(): Stop the snap.
• resize(): Force recalculate the snap points.

Overview (`packages/vue/README.md`) Copy Section

lenis/vue

Introduction Copy Chapter

lenis/vue provides a <VueLenis> component that creates a Lenis instance and provides it to its children via context. This allows you to use Lenis in your Vue app without worrying about passing the instance down through props. It also provides a useLenis hook that allows you to access the Lenis instance from any component in your app. lenis/vue provides a vueLenisPlugin that you can use to register the component globally. This allows you to use the component in your templates without having to import it, by using the vue-lenis template tag.

Installation Copy Chapter

npm i lenis

Vue Copy Section

// main.js
import { createApp } from 'vue'
import LenisVue from 'lenis/vue'

const app = createApp({})

app.use(LenisVue)

Nuxt Copy Section

// nuxt.config.js
export default defineNuxtConfig({
  modules: ['lenis/nuxt'],
})

Recommended CSS Copy Chapter

Import the Lenis CSS to ensure proper behavior:

import 'lenis/dist/lenis.css'

Usage Copy Chapter

<script setup>
import { VueLenis, useLenis } from 'lenis/vue' // Also available as global imports, no need to import them manually
import { watch } from 'vue'

const lenisOptions = {
  // lenis options (optional)
}

const lenis = useLenis((lenis) => {
  // called every scroll
  console.log(lenis)
})

watch(
  lenis,
  (lenis) => {
    // lenis instance
    console.log(lenis)
  },
  { immediate: true }
)
</script>

<template>
  <VueLenis root :options="lenisOptions" />
  
</template>

Props Copy Chapter

• options: Lenis options.
• root: if true, Lenis will be instanciate using <html> scroll, then you can use the useLenis hook to access the Lenis instance from anywhere in your app. Default: false.

Hooks Copy Chapter

Once the Lenis context is set (components mounted inside <VueLenis> or <vue-lenis>) you can use these handy hooks:

useLenis is a hook that returns the Lenis instance

The hook takes two arguments:

• callback: The function to be called whenever a scroll event is emitted
• priority: Manage callback execution order

<script setup>
import { VueLenis, useLenis } from 'lenis/vue'
import { watch } from 'vue'

const scrollCallback = (lenis) => {
  // called on every scroll
  // useLenis provides the lenis instance as an argument
}

const lenis = useLenis(scrollCallback, 0) // where 0 is the default callback priority
</script>

<template>
  <VueLenis root />
  
</template>

Examples Copy Chapter

GSAP integration Copy Section

<script setup>
import { ref, watchEffect } from 'vue'
import { VueLenis, useLenis } from 'lenis/vue'
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

const lenisRef = ref()

watchEffect((onInvalidate) => {
   if (!lenisRef.value?.lenis) return

  //  if using GSAP ScrollTrigger, update ScrollTrigger on scroll
  lenisRef.value.lenis.on('scroll', ScrollTrigger.update)

  // add the Lenis requestAnimationFrame (raf) method to GSAP's ticker
  // this ensures Lenis's smooth scroll animation updates on each GSAP tick
  function update(time) {
    lenisRef.value.lenis.raf(time * 1000)
  }
  gsap.ticker.add(update)

  // disable lag smoothing in GSAP to prevent any delay in scroll animations
  gsap.ticker.lagSmoothing(0)

  // clean up GSAP's ticker from the previous execution of watchEffect, or when the effect is stopped
  onInvalidate(() => {
    gsap.ticker.remove(update)
  })
})

// if using GSAP ScrollTrigger, remember to register the plugin
onMounted(() => {
  gsap.registerPlugin(ScrollTrigger)
})
</script>

<template>
  <VueLenis root ref="lenisRef" :options="{ autoRaf: false }" />
  
</template>

Motion Integration Copy Section

<script setup>
import { VueLenis } from 'lenis/vue'
import { cancelFrame, frame } from 'motion-v'
import { onMounted, onUnmounted, ref } from 'vue'

const lenisRef = ref()

function update({ timestamp }) {
  lenisRef.value?.lenis?.raf(timestamp)
}

onMounted(() => {
  frame.update(update, true)
})

onUnmounted(() => {
  cancelFrame(update)
})
</script>

<template>
  <VueLenis ref="lenisRef" root :options="{ autoRaf: false }">
  
</template>

License Copy Chapter

MIT © darkroom.engineering

Overview (`playground/nuxt/README.md`) Copy Section

Nuxt Minimal Starter

Look at the Nuxt documentation to learn more.

Setup Copy Chapter

Make sure to install dependencies:

# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

# bun
bun install

Development Server Copy Chapter

Start the development server on http://localhost:3000:

# npm
npm run dev

# pnpm
pnpm dev

# yarn
yarn dev

# bun
bun run dev

Production Copy Chapter

Build the application for production:

# npm
npm run build

# pnpm
pnpm build

# yarn
yarn build

# bun
bun run build

Locally preview production build:

# npm
npm run preview

# pnpm
pnpm preview

# yarn
yarn preview

# bun
bun run preview

Check out the deployment documentation for more information.

--- METRICS ---

• Files Extracted: 5
• Estimated Token Budget: ~11272 tokens
• Canonical Reference: https://codewiki.google/github.com/darkroomengineering/lenis