Locomotive Scroll v5: A Lenis-Based Wrapper for Viewport Detection and Parallax

What Locomotive Scroll Is For, and Who It Is Aimed At

Locomotive Scroll solves a narrow problem: you have a page of DOM elements, and you want to know which of them are in the viewport, then move some of them at a different rate than the page scrolls. The README describes it as a "lightweight & modern scroll library for detection, animation, and smooth scrolling," and the repository topics list the same three concerns: in-view, parallax, smooth-scrolling.

The intended user is a front-end developer building a site where motion is part of the design: agency landing pages, product sites, portfolios. You do not write a scroll listener or compute intersection ratios by hand. You add attributes to markup and the library handles observation and transforms.

The library is not a general animation framework. It does not give you timelines, keyframes or scroll-position callbacks that you compose into arbitrary sequences. Its vocabulary is small on purpose, and that is the main thing to understand before adopting it.

How the Lenis Foundation and the Dual Observers Work

Version 5 is built on Lenis, the smooth-scroll library from darkroomengineering. That is a structural change, not a cosmetic one. In earlier versions Locomotive Scroll implemented its own virtual scroll and transform-based movement. In v5, the README states it is "Built on Lenis" using the "latest stable release with improved performance." If you already use Lenis, you are running the same scrolling engine either way, and Locomotive Scroll adds a layer for detection and parallax on top.

Detection uses what the README calls "Dual Intersection Observers," described as "optimized detection for triggers vs. animations." The idea is that the library separates the question "is this element entering or leaving the viewport" from the question "should this element's transform be updated right now." Two observers with different thresholds serve those two jobs instead of one observer doing both.

The data flow is attribute-driven. Elements carrying data-scroll are registered. An element with data-scroll-speed gets a transform whose rate is derived from that value. The README's own example is a div with data-scroll and data-scroll-speed="0.5", annotated "I move at half speed." Everything else (the scrolling itself, the RAF loop) comes from Lenis.

The README also states that parallax is "auto-disabled on mobile" through what it calls "Smart Touch Detection." That is a deliberate default, and it means a parallax effect you tune on desktop will simply not appear on a phone unless you override it. Whether that is convenient or surprising depends on your design.

Installing Locomotive Scroll and Getting a First Parallax Element Moving

The README gives a four-step quick start. Install the package from npm:

npm install locomotive-scroll

Import the class and instantiate it. With no arguments, the README's example is a single line, which means the library will look for data-scroll attributes in the document on its own:

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll();

The stylesheet ships inside the package and is imported from the dist path. The README uses a CSS import:

@import 'locomotive-scroll/dist/locomotive-scroll.css';

Finally, mark up the element you want to move. The data-scroll attribute opts the element in to detection; data-scroll-speed sets the rate. A value of 0.5 means half speed, per the README's inline comment:

<div data-scroll data-scroll-speed="0.5">I move at half speed</div>

After this, scrolling the page should move that div at half the rate of the surrounding content. If nothing moves, the two things to check first are whether the CSS import resolved in your bundler and whether the element actually carries both attributes. The README does not document a manual refresh call for v5, so treat dynamically inserted elements as an open question to test in your own build.

Where Locomotive Scroll v5 Stops Being the Right Tool

The clearest limitation is the one the project states about itself: it is built on Lenis. If your requirement is smooth scrolling and nothing else, Locomotive Scroll is a wrapper around a library you could use directly, with an extra dependency and an attribute layer in between. The related searches show this confusion is common; people ask whether to pick Locomotive Scroll or Lenis, and the honest answer from the README alone is that v5 no longer competes with Lenis, it contains it.

The second limitation is the animation model. Locomotive Scroll does not provide a timeline. If you need an animation to start at a precise scroll offset, run for a defined duration, and hand off to a second animation, you are outside what the README describes. The library's own vocabulary is detection plus speed values. Anything more sequenced has to come from somewhere else.

The third is touch. Parallax being auto-disabled on mobile is a sensible default for performance and for the reading experience, but it means your motion design has a desktop-only branch you did not write and cannot see in the README's quick start. Verify it on a real device.

Finally, the release history is uneven. v5.0.1 landed on 2026-01-15, but the two releases before it were betas from 2024 and 2023. Anyone migrating from an older major version should read the changelog rather than assume a smooth path, because the Lenis rewrite is a real architectural change.

Locomotive Scroll vs GSAP ScrollTrigger: Different Jobs

The most frequent comparison in the search data is Locomotive Scroll against GSAP, and it is worth being precise about the difference rather than treating them as interchangeable.

GSAP ScrollTrigger is a timeline engine that reads scroll position. You define animations with start and end points, easing, pinning and callbacks, and ScrollTrigger drives them as the page scrolls. The unit of work is an animation you author.

Locomotive Scroll's unit of work is an element plus a speed. You declare that an element is detected and that it moves at a rate. There is no timeline, no pinning API in the README, and no easing curve to configure. The two libraries can coexist, and people do use them together, but that combination means two systems observing scroll and two sources of truth for position. If your site needs choreographed sequences, ScrollTrigger is the closer fit and Locomotive Scroll is redundant. If your site needs elements drifting at different rates as you scroll, Locomotive Scroll expresses that in markup with no JavaScript per element, which is a genuinely smaller amount of code.

Licence, Maintenance and What Upgrading Costs

Locomotive Scroll is MIT licensed, and the monorepo's root package.json repeats that with a "license": "MIT" field. In practice that means you can use it commercially, modify it and ship it inside a product, provided the copyright notice and permission notice are preserved. This is a description of the licence text, not legal advice; read the LICENSE file in the repository if the terms matter to your organisation.

The repository is not archived, and the last push was on 2026-06-30. That is recent enough that the project is not abandoned, though the gap between the 2024 beta and the 2026 v5.0.1 release shows the cadence is not steady.

Upgrade cost is concentrated in one place. Moving from a pre-v5 version to v5 means moving from the library's own scroll implementation to Lenis. The public surface described in the README is small (a constructor, a CSS file, two data attributes), so if your integration is shallow the migration is mostly about re-testing motion on real devices. If you had built workarounds around the old scroll loop, those workarounds are the cost.

The monorepo structure matters for contributors rather than users. The root package.json is private and declares npm workspaces for packages/lib, packages/demo, packages/landing and packages/docs, with turbo orchestrating builds. The published artifact comes from packages/lib. If you plan to patch the library, that is where you work, and you build with the workspace scripts rather than at the root.

Editorial conclusion

Adopt Locomotive Scroll v5 if you are building a marketing or portfolio site where data-scroll attributes and speed values are enough to express the motion you want, and if you accept that the smooth-scroll loop is Lenis underneath. Do not adopt it if you need scroll-driven timelines tied to a broader animation system, or if you need the library to own the scroll loop itself; that is what Lenis alone is for. Before committing, verify two things in your own build: that the CSS import resolves from locomotive-scroll/dist/locomotive-scroll.css in your bundler, and that parallax behaves the way you expect on touch devices, since the README states parallax is auto-disabled on mobile.

Frequently asked questions

Official sources

1. License: MIT
2. locomotivemtl/locomotive-scroll on GitHub
3. Project website
4. README
5. Releases