Locomotive Scroll
Detection of elements in viewport & smooth scrolling with parallax effects.
Installation
β οΈ Scroll-hijacking is a controversial practice that can cause usability, accessibility, and performance issues. Please use responsibly.
npm install locomotive-scroll
Usage
Basic
With simple detection.
HTML
<h1 data-scroll>Hey</h1>
<p data-scroll>π</p>
CSS
Add the base styles to your CSS file.
JS
With a bundler
import LocomotiveScroll from 'locomotive-scroll';
const scroll = new LocomotiveScroll();
Or without
<script src="locomotive-scroll.min.js"></script>
<script>
(function () {
var scroll = new LocomotiveScroll();
})();
</script>
Get the JS file.
Smooth
With smooth scrolling and parallax.
<div data-scroll-container>
<div data-scroll-section>
<h1 data-scroll>Hey</h1>
<p data-scroll>π</p>
</div>
<div data-scroll-section>
<h2 data-scroll data-scroll-speed="1">What's up?</h2>
<p data-scroll data-scroll-speed="2">π¬</p>
</div>
</div>
import LocomotiveScroll from 'locomotive-scroll';
const scroll = new LocomotiveScroll({
el: document.querySelector('[data-scroll-container]'),
smooth: true
});
Note: scroll-sections are optional but recommended to improve performance, particularly in long pages.
Advanced
Make it do what you want.
With methods
<section id="js-target">Come here please.</section>
import LocomotiveScroll from 'locomotive-scroll';
const scroll = new LocomotiveScroll();
const target = document.querySelector('#js-target');
scroll.scrollTo(target);
With events
<!-- Using modularJS -->
<div data-scroll data-scroll-call="function, module">Trigger</div>
<!-- Using jQuery events -->
<div data-scroll data-scroll-call="EVENT_NAME">Trigger</div>
<!-- Or do it your own way π -->
<div data-scroll data-scroll-call="{y,o,l,o}">Trigger</div>
import LocomotiveScroll from 'locomotive-scroll';
const scroll = new LocomotiveScroll();
scroll.on('call', func => {
// Using modularJS
this.call(...func);
// Using jQuery events
$(document).trigger(func);
// Or do it your own way π
});
Instance options
Element attributes
Attribute | Values | Description |
---|---|---|
data-scroll |
Detect if in-view. | |
data-scroll-id |
string |
(Optional) Useful if you want to scope your element and get the progress of your element in the viewport for example. |
data-scroll-container |
Defines the scroll container. Required for basic styling. | |
data-scroll-section |
Defines a scrollable section. Splitting your page into sections may improve performance. | |
data-scroll-class |
string |
Element in-view class. |
data-scroll-offset |
string |
Element in-view trigger offset : bottom,top First value is bottom offset, second (optional) is top offset.Percent is relative to viewport height, otherwise it's absolute pixels. E.g. "10" , "100,50%" , "25%, 15%" |
data-scroll-repeat |
boolean |
Element in-view detection repeat. |
data-scroll-call |
string |
Element in-view trigger call event. |
data-scroll-position |
string |
top , bottom , left or right Window position of in-view trigger. |
data-scroll-speed |
number |
Element parallax speed. A negative value will reverse the direction. |
data-scroll-delay |
number |
Element's parallax lerp delay. |
data-scroll-direction |
string |
Element's parallax direction. vertical or horizontal |
data-scroll-sticky |
Sticky element. Starts and stops at data-scroll-target position. |
|
data-scroll-target |
string |
Target element's in-view position. |
Instance methods
Method | Description | Arguments |
---|---|---|
init() |
Reinitializes the scroll. | |
on(eventName, function) |
Listen instance events β¬. | |
update() |
Updates all element positions. | |
destroy() |
Destroys the scroll events. | |
start() |
Restarts the scroll events. | |
stop() |
Stops the scroll events. | |
scrollTo(target, options) |
Scroll to a target. | target : Defines where you want to scroll. Available values types are :
options (optional, object) : Settings object. Available values are:
|
Instance events
Event | Arguments | Description |
---|---|---|
scroll |
obj |
Returns scroll instance (position, limit, speed, direction and current in-view elements). |
call |
func |
Trigger if in-view. Returns your string or array if contains , . |
Progressive playing animations example (like gsap)
All data-scroll
elements have a progress value.
In the on scroll event you can get all current in-view elements.
HTML
<h1 data-scroll data-scroll-id="hey">Hey</h1>
JS
scroll.on('scroll', (args) => {
// Get all current elements : args.currentElements
if(typeof args.currentElements['hey'] === 'object') {
let progress = args.currentElements['hey'].progress;
console.log(progress);
// ouput log example: 0.34
// gsap example : myGsapAnimation.progress(progress);
}
});
Dependencies
Name | Description |
---|---|
Virtual Scroll | Custom scroll event with inertia/momentum. |
modularScroll | Elements in viewport detection. Forked from it, not a dependency. |
bezier-easing | Allows to define an easing to scrollTo movement |
Browser support
Works on most modern browsers. Chrome, Firefox, Safari, Edge...
To get IE 11 support, you need polyfills. You can use your own or include these before our script.
<script nomodule src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/7.6.0/polyfill.min.js" crossorigin="anonymous"></script>
<script nomodule src="https://polyfill.io/v3/polyfill.min.js?features=Object.assign%2CElement.prototype.append%2CNodeList.prototype.forEach%2CCustomEvent%2Csmoothscroll" crossorigin="anonymous"></script>
Who's using Locomotive Scroll?
- thierrychopain.com
- clmt.paris
- miragefestival.com/2020
- mazellier.design
- ccccontemple.com
- abhishekjha.me/muteza
- normal.studio
- mixlegno.com
- nfq.group
- works.studio
- beangels.eu
- izakaya-caen.fr
- white-elephant.fr
- henge07.com
- loirevalleylodges.com