How to Use the Locomotive Scroll for all Kinds of Scrolling Effects

I was recently looking for a way to perform scrolling effects on a project and I stumbled on the Locomotive Scroll library. It lets you perform a variety of scrolling effects, like parallax and triggering/controlling animations at scroll points.

You might also call it a “smooth scrolling” library, but it doesn’t leverage native smooth scrolling — it does just the opposite by virtualizing scrolling and ensuring it’s always smooth. You could probably consider this “scrolljacking” so if you hate that generally, you might hate this, but UX research seems rather mixed on whether it’s actually bad or not. The homepage will give you a good sense of how it works and feels.

Let’s look at the basics of using Locomotive-Scroll JavaScript and how to leverage it to for delightful user experiences.

What is Locomotive Scroll?

Here’s what they say:

Locomotive scroll is a simple scroll library, built as a layer on top of ayamflow’s virtual-scroll, it provides smooth scrolling with support for parallax effects, toggling classes, and triggering event listeners when elements are in the viewport.

In other words, it detects when elements are in the viewport and then alters CSS transform property values on those elements to create scrolling effects.

Oftentimes scrolling effects are called parallax meaning some elements are made to look like they are deep in the background, making them appear to move slower than other elements that are closer to the foreground while scrolling is taking place. Imagine looking out the window from a moving car. The trees far away seems to slowly drift by where the fence right along the road zips quickly by. Sort of like the effect here in this pen from Sarah Drasner:

Here’s how it works

Locomotive Scroll works primarily through specific attributes in the HTML. Elements with these attributes trigger event listeners in JavaScript when they are in the viewport, then apply CSS transform values as inline styles.

There are two key attributes to always call upon Locomotive:

• data-scroll: detects whether or not an element is in the viewport
• data-scroll-container: wraps all the HTML content you want to watch for scrolling

Here’s what we’re talking about when we say that the transform property values are updated in the HTML as inline styles.

Let’s set this up

We can use the library right as a <script> tag if we’d like. It’s on CDNs, so like:

<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">

Now we look for the container and kick off the library:

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

The library is on npm as well, so we can use it that way in our build instead with the typical npm install locomotive-scroll, then:

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll();

That means we could use them off Skypack too, like:

That’s really all there is to the setup! It’s pretty plug-and-play like that.

Here are some examples

You can probably think of some pretty nice use cases for something like this, but let’s go over a few examples where you might use Locomotive Scroll.

Let’s start with this one:

That HTML has all kinds of data- attributes going on in there. We’ve already looked at data-scroll and data-scroll-container. Here’s what the rest are and what they do:

• data-scroll-section : Defines a scrollable section. For better performance, it’s a good idea to split pages into sections.
• data-scroll-direction: Defines the vertical or horizontal direction that an element moves.
• data-scroll-speed: Specifies the speed an element moves. A negative value reverses the direction, but only vertically, unless data-scroll-direction is applied on the same element.
• data-scroll-sticky: Specifies an element that sticks to the viewport as long as the target element is still in view.
• data-scroll-target: Targets a particular element. It takes in an ID selector, which is unique compared to the other attributes.

So, let’s say we are using the data-scroll-sticky attribute. We always have to set a data-scroll-target attribute as well, because the target element is usually the container holding the other elements.

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

Now that we’ve picked one apart, here are a couple of others:

You can also use LocoMotive-Scroll in other frameworks, too. Here’s an example in React:

Scroll aboard!

I can not emphasize the power of Locomotive Scroll enough. I needed to add scroll effects to a side project I was working on, and this was super quick and easy to use. I hope you’re able to use it on a project and experience how great it is for scrolling effects.