Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://locomotivemtl.github.io/locomotive-scroll/
🛤 Detection of elements in viewport & smooth scrolling with parallax.
https://locomotivemtl.github.io/locomotive-scroll/
in-view javascript parallax smooth-scrolling
Last synced: 25 days ago
JSON representation
🛤 Detection of elements in viewport & smooth scrolling with parallax.
- Host: GitHub
- URL: https://locomotivemtl.github.io/locomotive-scroll/
- Owner: locomotivemtl
- License: mit
- Created: 2016-10-12T20:12:46.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-04-29T17:54:40.000Z (6 months ago)
- Last Synced: 2024-05-17T05:43:54.325Z (6 months ago)
- Topics: in-view, javascript, parallax, smooth-scrolling
- Language: JavaScript
- Homepage: https://locomotivemtl.github.io/locomotive-scroll
- Size: 7.92 MB
- Stars: 7,430
- Watchers: 73
- Forks: 1,107
- Open Issues: 263
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-dev-design-stuff - Locomotive Scroll - A javascript framework to make advanced scroll. (Web Development / Library)
README
[](https://www.npmjs.com/package/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`
| `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. |
- `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` (_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