How To Add Locomotive Scroll To A Website

By James LePage
 on March 18, 2021
Last modified on January 6th, 2022

How To Add Locomotive Scroll To A Website

By James LePage
 on March 18, 2021
Last modified on January 6th, 2022

This article will show you how to add Locomotive Scroll to a website. For this example, we will be using WordPress and Oxygen Builder, but the concepts discussed here can easily be applied to any framework or CMS.

What is Locomotive Scroll? From the Github, it's "a simple scroll library used by developers at Locomotive. 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.". Once installed, this library makes your site incredibly unique. In our opinion, it's the best parallax library in the game, with a ton of options. You can also leverage the class toggles and event listeners to create incredibly immersive, interactive experiences.

Essentially, it's something that you should at least be experimenting with.

Step 1: Install JS and CSS Libraries

First thing to do is install the JS and CSS associated with Locomotive Scroll. For development, we copy the most recent version of the code, create a new Advanced Script, and add both to our website's header and footer (on WP it would be wp_head and wp_footer).

We can also embed our <script> and <link> components by using Statically, generating a CDN version from the raw Github, and placing the component in our header and footer by using AS.

To manage our code, embed CDN versions in the head of our site, and more, we use a WordPress plugin called Advanced Scripts. It makes it easy to debug when developing by offering a safe mode, on off toggles, and a ton of other features. You can read our review here:

Step 2: Create Website Structure For Locomotive Scroll

Now, it's time to structure our website in a way that enables Locomotive Scroll to apply the parallax and additional effects. To do that, we need to add an attribute to a <div> or <main> element that surrounds the content, including the header, body, and footer. On Oxygen builder, we use a catchall template to do this.

A div, which we change to <main> wraps all content in the site. This includes our Top Bar, Header, Inner Content, and Footer.

Wrap all elements of your website in a div.

That div, which is now a "<main>", then has the "data-scroll-container" attribute added to it.

Step 3: Initialize The Locomotive Scroll Library

Now the site is ready for the scripts, css, and new element with the attribute to all work together, and create a unique smooth scroll effect. All we need to do is initialize the library. You can do this globally (as we've done in the script above), only include this code on specific pages, or anything in between. If using Oxygen Builder, you can use a code block to do this, or add the JS to the JS section of any element. If using WordPress, you can use Advanced Scripts. With it, you can globally toggle this, or set conditions to only initialize LS on specific pages or ranges of pages.

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

You can see that there is a place to add additional options (after smooth: true).

All options listed on the Github.

Now, if you go to the frontend of your website, there should be a new scrollbar (like a mobile iOS one), and a smooth scrolling effect. If this doesn't show, check your browser console to troubleshoot.

Step 4 (Optional) - Improve Scrolling Performance

For each section on the page, add the "data-scroll-section". While optional, this really helps with scrolling performance (reduces choppiness).


You should now have a really unique smooth scrolling effect. From here, you can apply parallax, and do unique things like on letter scroll animations.

If you found this helpful, please share! Feel free to ask any questions down in the comments section below.

Subscribe & Share
If you liked this content, subscribe for our monthly roundup of WordPress news, website inspiration, exclusive deals and interesting articles.
Unsubscribe at any time. We do not spam and will never sell or share your email.
Notify of
Newest Most Voted
Inline Feedbacks
View all comments
Dirk Borchers
3 years ago

I'm already lost and haven't even started yet. Step 1: where are the css and js files in the github repository? Should I download the zip-file, or should I do something with the URL? And then what to do with it? So I try to upload the json file.But when I click on the link it doesn't start any download, but just opens the json code in the browser. What am I am supposed to do with that? See, I think that most tutorials assume that everyone knows their way around github and these basic things. But for me that first step is where it usually ends whenever I try to work with js libraries. That's a pity because the following steps all don't seem to be too difficult to get right.

Alejandro Aruca
Alejandro Aruca
3 years ago
Reply to  Dirk Borchers
Alejandro Aruca
Alejandro Aruca
3 years ago

The code works perfect, what I am having an error in the Oxygen editor
TypeError: can't access property "dispatchEvent", this.el is null on line # 1240 in

It's like trying to load it into the editor, do you know how to make it not come out?

Last edited 3 years ago by Alejandro Aruca
1 year ago

hi, how can i do it with elementor too?
where and how i should i add data-scroll-container ?


Article By
James LePage
James LePage is the founder of Isotropic, a WordPress education company and digital agency. He is also the founder of, a venture backed startup bringing AI to WordPress creators.
We're looking for new authors. Explore Isotropic Jobs.
linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram