Locomotive Scroll

Locomotive Scroll is a lightweight JavaScript library (9.4kB gzipped) designed for smooth scrolling animations and advanced scroll interactions. It is built on top of Lenis and focuses on performance and accessibility.

Key capabilities include:

• Viewport Detection: Uses the browser's native Intersection Observer API.
• Parallax Effects: Implement parallax using the data-scroll-speed attribute.
• Progress Tracking: Access real-time scroll progress (0-1) via CSS variables or JavaScript events.
• Custom Events: Trigger callbacks when elements enter or leave the viewport.
• Accessibility: Supports native scrollbars, keyboard navigation, and proper ARIA support.
• Performance: Elements only subscribe to Request Animation Frame (RAF) when they are both visible and animating.

After cloning the repository, use NVM to switch to the recommended Node version specified in .nvmrc and then install the project dependencies using npm.

# Switch to recommended Node version from .nvmrc
nvm use

# Install dependencies from package.json
npm install

If you are using a module bundler (like Webpack, Vite, or Rollup), import the LocomotiveScroll class and instantiate it.

import LocomotiveScroll from 'locomotive-scroll';

const locomotiveScroll = new LocomotiveScroll();

If you are using the horizontal scrolling feature, apply these CSS rules to ensure the layout behaves correctly when html[data-scroll-orientation='horizontal'] is active.

/* Only necessary with horizontal scrolling */
html[data-scroll-orientation='horizontal'] {
    body {
        width: fit-content;
    }
    [data-scroll-container] {
        display: flex;
    }
}

You can include Locomotive Scroll directly in your HTML by using a CDN link. After including the script, initialize it by creating a new instance of LocomotiveScroll.

<script src="https://cdn.jsdelivr.net/npm/locomotive-scroll/bundled/locomotive-scroll.min.js"></script>
<script>
    const locomotiveScroll = new LocomotiveScroll();
</script>

To ensure styles are applied correctly, import the library's CSS file into your stylesheet.

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

Ensure you have Node (at least 14.17) and NPM (at least 8.0) installed. Use NVM to switch to the recommended version specified in .nvmrc, then install dependencies using npm.

# Switch to recommended Node version from .nvmrc
nvm use

# Install dependencies from package.json
npm install

When third-party scripts inject popups or modals that require independent scrolling, they may conflict with the default scroll wrapper. While adding data-lenis-prevent to the DOM element is a standard solution, it fails if the element is injected dynamically.

To resolve this for dynamic elements, use the prevent option within lenisOptions. This option accepts a function that receives the DOM node; if the function returns true, scroll smoothing is prevented for that element.

import LocomotiveScroll from 'locomotive-scroll';

const locomotiveScroll = new LocomotiveScroll({
    lenisOptions: {
        prevent: (node) => node.getAttribute('id') === 'modalSelector',
    },
});

Locomotive Scroll requires base CSS to function correctly. You can import the CSS file into your stylesheet or link to the CDN version in your HTML.

/* Via CSS import */
@import 'locomotive-scroll/dist/locomotive-scroll.css';

<!-- Via HTML link -->
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/locomotive-scroll/bundled/locomotive-scroll.css"
/>

Install the library using npm to get started with smooth scrolling and animations.

npm install locomotive-scroll

Import the LocomotiveScroll class and instantiate it to enable smooth scrolling on your page.

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll();

You can deploy the website using different methods depending on your hosting configuration:

Using SSH: Set the USE_SSH environment variable to true.

Using GitHub Pages (Non-SSH): Provide your GitHub username via the GIT_USER environment variable. This will build the site and push it to the gh-pages branch.