Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/locomotivemtl/locomotive-scroll

🛤 Detection of elements in viewport & smooth scrolling with parallax.
https://github.com/locomotivemtl/locomotive-scroll

in-view javascript parallax smooth-scrolling

Last synced: 3 days ago
JSON representation

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

Awesome Lists containing this project

README

        

[![](https://img.shields.io/npm/v/locomotive-scroll)](https://www.npmjs.com/package/locomotive-scroll)
[![](https://img.shields.io/npm/dm/locomotive-scroll)](https://www.npmjs.com/package/locomotive-scroll)

> 🚀 **Locomotive Scroll v5 Beta Release**
>
> Try out the beta version of Locomotive Scroll v5!
>
> 🔗 [Click here to try Locomotive Scroll v5 Beta](https://github.com/locomotivemtl/locomotive-scroll/tree/v5-beta)
>
> Your feedback is valuable during this beta testing phase. If you encounter any issues or have suggestions, please [open an issue](https://github.com/locomotivemtl/locomotive-scroll/issues/new?labels=v5&template=bug_report.md).
>
> Happy scrolling! 😄






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.

```sh
npm install locomotive-scroll
```

## Usage

### Basic
With simple detection.

#### HTML
```html

Hey


👋


```

#### CSS
Add the base styles to your CSS file.

[`locomotive-scroll.css`](https://github.com/locomotivemtl/locomotive-scroll/blob/master/dist/locomotive-scroll.css)

#### JS

##### With a bundler
```js
import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll();
```

##### Or without
```js

(function () {
var scroll = new LocomotiveScroll();
})();

```
_Get the [JS file](https://github.com/locomotivemtl/locomotive-scroll/blob/master/dist/locomotive-scroll.min.js)._

### Smooth
With smooth scrolling and parallax.

```html



Hey


👋




What's up?


😬




```

```js
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
```html
Come here please.
```

```js
import LocomotiveScroll from 'locomotive-scroll';

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

scroll.scrollTo(target);
```

#### With events

```html

Trigger

Trigger

Trigger

```

```js
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

| 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. |
| `initPosition` | `object` | `{ x: 0, y: 0 }` | ![Smooth only][smooth-only]
An `object` defining the initial scroll coordinates on a smooth instance. For example: `{ x: 0, y: 1000 }` |
| `direction` | `string` | `vertical` | ![Smooth only][smooth-only]
Scroll direction: `vertical` or `horizontal` |
| `lerp` | `number` | `0.1` | ![Smooth only][smooth-only]
Linear interpolation (lerp) intensity. Float between `0` and `1`.
This defines the "smoothness" intensity. The closer to `0`, the smoother. |
| `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. |
| `scrollbarContainer` | `object` | `false` | ![Smooth only][smooth-only]
Specifies the container element for the scrollbar to be appended in. If false, scrollbar will be appended to the body. |
| `scrollbarClass` | `string` | `c-scrollbar` | ![Smooth only][smooth-only]
Scrollbar element class. |
| `multiplier` | `number` | `1` | ![Smooth only][smooth-only]
Factor applied to the scroll delta, allowing to boost/reduce scrolling speed (regardless of the platform). |
| `firefoxMultiplier` | `number` | `50` | ![Smooth only][smooth-only]
Boost scrolling speed of Firefox on Windows. |
| `touchMultiplier` | `number` | `2` | ![Smooth only][smooth-only]
Multiply touch action to scroll faster than finger movement. |
| `scrollFromAnywhere` | `boolean` | `false` | ![Smooth only][smooth-only]
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. |
| `gestureDirection` | `string` | `vertical` | ![Smooth only][smooth-only]
Defines which gesture direction(s) scrolls in your instance. You can use :


  • `vertical`

  • `horizontal`

  • `both`

|
| `tablet` & `smartphone` | `object` | | Object allowing to override some options for a particular context. You can specify:

  • `smooth`

  • `direction`

  • `horizontalGesture`

For `tablet` context you can also define `breakpoint` (_integer_, defaults to 1024) to set the max-width breakpoint for tablets. |
| `reloadOnContextChange` | `boolean` | `false` | Allows 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. |
| `resetNativeScroll` | `boolean` | `true` | Sets `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

| 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](https://github.com/locomotivemtl/locomotive-scroll/blob/master/dist/locomotive-scroll.css). |
| `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` | ![Smooth only][smooth-only]
Element parallax speed. A negative value will reverse the direction. |
| `data-scroll-delay` | `number` | ![Smooth only][smooth-only]
Element's parallax lerp delay. |
| `data-scroll-direction` | `string` | ![Smooth only][smooth-only]
Element's parallax direction. `vertical` or `horizontal` |
| `data-scroll-sticky` | | ![Smooth only][smooth-only]
Sticky element. Starts and stops at `data-scroll-target` position. |
| `data-scroll-target` | `string` | ![Smooth only][smooth-only]
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 :

  • `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


`options` (optional, _object_) : Settings object. Available values are:

  • `offset` (_integer_) : Defines an offset from your target. E.g. `-100` if you want to scroll 100 pixels above your target

  • `callback` (_function_) : Called when scrollTo completes (note that it won't wait for lerp to stabilize)

  • `duration` (_integer_) : Defines the duration of the scroll animation in milliseconds. Defaults to `1000`
    ![Smooth only][smooth-only]

  • `easing` (_array_) : An `array` of 4 floats between 0 and 1 defining the bezier curve for the animation's easing.
    Defaults to `[0.25, 0.00, 0.35, 1.00]`
    See [https://greweb.me/2012/02/bezier-curve-based-easing-functions-from-concept-to-implementation](https://greweb.me/2012/02/bezier-curve-based-easing-functions-from-concept-to-implementation)
    *Keep in mind this will also be affected by the lerp unless you set `disableLerp` to `true`*.
    ![Smooth only][smooth-only]

  • `disableLerp` (_boolean_) : Lerp effect won't be applied if set to `true`
    ![Smooth only][smooth-only]

|

## 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
```html

Hey


```
#### JS
```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 |

[instance events]: #instance-events
[Virtual Scroll]: https://github.com/ayamflow/virtual-scroll
[modularScroll]: https://github.com/modularorg/modularscroll
[bezier-easing]: https://github.com/gre/bezier-easing

## 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.

```html

```

## Who's using Locomotive Scroll?
- [thierrychopain.com](https://thierrychopain.com/)
- [clmt.paris](https://clmt.paris/)
- [miragefestival.com/2020](https://www.miragefestival.com/2020/)
- [mazellier.design](https://www.mazellier.design/)
- [ccccontemple.com](https://ccccontemple.com/)
- [abhishekjha.me/muteza](https://abhishekjha.me/muteza/)
- [normal.studio](https://normal.studio/en/)
- [mixlegno.com](https://www.mixlegno.com/)
- [nfq.group](https://nfq.group/)
- [works.studio](https://works.studio/)
- [beangels.eu](https://www.beangels.eu/)
- [izakaya-caen.fr](https://www.izakaya-caen.fr/)
- [white-elephant.fr](https://www.white-elephant.fr/)
- [henge07.com](https://www.henge07.com/)
- [loirevalleylodges.com](https://loirevalleylodges.com/)

## Related

- [Locomotive Boilerplate 🚂](https://github.com/locomotivemtl/locomotive-boilerplate)

[smooth-only]: https://img.shields.io/badge/smooth-only-blue