A common frontend gotcha: Lenis smooth scroll library and CSS scroll-snap are incompatible. Here’s why they fight and how to choose between them.

The Idea

Lenis smooth scroll library is INCOMPATIBLE with CSS scroll-snap. They fight for scroll control.

Context

Wedding invitation site had both Lenis (for smooth parallax scrolling) and CSS scroll-snap (for section-by-section navigation). Neither worked properly.

Raw Exchange

Librarian agent research: “CRITICAL: Lenis and CSS scroll-snap are INCOMPATIBLE - Lenis hijacks native scrolling” Solution: “Remove Lenis, use CSS scroll-snap + native smooth scroll for better mobile performance”

Investigation

Lenis works by:

1. Intercepting wheel/touch events
2. Applying its own scroll animation via requestAnimationFrame
3. Updating scroll position programmatically

CSS scroll-snap expects:

1. Native scroll behavior
2. Browser to handle snap points
3. No interference with scroll position

When combined:

• Lenis animates scroll → browser tries to snap → Lenis overrides → janky behavior
• Mobile especially broken (touch events fight)

Resolution

Removed Lenis entirely:

// Before (Layout.astro)
import Lenis from 'lenis';
const lenis = new Lenis({ ... });
lenis.on('scroll', ScrollTrigger.update);

// After
// Just GSAP ScrollTrigger, no Lenis
gsap.registerPlugin(ScrollTrigger);

Added native smooth scroll: