Locomotive Scroll

Detection of elements in viewport & smooth scrolling with parallax effects.

Installation

npm install locomotive-scroll

Basic example

HTML

<html>
    <body>
        <div class="o-scroll" id="js-scroll">
            <div data-scroll-section>
                <h1 data-scroll data-scroll-speed="1">Hello</h1>
                <p data-scroll data-scroll-speed="2">My friends</p>
            </div>

            <div data-scroll-section>
                <h2 data-scroll data-scroll-speed="1">I hope</h2>
                <p>You are doing good</p>
            </div>            
        </div>
    </body>
</html>

Note : scroll-section are not required, however they improve performance a lot particularly on long pages

CSS

Import the basic styles here

JS

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll({
    el: document.querySelector('#js-scroll'),
    smooth: true
});

Usage

With options

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll({
    el: document.querySelector('#js-scroll'),
    smooth: true,
    scrollbarClass: 'my-scrollbar'
});

With methods

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll();
const target = document.querySelector('#js-target');

scroll.scrollTo(target);

With events

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 😎
});

<!-- 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>

Instance options

Option	Type	Default	Description
`el`	`object`	`document`	Scroll container element.
`name`	`string`	`'scroll'`	Data attribute prefix (`data-scroll-xxxx`).
`offset`	`array(2)`	`[0,0]`	Global in-view trigger offset : `[bottom,top]` Use a string with `%` to use a percentage of the viewport height. Use a numeric value for absolute pixels unit. E.g. `["30%",0]`, `[100,0]`, `["30%", 100]`
`repeat`	`boolean`	`false`	Repeat in-view detection.
`smooth`	`boolean`	`false`	Smooth scrolling.
`smoothMobile`	`boolean`	`false`	Smooth scrolling on iOS and Android devices.
`direction`	`string`	`vertical`	Scroll direction.
`inertia`	`number`	`1`	Lerp intensity.
`getDirection`	`boolean`	`false`	Add direction to scroll event.
`getSpeed`	`boolean`	`false`	Add speed to scroll event.
`class`	`string`	`is-inview`	Element in-view class.
`initClass`	`string`	`has-scroll-init`	Initialize class.
`scrollingClass`	`string`	`has-scroll-scrolling`	Is scrolling class.
`draggingClass`	`string`	`has-scroll-dragging`	Is dragging class.
`smoothClass`	`string`	`has-scroll-smooth`	Has smooth scrolling class.
`scrollbarClass`	`string`	`c-scrollbar`	Scrollbar element class.
`firefoxMultiplier`	`number`	`50`	Boost scrolling speed of Firefox on Windows.
`touchMultiplier`	`number`	`2`	Mutiply touch action to scroll faster than finger movement.

Element attributes

Attribute	Values	Description
`data-scroll`		Detect if in-view.
`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`	`true`, `false`	Element in-view detection repeat.
`data-scroll-call`	`string`	Element in-view trigger call event.
`data-scroll-speed`	`number`	Element parallax speed. A negative value will reverse the direction.
`data-scroll-target`	`string`	Target element's in-view position.
`data-scroll-position`	`top`, `bottom`	Window position of in-view trigger.
`data-scroll-direction`	`vertical`, `horizontal`	Element's parallax direction.
`data-scroll-delay`	`number`	Element's parallax lerp delay.
`data-scroll-sticky`		Sticky element. Starts and stops at `data-scroll-target` 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, offset)`	Scroll to an element.	`target`: Defines where you want to scroll. Available values types are : `node` : a dom element `string` : you can type your own selector, or use values `"top"` and `"bottom"` to reach scroll boundaries `int` : An absolute scroll coordinate in pixels `offset` (optionnal) : A `number` that defines an offset from your target. E.g. `-100` if you want to scroll 100 pixels above your target

Instance events

Event	Arguments	Description
`scroll`	`obj`	Returns scroll instance (position, limit, speed, direction).
`call`	`func`	Trigger if in-view. Returns your `string` or `array` if contains `,`.

Dependencies

Name	Description
Virtual Scroll	Custom scroll event with inertia/momentum.
modularScroll	Elements in viewport detection. Forked from it, not a dependency.

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 this 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>

mathieustan / locomotive-scroll