Lenis — Smooth Scroll Library for Modern Websites

Introduction

Lenis is a smooth scroll library that intercepts native browser scrolling and applies inertia-based easing for a fluid, polished feel. It is designed for creative and portfolio websites where scroll-driven animations, parallax effects, and smooth page transitions are essential to the user experience.

What Lenis Does

• Overrides native scroll behavior with configurable inertia and easing curves
• Works on both vertical and horizontal scroll containers
• Integrates with GSAP ScrollTrigger and other scroll-driven animation libraries
• Provides scroll-to functionality with smooth animated transitions
• Supports touch devices, trackpads, and mouse wheels with consistent behavior

Architecture Overview

Lenis listens to wheel, touch, and keyboard scroll events and translates them into a virtual scroll position. On each animation frame, it interpolates between the current and target scroll positions using a configurable lerp factor, then applies the result via window.scrollTo or a container's scrollTop. This approach preserves native scroll features like accessibility and find-in-page while adding smooth interpolation.

Self-Hosting & Configuration

• Install from npm and import into any JavaScript or TypeScript project
• Create a Lenis instance and drive it with requestAnimationFrame or GSAP ticker
• Set duration, easing, and lerp to control smoothness and responsiveness
• Use orientation: 'horizontal' for horizontal scroll layouts
• Call lenis.scrollTo(target) for programmatic smooth scroll to anchors or positions

Key Features

• Sub-2 KB gzipped with no dependencies
• Preserves native accessibility features like keyboard navigation and anchors
• GSAP ScrollTrigger integration with a single line of setup
• Touch and trackpad inertia that feels natural on all devices
• Scroll lock and unlock API for modals and overlays

Comparison with Similar Tools

• Locomotive Scroll — Feature-rich with parallax built in; Lenis is lighter and more focused on scroll feel
• GSAP ScrollSmoother — Part of the GSAP paid tier; Lenis is fully open source
• Smooth Scrollbar — Custom scrollbar approach; Lenis uses native scroll position for better compatibility
• CSS scroll-behavior: smooth — Browser-native but limited to anchor links with no inertia control

FAQ

Q: Does Lenis affect page accessibility? A: Lenis preserves native scroll position and keyboard navigation. Screen readers and find-in-page continue to work normally.

Q: Can I use Lenis with React or Next.js? A: Yes. Initialize it in a useEffect hook or use the community React wrapper. It works with any framework.

Q: How do I integrate with GSAP ScrollTrigger? A: Connect Lenis to GSAP's ticker with gsap.ticker.add((time) => lenis.raf(time * 1000)) and set ScrollTrigger.defaults({ scroller: document.body }).

Q: Does it work on mobile? A: Yes. Lenis handles touch events and can be configured with different easing for touch devices.

Sources

• https://github.com/darkroomengineering/lenis
• https://lenis.darkroom.engineering