Skip to content

Lenis Grid Notes

Lightweight smooth-scroll engine that keeps native browser scrolling, sticky positioning and intersection observers intact, and pairs cleanly with GSAP ScrollTrigger.

Grid NotesVersion 1.3.27MotionChecked 2026-11-11
Setup & agent config

Install and prerequisites

What your agent should install or configure before writing code with this pack.
Terminal
npm install lenis
Packages:lenis

Import lenis/dist/lenis.css once in your root stylesheet or layout so stopped, smooth and nested-scroll containers get the required styles.

Framework setup

Production-ready wiring for React 19, Next.js App Router and Tailwind CSS v4.

React and Next.js App Router with GSAP ticker

Drive Lenis from gsap.ticker with autoRaf: false so ScrollTrigger and smooth scrolling share one requestAnimationFrame loop.

components/smooth-scroll.tsx
"use client";

import { useEffect, useRef, type ReactNode } from "react";
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { ReactLenis, type LenisRef } from "lenis/react";
import "lenis/dist/lenis.css";

gsap.registerPlugin(ScrollTrigger);

export function SmoothScroll({ children }: { children: ReactNode }) {
  const lenisRef = useRef<LenisRef>(null);

  useEffect(() => {
    const update = (time: number) => {
      lenisRef.current?.lenis?.raf(time * 1000);
    };
    gsap.ticker.add(update);
    gsap.ticker.lagSmoothing(0);
    return () => gsap.ticker.remove(update);
  }, []);

  return (
    <ReactLenis
      ref={lenisRef}
      root
      options={{ autoRaf: false, allowNestedScroll: true, anchors: true, stopInertiaOnNavigate: true }}
    >
      {children}
    </ReactLenis>
  );
}

Scrollable inner panels and Firefox textareas

Mark custom overflow containers with data-lenis-prevent, and set textarea { overflow: auto } in CSS so Firefox nested scrolling works.

app/globals.css
/* Firefox computes textarea overflow as "visible", which makes allowNestedScroll scroll the page instead. */
textarea {
  overflow: auto;
}

/* Keep sticky header clearance on html rather than per-element scroll-mt-* classes. */
html {
  scroll-padding-top: 5rem;
}

Gotchas for agents

Real-world traps — version mismatches, licence boundaries, main-thread stalls and CSS layer rules — that trip AI agents up.
  1. One ticker only

    When pairing Lenis with GSAP ScrollTrigger, pass autoRaf: false to Lenis and multiply GSAP's seconds timestamp by 1000 inside gsap.ticker.add((time) => lenis.raf(time * 1000)). Leaving autoRaf: true runs two competing RAF loops and causes jitter.

  2. Firefox textareas need explicit overflow

    Firefox reports getComputedStyle(textarea).overflow as visible (Chromium reports auto). Lenis's allowNestedScroll checks that computed value, so wheeling inside a <textarea> scrolls the page in Firefox unless your CSS sets textarea { overflow: auto }.

  3. Native scroll calls are ignored mid-glide

    While Lenis is easing (isScrolling is 'smooth'), programmatic window.scrollTo() calls are overwritten on the next frame. Use lenis.scrollTo(target, { immediate: true }) or enable stopInertiaOnNavigate: true for route changes.

  4. Mount per route group, not inside heavy hydration

    Keep <ReactLenis root> out of routes that must not load scroll libraries, and pass anchors: true so hash links (#content skip links included) scroll to their target while preserving focus.

Accessibility and reduced motion

How to keep animations and interactive components accessible across keyboard, screen readers and prefers-reduced-motion.

Reduced motion

Lenis 1.3.26+ honours prefers-reduced-motion: reduce by default (respectReducedMotion: true), turning off scroll smoothing and making scrollTo jump immediately.

Keyboard and screen readers

Lenis's anchor click handler calls scrollTo without cancelling the native hash navigation, so <a href="#content"> skip links still move the sequential focus starting point.

components/skip-link.tsx
export function SkipLink() {
  return (
    <a
      href="#content"
      className="sr-only focus:not-sr-only focus:fixed focus:top-3 focus:left-3 focus:z-50 focus:bg-background focus:px-4 focus:py-2"
    >
      Skip to content
    </a>
  );
}