Guide · Open source

How to use Lenis: install, set up smooth scroll and sync animations

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Lenis is a lightweight, dependency-free JavaScript library that adds smooth, eased scrolling to a website. It is aimed at web developers who want polished scroll effects such as WebGL scroll syncing and parallax. This guide shows how to install it, initialise it, connect it to animation code, and decide whether it fits your project.

Lenisdarkroomengineering/lenis · ★ 17k · MIT Install options & downloads

Quick start

1Install the package. Run npm i lenis, yarn add lenis or pnpm add lenis in your project folder.
2Import Lenis. Add import Lenis from 'lenis' to your JavaScript file, or load the unpkg script tag if you have no build step.
3Add the stylesheet. Import lenis/dist/lenis.css or link the CSS file as described in the README.
4Create an instance. Run new Lenis with autoRaf set to true for the simplest setup.
5Listen to scroll events. Attach lenis.on('scroll', ...) to read scroll data or to trigger other code.
6Connect your animation library. If you use GSAP ScrollTrigger, forward Lenis scroll events to ScrollTrigger.update and drive lenis.raf from the GSAP ticker.

Install Lenis with npm, yarn or pnpm

Lenis is installed as a package. The README lists three equivalent package-manager commands. After installing, import it into your JavaScript file.

npm: install with the npm command below
yarn: yarn add lenis
pnpm: pnpm add lenis

npm i lenis
import Lenis from 'lenis'

Load Lenis without a build step

If you are not using a package manager, the README shows a script tag that loads the minified build from unpkg. The stylesheet is loaded separately with a link tag.

<script src="https://unpkg.com/lenis@1.3.27/dist/lenis.min.js"></script>

Create a basic Lenis instance

The basic setup creates a Lenis instance with autoRaf turned on, so Lenis runs its own requestAnimationFrame loop. You can then listen for the scroll event to read scroll data.

If you prefer to control the timing yourself, create the instance without autoRaf and call lenis.raf(time) inside your own requestAnimationFrame loop.

autoRaf: true runs the animation loop for you
Use lenis.on('scroll', ...) to react to scroll events
Custom loop: call lenis.raf(time) on every frame

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

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

Add the recommended CSS

The README recommends the Lenis stylesheet. You can import it in a bundled project, link the CSS file from unpkg, or copy the file from the repository manually.

Import: import 'lenis/dist/lenis.css'
Link: the unpkg stylesheet URL for version 1.3.27
Manual: copy packages/core/lenis.css from the repository

import 'lenis/dist/lenis.css'

Sync Lenis with GSAP ScrollTrigger

To keep GSAP ScrollTrigger animations aligned with the smooth scroll position, the README connects Lenis's scroll event to ScrollTrigger.update and drives Lenis from the GSAP ticker. It also disables GSAP lag smoothing so scroll animations do not lag behind.

Call ScrollTrigger.update on each Lenis scroll event
Pass GSAP ticker time to lenis.raf, converting seconds to milliseconds
Set gsap.ticker.lagSmoothing(0)

const lenis = new Lenis();

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

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

gsap.ticker.lagSmoothing(0);

Use the no-code option and its settings

The README provides a no-code option that still needs you to edit HTML: you add the stylesheet and script, then create an instance with several options turned on. The README says this covers compatibility with other packages, modals, smooth anchors and scroll reset on page change.

The Settings table documents the options. For example, allowNestedScroll lets nested scrollable elements scroll natively, but the README warns it can cost performance because it checks the DOM tree on every scroll event. The prevent option is the alternative it suggests. anchors enables smooth scrolling to anchor links, and autoResize defaults to true using ResizeObserver.

allowNestedScroll: default false; can affect performance
anchors: default false; accepts true or ScrollToOptions
autoRaf: default false
autoResize: default true; call .resize() manually if set to false

new Lenis({ autoRaf: true, autoToggle: true, anchors: true, allowNestedScroll: true, naiveDimensions: true, stopInertiaOnNavigate: true })

What people use it for

Adding smooth scrolling to a marketing or portfolio site
Syncing GSAP ScrollTrigger animations to the scroll position
Driving WebGL scroll scenes from the scroll position
Enabling smooth anchor links and scrolling inside nested containers

Frequently asked questions

How do I install Lenis?

Run npm i lenis, yarn add lenis or pnpm add lenis in your project. Then import it with import Lenis from 'lenis'. The README also shows a script tag option for projects without a build step.

Is Lenis free to use?

Lenis is released under the MIT licence, as stated in the project's licence field. Check the repository's LICENSE file for the full terms before using it in a commercial project.

Does Lenis need any prerequisites?

The README lists no prerequisites. Lenis depends on JavaScript to run, so a page that cannot load JavaScript will not get the smooth scroll behaviour.

Does Lenis work with React, Vue or Framer?

Yes. The README lists first-class packages for React, Vue and Framer, plus a snap plugin for scroll snapping. Each has its own README in the repository.

What are the alternatives to Lenis?

The project lists Locomotive Scroll, Bigscreen Scroll and SmoothScroll.js as comparable projects. Simple static pages may not need any of them, since native scrolling may already be enough.

Why are my anchor links or sticky elements not working?

Lenis wraps the browser's native scroll, so position: sticky and anchor links should keep working. For anchor links, the anchors option must be enabled. For nested scroll areas, the README suggests allowNestedScroll or the prevent option; check the Troubleshooting section of the README for more.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Lenis suits developers who want polished smooth scrolling on a marketing or portfolio site, or who need to sync GSAP, WebGL or parallax effects to scroll. It is not a good fit for simple static pages where native scrolling is enough, for pages that cannot run JavaScript, or for non-developers who want a no-code tool, since even the no-code option requires editing HTML.

Install options & downloads