Locomotive Scroll — Smooth Scrolling Library with Parallax Effects

Introduction

Locomotive Scroll is a JavaScript library by the Locomotive agency that provides buttery smooth virtual scrolling with built-in parallax effects. It intercepts native scroll behavior and applies inertia-based momentum, enabling cinematic scroll experiences common in award-winning portfolio and marketing sites.

What Locomotive Scroll Does

• Replaces native scrolling with a smooth, momentum-based virtual scroll
• Applies parallax speed multipliers to elements via data attributes
• Detects when elements enter and exit the viewport for triggering animations
• Supports both vertical and horizontal scroll directions
• Provides scroll progress values that can drive CSS custom properties or JS callbacks

Architecture Overview

Locomotive Scroll uses a transform-based scrolling approach. Instead of the browser's native scroll, it translates the scroll container using CSS transforms driven by requestAnimationFrame. A lerp (linear interpolation) function smooths the transition between the current and target scroll positions, creating the momentum effect. Intersection detection is handled internally to track which elements are in view. In v5, the library introduced a modular architecture with native scroll mode as an alternative to virtual scroll.

Self-Hosting & Configuration

• Install via npm and import the main class
• Wrap your page content in a data-scroll-container element
• Add data-scroll to elements you want to track or animate
• Set data-scroll-speed for parallax speed multipliers (positive or negative)
• Configure smooth scrolling intensity, direction, and gesture sensitivity via constructor options

Key Features

• Smooth virtual scrolling with configurable inertia and lerp values
• Declarative parallax via HTML data attributes with no JavaScript required per element
• In-view detection with CSS classes and JavaScript callbacks for scroll-triggered effects
• Horizontal scroll support for portfolio and gallery layouts
• Lightweight core with modular v5 architecture supporting tree shaking

Comparison with Similar Tools

• GSAP ScrollSmoother — premium GSAP plugin with similar smooth scroll and parallax; Locomotive Scroll is open source and MIT licensed
• Lenis — a newer smooth scroll library with a simpler API; Locomotive Scroll has a more mature ecosystem and built-in parallax via data attributes
• ScrollMagic — focuses on scroll-triggered scene animations without virtual scroll; Locomotive Scroll provides the smooth scroll layer that ScrollMagic does not
• CSS scroll-behavior: smooth — native browser smooth scrolling; Locomotive Scroll adds momentum physics, parallax, and programmatic control beyond what CSS offers

FAQ

Q: Does Locomotive Scroll affect SEO? A: The content is in the DOM and crawlable. However, virtual scroll can interfere with anchor links and browser find-in-page. Use native scroll mode in v5 for SEO-critical pages.

Q: Can I use Locomotive Scroll with React or Next.js? A: Yes. Initialize it inside a useEffect hook and destroy it on cleanup. Community hooks and examples are available for Next.js and Nuxt.

Q: What is the difference between v4 and v5? A: v5 introduced a modular architecture, native scroll mode, and better integration with modern frameworks. v4 remains widely used for its simpler API.

Q: Does it work on mobile devices? A: Yes, but virtual scroll can conflict with native mobile scrolling gestures. Many developers use native scroll mode on mobile and virtual scroll on desktop.

Sources

• https://github.com/locomotivemtl/locomotive-scroll
• https://scroll.locomotive.ca/