locomotive-scroll

Locomotive Scroll

Comprehensive guide for implementing smooth scrolling, parallax effects, and scroll-driven animations using Locomotive Scroll.

Overview

Locomotive Scroll is a JavaScript library that provides:

• Smooth scrolling: Hardware-accelerated smooth scroll with customizable easing
• Parallax effects: Element-level speed control for depth
• Viewport detection: Track when elements enter/exit viewport
• Scroll events: Monitor scroll progress for animation synchronization
• Sticky elements: Pin elements within defined boundaries
• Horizontal scrolling: Support for horizontal scroll layouts

When to use Locomotive Scroll:

• Building immersive landing pages with parallax
• Creating smooth, Apple-style scroll experiences
• Implementing scroll-triggered animations
• Developing narrative/storytelling websites
• Adding depth and motion to long-form content

Trade-offs:

• Scroll-hijacking can impact accessibility (provide disable option)
• Performance overhead on low-end devices (detect and disable)
• Mobile touch scrolling feels different (test extensively)
• Fixed positioning requires workarounds

Installation

npm install locomotive-scroll

// ES6
import LocomotiveScroll from 'locomotive-scroll';
import 'locomotive-scroll/dist/locomotive-scroll.css';

// Or via CDN
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/locomotive-scroll/dist/locomotive-scroll.min.css">
<script src="https://cdn.jsdelivr.net/npm/locomotive-scroll/dist/locomotive-scroll.min.js"></script>

Core Concepts

1. HTML Structure

Every Locomotive Scroll implementation requires specific data attributes:

<!-- Scroll container (required) -->
<div data-scroll-container>

  <!-- Scroll sections (optional, improves performance) -->
  <div data-scroll-section>

    <!-- Tracked elements -->
    <h1 data-scroll>Basic detection</h1>

    <!-- Parallax element -->
    <div data-scroll data-scroll-speed="2">
      Moves faster than scroll
    </div>

    <!-- Sticky element -->
    <div data-scroll data-scroll-sticky>
      Sticks within section
    </div>

    <!-- Element with ID for tracking -->
    <div data-scroll data-scroll-id="hero">
      Accessible via JavaScript
    </div>

    <!-- Call event trigger -->
    <div data-scroll data-scroll-call="fadeIn">
      Triggers custom event
    </div>

  </div>
</div>