Getting Started With Locomotive Scroll

Locomotive Scroll is a JavaScript library for adding advanced scrolling effects to a page. Built on top of ayamflow's virtual-scroll, it detects when elements enter the viewport and applies inline CSS transform values to produce smooth motion. This enables effects like parallax, class toggling, and event triggering tied to scroll position.

Instead of relying on the browser's native smooth scrolling, Locomotive virtualizes the scroll position and continually smooths it out. This is essentially a form of scrolljacking, and user research on its merits is mixed, so it's worth checking the homepage to get a feel for the behavior before committing to it.

Core Concepts

The library works primarily through HTML attributes. When an element carrying one of these attributes enters the viewport, the library triggers the appropriate JavaScript event listener and updates the element's transform inline style.

Two attributes form the foundation:

  • data-scroll: Marks an element to be detected when it enters the viewport.
  • data-scroll-container: Wraps all HTML content that should be monitored for scrolling.

When an effect is applied, you'll see the resulting inline styles directly in the markup, like this:

Notice how, as soon as an element with Locomotive’s data- attributes comes into the viewport, the CSS transform values are are updated.

Setup Options

Locomotive Scroll is available via CDN, so you can drop it in with a simple <script> tag:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/locomotive-scroll.css"> 
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/locomotive-scroll.min.js">

With the library loaded, simply instantiate it with the container element:

const scroller = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true
});

It's also on npm, which fits into a typical build setup:

npm install locomotive-scroll

Then import and initialize it in your JavaScript:

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll();

That covers the basic setup — it's largely plug-and-play from there.

More Attributes for Full Control

Beyond the two base attributes, Locomotive provides several others for more granular control. Here's a quick breakdown:

  • data-scroll-section: Defines a scrollable section. Splitting a page into sections can improve performance.
  • data-scroll-direction: Sets whether an element moves vertically or horizontally.
  • data-scroll-speed: Controls how fast an element moves. A negative value reverses the direction, but only vertically unless data-scroll-direction is also set on the same element.
  • data-scroll-sticky: Makes an element stick to the viewport as long as its target element remains visible.
  • data-scroll-target: Points to a specific element using an ID selector. When using data-scroll-sticky, you must also set a target, which is typically the container that holds the other elements.

Here's an example of the sticky behavior combined with its required target:

<div class="container" id="stick" data-scroll-section >
  <p data-scroll data-scroll-sticky>
    Look at me, I'm going to stick when you scroll pass me.
  </p>
</div>

Using Locomotive With Other Frameworks

The library isn't limited to vanilla JavaScript. It can be integrated into component-based frameworks as well, such as React, so you can apply the same scroll effects within your existing component structure.

With just these attributes and a bit of configuration, Locomotive Scroll makes it straightforward to add polished, custom scroll effects to nearly any web project.