Smooth scrolling gives your site a polished, premium feel — and Lenis is a tiny, high-quality library that does it nicely. Below is a clear, practical walkthrough that explains the snippet you provided, how to install it, and how to tune it. If you want the full production-ready package (touch fallbacks, scroll-linked animations, ScrollTrigger/GSAP integration, performance tweaks, and accessibility polish), contact us and we’ll deliver the complete code and setup. What this code does (quick summary)
- Loads Lenis from a CDN.
- Adds a small CSS reset/override to make Lenis work reliably.
- Initializes Lenis with smoothing parameters and runs the animation frame loop so Lenis controls scroll behavior.
1) Add the Lenis script
Place this in the <head> (or before your closing <body> if you prefer scripts at the end). Using the CDN is quick to test:
<script src="https://unpkg.com/@studio-freight/lenis@1.0.42/dist/lenis.min.js"></script>Tip: For production consider hosting the file locally or pinning a local copy to avoid CDN flakiness.
2) Include the CSS tweaks
Lenis requires a couple of small CSS overrides to ensure the page height and scroll-behavior work correctly. Insert this in your main stylesheet or in a <style> block:
/* Ensure the page height is correctly set for Lenis */
html.lenis, html.lenis body {
height: auto;
}
/* Override default scroll behavior */
.lenis.lenis-smooth {
scroll-behavior: auto !important;
}
/* Prevent scrolling when necessary */
.lenis.lenis-stopped {
overflow: hidden;
}Why these matter:
- html.lenis is added by Lenis to the <html> element when active. Setting height:auto avoids hard resets that can break scrolling.
- scroll-behaviour is set to auto to prevent conflicts between CSS smooth scrolling and Lenis’ JS smoothing.
- .lenis-stopped can be used to temporarily freeze scrolling (e.g., when a modal is open).
3) Initialize Lenis (the JS)
Place this script after the Lenis script tag and after the DOM (bottom of body or inside a DOMContentLoaded callback). Your snippet:
<script>
// Initialize Lenis with smooth scrolling configuration
const lenis = new Lenis({
lerp: 0.1, // damping effect for smoothness
wheelMultiplier: 0.7, // adjust scroll speed
gestureOrientation: 'vertical', // vertical scroll only
normalizeWheel: false, // preserve native wheel delta behavior
smoothTouch: false // disable smoothing for touch (mobile) devices
});
// Animation frame loop to keep Lenis active
function raf(time) {
lenis.raf(time);
requestAnimationFrame(raf);
}
requestAnimationFrame(raf);
</script>- Parameter notes:
- lerp (0–1): lower values = slower catch-up (more damped, very smooth); higher values = snappier movement. 0.1 is smooth and gentle.
- wheelMultiplier: multiplies wheel delta. Set <1 for slower, >1 for faster scroll feeling.
- gestureOrientation: ‘vertical’ is standard for typical sites.
- normalizeWheel: when true, Lenis normalizes wheel events across devices; set false if you want to preserve native device differences.
- smoothTouch: enabling it smooths touch scrolling on mobile — disable if smooth touch causes performance issues or when you want native touch feel.
4) Where to place this in your project
- For small sites: put the CDN <script> in the head and the init script before <body>.
- For bundlers (Webpack/Vite): npm install @studio-freight/lenis and import Lenis from ‘@studio-freight/lenis’ — then use the same initialization code.
- Ensure any scroll-linked libraries (GSAP ScrollTrigger, ScrollMagic, your own wheel listeners) are configured to work with Lenis (see Troubleshooting).
5) Accessibility & UX considerations
- Focus management: When using keyboard navigation (tab) make sure Lenis preserves focus behavior. Test keyboard scrolling and focus visibility.
- Reduced motion: Respect prefers-reduced-motion. If the user prefers reduced motion, disable smoothing or reduce durations:
const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
const lenis = new Lenis({ smooth: !reduced, /* ... */ });- Scroll restoration: Test browser back/forward navigation — some single-page setups need custom handling so users get correct scroll positions.
- Performance: Test on low-powered devices. If you see jank, try increasing lerp slightly, disable smoothTouch, or lower visual complexity during scroll.
6) Integrating with animations (quick tips)
- If you use GSAP + ScrollTrigger, make ScrollTrigger use Lenis’ scroll position. The pattern is:
- Update ScrollTrigger on Lenis raf.
- Use scrollerProxy for the scroll container.
- (We can provide the exact GSAP+Lenis glue code as part of the full package.)
7) Common issues & fixes
- Page “stuck” after enabling Lenis: ensure html / body are not set to height: 100% forcing fixed height; those CSS tweaks above usually fix it.
- Jumping to anchors: if anchor links don’t land correctly, implement Lenis’ scrollTo() method to animate and offset positions (handy with fixed headers).
- Conflict with scroll-behavior: smooth in CSS: disable the CSS scroll-behavior (Lenis sets it to auto) or remove the CSS rule.
- Touch devices feel sluggish: try smoothTouch: true or false depending on the desired behavior; test across multiple devices.
8) Example: scrolling to an element with Lenis
Use Lenis’ scrollTo() to jump smoothly to an anchor (handy for header nav):
<button id="to-contact">Contact</button>
<script>
document.getElementById('to-contact').addEventListener('click', () => {
// scroll to an element or y-coordinate
lenis.scrollTo(document.querySelector('#contact-section'));
});
</script>9) Final checklist before shipping
- Test on desktop, tablet, and multiple phones.
- Test keyboard navigation and focus states.
- Add prefers-reduced-motion support.
- Confirm interactions (modals, dropdowns) don’t break when scrolling is stopped.
- Minify and bundle Lenis for production (or self-host the minified file).
Want the full, production-ready implementation?
If you want the complete, production-ready package (local installation, GSAP + ScrollTrigger integration, anchor handling, prefers-reduced-motion, accessibility checks, performance optimizations and a polished example page), contact us and we’ll deliver the full code + setup guide tailored to your project.
👉 Contact Website Cradle to get the full code and a custom integration that matches your site and brand.
