locomotive-scroll
Comprehensive skill for Locomotive Scroll smooth scrolling library with parallax effects, viewport detection, and scroll-driven animations. Use this skill when implementing smooth scrolling experiences, creating parallax effects, building scroll-triggered animations, or developing immersive scrollin
By freshtechbro · 2,041 installs
npx skills add freshtechbro/claudedesignskills --skill locomotive-scroll
Source repository · Upstream listing
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
Core Concepts
1. HTML Structure
Every Locomotive Scroll implementation requires specific data attributes:
2. Initialization
3. Data Attributes
Attribute Purpose Example
data scroll Enable detection data scroll
data scroll speed Parallax speed data scroll speed="2"
data scroll direction Parallax axis data scroll direction="horizontal"
data scroll sticky Sticky positioning data scroll sticky
data scroll target Sticky boundary data scroll target=" section"
data scroll offset Trigger offset data scroll offset="20%"
data scroll repeat Repeat detection data scroll repeat
data scroll call Event trigger data scroll call="myFunction"
data scroll id Unique identifier data scroll id="hero"
data scroll class Custom class data scroll class="is visible"
Common Patterns
1. Basic Smooth Scrolling
2. Parallax Effects
3. Viewport Detection and Callbacks
4. Sticky Elements
5. Programmatic Scrolling
6. Horizontal Scrolling
7. Mobile Responsiveness
Integration with GSAP ScrollTrigger
Locomotive Scroll and GSAP ScrollTrigger work together for advanced animations:
Instance Methods
Performance Optimization
1. Use data scroll section to segment long pages:
2. Limit parallax elements Too many can impact performance
3. Disable on mobile if performance is poor:
4. Update on resize :
5. Destroy when not needed :
Common Pitfalls
1. Fixed Positioning Issues
Problem : position: fixed elements break with smooth scroll
Solution : Use data scroll sticky instead or add fixed elements outside container:
2. Images Not Lazy Loading
Problem : All images load at once
Solution : Integrate with lazy loading:
3. Scroll Position Not Updating
Problem : Dynamic content doesn't update scroll positions
Solution : Call update() after DOM changes:
4. Accessibility Concerns
Problem : Screen readers and keyboard navigation broken
Solution : Provide disable option:
5. Memory Leaks
Problem : Scroll instance not cleaned up on route changes (SPAs)
Solution : Always destroy on unmount:
6. Z Index Fighting
Problem : Parallax elements overlap incorrectly
Solution : Set explicit z index on parallax layers:
Related Skills
gsap scrolltrigger : Advanced scroll driven animations (use together)
barba js : Page transitions with Locomotive Scroll integration
scroll reveal libraries : Simpler alternative for basic fade in effects
react three fiber : Scroll driven 3D scenes (sync with Locomotive events)
motion framer : Alternative scroll animations in React
Resources
Scripts : generate config.py Configuration generator, integration helper.py GSAP integration code
References : api reference.md Complete API, gsap integration.md GSAP ScrollTrigger patterns
Assets : starter locomotive/ Complete starter template with examples