Home

Awesome

🚀 Locomotive Scroll v5 Beta Release

Try out the beta version of Locomotive Scroll v5!

🔗 Click here to try Locomotive Scroll v5 Beta

Your feedback is valuable during this beta testing phase. If you encounter any issues or have suggestions, please open an issue.

Happy scrolling! 😄

<p align="center"> <a href="https://github.com/locomotivemtl/locomotive-scroll"> <img src="https://user-images.githubusercontent.com/4596862/58807621-67aeec00-85e6-11e9-8e3a-3fe4123ee76c.png" height="140"> </a> </p> <h1 align="center">Locomotive Scroll</h1> <p align="center">Detection of elements in viewport & smooth scrolling with parallax effects.</p>

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.

locomotive-scroll.css

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

OptionTypeDefaultDescription
elobjectdocumentScroll container element.
namestring'scroll'Data attribute prefix (data-scroll-xxxx).
offsetarray(2)[0,0]Global in-view trigger offset : [bottom,top]<br>Use a string with % to use a percentage of the viewport height.<br>Use a numeric value for absolute pixels unit.<br>E.g. ["30%",0], [100,0], ["30%", 100]
repeatbooleanfalseRepeat in-view detection.
smoothbooleanfalseSmooth scrolling.
initPositionobject{ x: 0, y: 0 }Smooth only<br>An object defining the initial scroll coordinates on a smooth instance. For example: { x: 0, y: 1000 }
directionstringverticalSmooth only<br>Scroll direction: vertical or horizontal
lerpnumber0.1Smooth only<br>Linear interpolation (lerp) intensity. Float between 0 and 1.<br>This defines the "smoothness" intensity. The closer to 0, the smoother.
getDirectionbooleanfalseAdd direction to scroll event.
getSpeedbooleanfalseAdd speed to scroll event.
classstringis-inviewElement in-view class.
initClassstringhas-scroll-initInitialize class.
scrollingClassstringhas-scroll-scrollingIs scrolling class.
draggingClassstringhas-scroll-draggingIs dragging class.
smoothClassstringhas-scroll-smoothHas smooth scrolling class.
scrollbarContainerobjectfalseSmooth only<br>Specifies the container element for the scrollbar to be appended in. If false, scrollbar will be appended to the body.
scrollbarClassstringc-scrollbarSmooth only<br>Scrollbar element class.
multipliernumber1Smooth only<br>Factor applied to the scroll delta, allowing to boost/reduce scrolling speed (regardless of the platform).
firefoxMultipliernumber50Smooth only<br>Boost scrolling speed of Firefox on Windows.
touchMultipliernumber2Smooth only<br>Multiply touch action to scroll faster than finger movement.
scrollFromAnywherebooleanfalseSmooth only<br>By default locomotive-scroll listens for scroll events only on the scroll container (el option). With this option set to true, it listens on the whole document instead.
gestureDirectionstringverticalSmooth only<br>Defines which gesture direction(s) scrolls in your instance. You can use : <ul><li>vertical</li><li>horizontal</li><li>both</li></ul>
tablet & smartphoneobjectObject allowing to override some options for a particular context. You can specify: <ul><li>smooth</li><li>direction</li><li>horizontalGesture</li></ul>For tablet context you can also define breakpoint (integer, defaults to 1024) to set the max-width breakpoint for tablets.
reloadOnContextChangebooleanfalseAllows to reload the page when switching between desktop, tablet and smartphone contexts. It can be useful if your page changes a lot between contexts and you want to reset everything.
resetNativeScrollbooleantrueSets history.scrollRestoration = 'manual' and calls window.scrollTo(0, 0) on locomotive-scroll init in Native Class. Useful if you use transitions with native scrolling, otherwise we advise to set it to false if you don't want to break History API's scroll restoration feature.

Element attributes

AttributeValuesDescription
data-scrollDetect if in-view.
data-scroll-idstring(Optional) Useful if you want to scope your element and get the progress of your element in the viewport for example.
data-scroll-containerDefines the scroll container. Required for basic styling.
data-scroll-sectionDefines a scrollable section. Splitting your page into sections may improve performance.
data-scroll-classstringElement in-view class.
data-scroll-offsetstringElement in-view trigger offset : bottom,top<br>First value is bottom offset, second (optional) is top offset.<br> Percent is relative to viewport height, otherwise it's absolute pixels.<br>E.g. "10", "100,50%", "25%, 15%"
data-scroll-repeatbooleanElement in-view detection repeat.
data-scroll-callstringElement in-view trigger call event.
data-scroll-positionstringtop, bottom, left or right<br>Window position of in-view trigger.
data-scroll-speednumberSmooth only<br>Element parallax speed. A negative value will reverse the direction.
data-scroll-delaynumberSmooth only<br>Element's parallax lerp delay.
data-scroll-directionstringSmooth only<br>Element's parallax direction. vertical or horizontal
data-scroll-stickySmooth only<br>Sticky element. Starts and stops at data-scroll-target position.
data-scroll-targetstringSmooth only<br>Target element's in-view position.

Instance methods

MethodDescriptionArguments
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.<div>target: Defines where you want to scroll. Available values types are :<ul><li>node : a dom element</li><li>string : you can type your own selector, or use values "top" and "bottom" to reach scroll boundaries</li><li>int : An absolute scroll coordinate in pixels</li></ul></div><div>options (optional, object) : Settings object. Available values are: <ul><li>offset (integer) : Defines an offset from your target. E.g. -100 if you want to scroll 100 pixels above your target</li><li>callback (function) : Called when scrollTo completes (note that it won't wait for lerp to stabilize)</li><li>duration (integer) : Defines the duration of the scroll animation in milliseconds. Defaults to 1000<br>Smooth only</li><li>easing (array) : An array of 4 floats between 0 and 1 defining the bezier curve for the animation's easing. <br>Defaults to [0.25, 0.00, 0.35, 1.00]<br>See https://greweb.me/2012/02/bezier-curve-based-easing-functions-from-concept-to-implementation<br>Keep in mind this will also be affected by the lerp unless you set disableLerp to true.<br>Smooth only</li><li>disableLerp (boolean) : Lerp effect won't be applied if set to true<br>Smooth only</li></ul>

Instance events

EventArgumentsDescription
scrollobjReturns scroll instance (position, limit, speed, direction and current in-view elements).
callfuncTrigger 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

NameDescription
Virtual ScrollCustom scroll event with inertia/momentum.
modularScrollElements in viewport detection. Forked from it, not a dependency.
bezier-easingAllows 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://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=Object.assign%2CElement.prototype.append%2CNodeList.prototype.forEach%2CCustomEvent%2Csmoothscroll" crossorigin="anonymous"></script>

Who's using Locomotive Scroll?

Related