{"id":13447438,"url":"https://github.com/locomotivemtl/locomotive-scroll","last_synced_at":"2025-05-12T13:23:18.830Z","repository":{"id":37252135,"uuid":"70737507","full_name":"locomotivemtl/locomotive-scroll","owner":"locomotivemtl","description":"🛤 Detection of elements in viewport \u0026 smooth scrolling with parallax.","archived":false,"fork":false,"pushed_at":"2024-08-30T16:08:23.000Z","size":9942,"stargazers_count":8300,"open_issues_count":272,"forks_count":1124,"subscribers_count":78,"default_branch":"master","last_synced_at":"2025-05-09T02:58:53.678Z","etag":null,"topics":["in-view","javascript","parallax","smooth-scrolling"],"latest_commit_sha":null,"homepage":"https://locomotivemtl.github.io/locomotive-scroll","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/locomotivemtl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-12T20:12:46.000Z","updated_at":"2025-05-08T13:30:56.000Z","dependencies_parsed_at":"2023-02-05T02:01:15.624Z","dependency_job_id":"fb8465b2-7dbb-43fd-9d28-99706fd9a0a2","html_url":"https://github.com/locomotivemtl/locomotive-scroll","commit_stats":{"total_commits":353,"total_committers":30,"mean_commits":"11.766666666666667","dds":0.6827195467422096,"last_synced_commit":"53d7a2885e6740cddd0c51ca6cd8e4f76328f1c1"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Flocomotive-scroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Flocomotive-scroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Flocomotive-scroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locomotivemtl%2Flocomotive-scroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locomotivemtl","download_url":"https://codeload.github.com/locomotivemtl/locomotive-scroll/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253453176,"owners_count":21911053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["in-view","javascript","parallax","smooth-scrolling"],"created_at":"2024-07-31T05:01:17.692Z","updated_at":"2025-05-12T13:23:18.806Z","avatar_url":"https://github.com/locomotivemtl.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","JS","Uncategorized","Scroll","JavaScript Utilities","Table of Contents","🔧 Utilities \u0026 Miscellaneous"],"sub_categories":["Scroll","Uncategorized","Other","CSS Animation","Scroll Animation Libraries"],"readme":"[![](https://img.shields.io/npm/v/locomotive-scroll)](https://www.npmjs.com/package/locomotive-scroll)\n[![](https://img.shields.io/npm/dm/locomotive-scroll)](https://www.npmjs.com/package/locomotive-scroll)\n\n\u003e 🚀 **Locomotive Scroll v5 Beta Release**\n\u003e\n\u003e Try out the beta version of Locomotive Scroll v5!\n\u003e\n\u003e 🔗 [Click here to try Locomotive Scroll v5 Beta](https://github.com/locomotivemtl/locomotive-scroll/tree/v5-beta)\n\u003e\n\u003e 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\u0026template=bug_report.md).\n\u003e\n\u003e Happy scrolling! 😄\n\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/locomotivemtl/locomotive-scroll\"\u003e\n        \u003cimg src=\"https://user-images.githubusercontent.com/4596862/58807621-67aeec00-85e6-11e9-8e3a-3fe4123ee76c.png\" height=\"140\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eLocomotive Scroll\u003c/h1\u003e\n\u003cp align=\"center\"\u003eDetection of elements in viewport \u0026 smooth scrolling with parallax effects.\u003c/p\u003e\n\n## Installation\n\n\u003e ⚠️ Scroll-hijacking is a controversial practice that can cause usability, accessibility, and performance issues. Please use responsibly.\n\n```sh\nnpm install locomotive-scroll\n```\n\n## Usage\n\n### Basic\nWith simple detection.\n\n#### HTML\n```html\n\u003ch1 data-scroll\u003eHey\u003c/h1\u003e\n\u003cp data-scroll\u003e👋\u003c/p\u003e\n```\n\n#### CSS\nAdd the base styles to your CSS file.\n\n[`locomotive-scroll.css`](https://github.com/locomotivemtl/locomotive-scroll/blob/master/dist/locomotive-scroll.css)\n\n#### JS\n\n##### With a bundler\n```js\nimport LocomotiveScroll from 'locomotive-scroll';\n\nconst scroll = new LocomotiveScroll();\n```\n\n##### Or without\n```js\n\u003cscript src=\"locomotive-scroll.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n    (function () {\n        var scroll = new LocomotiveScroll();\n    })();\n\u003c/script\u003e\n```\n_Get the [JS file](https://github.com/locomotivemtl/locomotive-scroll/blob/master/dist/locomotive-scroll.min.js)._\n\n### Smooth\nWith smooth scrolling and parallax.\n\n```html\n\u003cdiv data-scroll-container\u003e\n    \u003cdiv data-scroll-section\u003e\n        \u003ch1 data-scroll\u003eHey\u003c/h1\u003e\n        \u003cp data-scroll\u003e👋\u003c/p\u003e\n    \u003c/div\u003e\n    \u003cdiv data-scroll-section\u003e\n        \u003ch2 data-scroll data-scroll-speed=\"1\"\u003eWhat's up?\u003c/h2\u003e\n        \u003cp data-scroll data-scroll-speed=\"2\"\u003e😬\u003c/p\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n```\n\n```js\nimport LocomotiveScroll from 'locomotive-scroll';\n\nconst scroll = new LocomotiveScroll({\n    el: document.querySelector('[data-scroll-container]'),\n    smooth: true\n});\n```\n\n_Note: scroll-sections are optional but recommended to improve performance, particularly in long pages._\n\n### Advanced\nMake it do what you want.\n\n#### With methods\n```html\n\u003csection id=\"js-target\"\u003eCome here please.\u003c/section\u003e\n```\n\n```js\nimport LocomotiveScroll from 'locomotive-scroll';\n\nconst scroll = new LocomotiveScroll();\nconst target = document.querySelector('#js-target');\n\nscroll.scrollTo(target);\n```\n\n#### With events\n\n```html\n\u003c!-- Using modularJS --\u003e\n\u003cdiv data-scroll data-scroll-call=\"function, module\"\u003eTrigger\u003c/div\u003e\n\u003c!-- Using jQuery events --\u003e\n\u003cdiv data-scroll data-scroll-call=\"EVENT_NAME\"\u003eTrigger\u003c/div\u003e\n\u003c!-- Or do it your own way 😎 --\u003e\n\u003cdiv data-scroll data-scroll-call=\"{y,o,l,o}\"\u003eTrigger\u003c/div\u003e\n```\n\n```js\nimport LocomotiveScroll from 'locomotive-scroll';\n\nconst scroll = new LocomotiveScroll();\n\nscroll.on('call', func =\u003e {\n    // Using modularJS\n    this.call(...func);\n    // Using jQuery events\n    $(document).trigger(func);\n    // Or do it your own way 😎\n});\n```\n\n## Instance options\n\n| Option                  | Type      | Default                | Description                                                                                                                                                                                                                                                                                        |\n| ----------------------- | --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `el`                    | `object`  | `document`             | Scroll container element.                                                                                                                                                                                                                                                                          |\n| `name`                  | `string`  | `'scroll'`             | Data attribute prefix (`data-scroll-xxxx`).                                                                                                                                                                                                                                                        |                                                                                                                                                                                                                                                               |\n| `offset`                | `array(2)`| `[0,0]`                | Global in-view trigger offset : `[bottom,top]`\u003cbr\u003eUse a string with `%` to use a percentage of the viewport height.\u003cbr\u003eUse a numeric value for absolute pixels unit.\u003cbr\u003eE.g. `[\"30%\",0]`, `[100,0]`, `[\"30%\", 100]`                                                                                |\n| `repeat`                | `boolean` | `false`                | Repeat in-view detection.                                                                                                                                                                                                                                                                          |\n| `smooth`                | `boolean` | `false`                | Smooth scrolling.                                                                                                                                                                                                                                                                                  |\n| `initPosition`          | `object`  | `{ x: 0, y: 0 }`       | ![Smooth only][smooth-only]\u003cbr\u003eAn `object` defining the initial scroll coordinates on a smooth instance. For example: `{ x: 0, y: 1000 }` |\n| `direction`             | `string`  | `vertical`             | ![Smooth only][smooth-only]\u003cbr\u003eScroll direction: `vertical` or `horizontal`                                                                                                                                                                                                                        |\n| `lerp`                  | `number`  | `0.1`                  | ![Smooth only][smooth-only]\u003cbr\u003eLinear interpolation (lerp) intensity. Float between `0` and `1`.\u003cbr\u003eThis defines the \"smoothness\" intensity. The closer to `0`, the smoother.                                                                                                                      |\n| `getDirection`          | `boolean` | `false`                | Add direction to scroll event.                                                                                                                                                                                                                                                                     |\n| `getSpeed`              | `boolean` | `false`                | Add speed to scroll event.                                                                                                                                                                                                                                                                         |\n| `class`                 | `string`  | `is-inview`            | Element in-view class.                                                                                                                                                                                                                                                                             |\n| `initClass`             | `string`  | `has-scroll-init`      | Initialize class.                                                                                                                                                                                                                                                                                  |\n| `scrollingClass`        | `string`  | `has-scroll-scrolling` | Is scrolling class.                                                                                                                                                                                                                                                                                |\n| `draggingClass`         | `string`  | `has-scroll-dragging`  | Is dragging class.                                                                                                                                                                                                                                                                                 |\n| `smoothClass`           | `string`  | `has-scroll-smooth`    | Has smooth scrolling class.                                                                                                                                                                                                                                                                        |\n| `scrollbarContainer`    | `object`  | `false`                | ![Smooth only][smooth-only]\u003cbr\u003eSpecifies the container element for the scrollbar to be appended in. If false, scrollbar will be appended to the body. |\n| `scrollbarClass`        | `string`  | `c-scrollbar`          | ![Smooth only][smooth-only]\u003cbr\u003eScrollbar element class.                                                                                                                                                                                                                                                                           |\n| `multiplier`            | `number`  | `1`                    | ![Smooth only][smooth-only]\u003cbr\u003eFactor applied to the scroll delta, allowing to boost/reduce scrolling speed (regardless of the platform).                                                                                                                                                          |\n| `firefoxMultiplier`     | `number`  | `50`                   | ![Smooth only][smooth-only]\u003cbr\u003eBoost scrolling speed of Firefox on Windows.                                                                                                                                                                                                                        |\n| `touchMultiplier`       | `number`  | `2`                    | ![Smooth only][smooth-only]\u003cbr\u003eMultiply touch action to scroll faster than finger movement.                                                                                                                                                                                                         |\n| `scrollFromAnywhere`    | `boolean` | `false`                | ![Smooth only][smooth-only]\u003cbr\u003eBy 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.                                                                                          |\n| `gestureDirection`     | `string` | `vertical`                | ![Smooth only][smooth-only]\u003cbr\u003eDefines which gesture direction(s) scrolls in your instance. You can use : \u003cul\u003e\u003cli\u003e`vertical`\u003c/li\u003e\u003cli\u003e`horizontal`\u003c/li\u003e\u003cli\u003e`both`\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                         |\n| `tablet` \u0026 `smartphone` | `object`  |                        | Object allowing to override some options for a particular context. You can specify: \u003cul\u003e\u003cli\u003e`smooth`\u003c/li\u003e\u003cli\u003e`direction`\u003c/li\u003e\u003cli\u003e`horizontalGesture`\u003c/li\u003e\u003c/ul\u003eFor `tablet` context you can also define `breakpoint` (_integer_, defaults to 1024) to set the max-width breakpoint for tablets.     |\n| `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.                                                                                                     |\n| `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. |\n\n## Element attributes\n\n| Attribute               | Values                   | Description                                                                              |\n| ----------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |\n| `data-scroll`           |                          | Detect if in-view.                                                                       |\n| `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. |\n| `data-scroll-container` |                          | Defines the scroll container. Required for [basic styling](https://github.com/locomotivemtl/locomotive-scroll/blob/master/dist/locomotive-scroll.css).                                                                                     |\n| `data-scroll-section`   |                          | Defines a scrollable section. Splitting your page into sections may improve performance. |\n| `data-scroll-class`     | `string`                 | Element in-view class.                                                                   |\n| `data-scroll-offset`    | `string`                 | Element in-view trigger offset : `bottom,top`\u003cbr\u003eFirst value is `bottom` offset, second (optional) is `top` offset.\u003cbr\u003e Percent is relative to viewport height, otherwise it's absolute pixels.\u003cbr\u003eE.g. `\"10\"`, `\"100,50%\"`, `\"25%, 15%\"`  |\n| `data-scroll-repeat`    | `boolean`                | Element in-view detection repeat.                                                        |\n| `data-scroll-call`      | `string`                 | Element in-view trigger call event.                                                      |\n| `data-scroll-position`  | `string`                 | `top`, `bottom`, `left` or `right`\u003cbr\u003eWindow position of in-view trigger.                |\n| `data-scroll-speed`     | `number`                 | ![Smooth only][smooth-only]\u003cbr\u003eElement parallax speed. A negative value will reverse the direction. |\n| `data-scroll-delay`     | `number`                 | ![Smooth only][smooth-only]\u003cbr\u003eElement's parallax lerp delay.                            |\n| `data-scroll-direction` | `string`                 | ![Smooth only][smooth-only]\u003cbr\u003eElement's parallax direction. `vertical` or `horizontal`  |\n| `data-scroll-sticky`    |                          | ![Smooth only][smooth-only]\u003cbr\u003eSticky element. Starts and stops at `data-scroll-target` position. |\n| `data-scroll-target`    | `string`                 | ![Smooth only][smooth-only]\u003cbr\u003eTarget element's in-view position.                        |\n\n## Instance methods\n\n| Method                     | Description                    | Arguments                                                                       |\n| -------------------------- | ------------------------------ | ------------------------------------------------------------------------------- |\n| `init()`                   | Reinitializes the scroll.      |                                                                                 |\n| `on(eventName, function)`  | Listen [instance events] ⬇.    |                                                                                 |\n| `update()`                 | Updates all element positions. |                                                                                 |\n| `destroy()`                | Destroys the scroll events.    |                                                                                 |\n| `start()`                  | Restarts the scroll events.    |                                                                                 |\n| `stop()`                   | Stops the scroll events.       |                                                                                 |\n| `scrollTo(target, options)`| Scroll to a target.            | \u003cdiv\u003e`target`: Defines where you want to scroll. Available values types are :\u003cul\u003e\u003cli\u003e`node` : a dom element\u003c/li\u003e\u003cli\u003e`string` : you can type your own selector, or use values `\"top\"` and `\"bottom\"` to reach scroll boundaries\u003c/li\u003e\u003cli\u003e`int` : An absolute scroll coordinate in pixels\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cdiv\u003e`options` (optional, _object_) : Settings object. Available values are: \u003cul\u003e\u003cli\u003e`offset` (_integer_) : Defines an offset from your target. E.g. `-100` if you want to scroll 100 pixels above your target\u003c/li\u003e\u003cli\u003e`callback` (_function_) : Called when scrollTo completes (note that it won't wait for lerp to stabilize)\u003c/li\u003e\u003cli\u003e`duration` (_integer_) : Defines the duration of the scroll animation in milliseconds. Defaults to `1000`\u003cbr\u003e![Smooth only][smooth-only]\u003c/li\u003e\u003cli\u003e`easing` (_array_) : An `array` of 4 floats between 0 and 1 defining the bezier curve for the animation's easing. \u003cbr\u003eDefaults to `[0.25, 0.00, 0.35, 1.00]`\u003cbr\u003eSee [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)\u003cbr\u003e*Keep in mind this will also be affected by the lerp unless you set `disableLerp` to `true`*.\u003cbr\u003e![Smooth only][smooth-only]\u003c/li\u003e\u003cli\u003e`disableLerp` (_boolean_) : Lerp effect won't be applied if set to `true`\u003cbr\u003e![Smooth only][smooth-only]\u003c/li\u003e\u003c/ul\u003e |\n\n## Instance events\n\n| Event    | Arguments | Description                                                           |\n| -------- | --------- | --------------------------------------------------------------------- |\n| `scroll` | `obj`     | Returns scroll instance (position, limit, speed, direction and current in-view elements).          |\n| `call`   | `func`    | Trigger if in-view. Returns your `string` or `array` if contains `,`. |\n\n## Progressive playing animations example (like gsap)\nAll `data-scroll` elements have a progress value.\nIn the on scroll event you can get all current in-view elements.\n#### HTML\n```html\n\u003ch1 data-scroll data-scroll-id=\"hey\"\u003eHey\u003c/h1\u003e\n```\n#### JS\n```js\nscroll.on('scroll', (args) =\u003e {\n    // Get all current elements : args.currentElements\n    if(typeof args.currentElements['hey'] === 'object') {\n        let progress = args.currentElements['hey'].progress;\n        console.log(progress);\n        // ouput log example: 0.34\n        // gsap example : myGsapAnimation.progress(progress);\n    }\n});\n```\n\n\n## Dependencies\n\n| Name             | Description                                                        |\n| ---------------- | ------------------------------------------------------------------ |\n| [Virtual Scroll] | Custom scroll event with inertia/momentum.                         |\n| [modularScroll]  | Elements in viewport detection. Forked from it, not a dependency.  |\n| [bezier-easing]  | Allows to define an easing to `scrollTo` movement                  |\n\n[instance events]: #instance-events\n[Virtual Scroll]: https://github.com/ayamflow/virtual-scroll\n[modularScroll]: https://github.com/modularorg/modularscroll\n[bezier-easing]: https://github.com/gre/bezier-easing\n\n\n## Browser support\n\nWorks on most modern browsers. Chrome, Firefox, Safari, Edge...\n\nTo get IE 11 support, you need polyfills.\nYou can use your own or include these before our script.\n\n```html\n\u003cscript nomodule src=\"https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/7.6.0/polyfill.min.js\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n\u003cscript nomodule src=\"https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=Object.assign%2CElement.prototype.append%2CNodeList.prototype.forEach%2CCustomEvent%2Csmoothscroll\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n```\n\n## Who's using Locomotive Scroll?\n- [thierrychopain.com](https://thierrychopain.com/)\n- [clmt.paris](https://clmt.paris/)\n- [miragefestival.com/2020](https://www.miragefestival.com/2020/)\n- [mazellier.design](https://www.mazellier.design/)\n- [ccccontemple.com](https://ccccontemple.com/)\n- [abhishekjha.me/muteza](https://abhishekjha.me/muteza/)\n- [normal.studio](https://normal.studio/en/)\n- [mixlegno.com](https://www.mixlegno.com/)\n- [nfq.group](https://nfq.group/)\n- [works.studio](https://works.studio/)\n- [beangels.eu](https://www.beangels.eu/)\n- [izakaya-caen.fr](https://www.izakaya-caen.fr/)\n- [white-elephant.fr](https://www.white-elephant.fr/)\n- [henge07.com](https://www.henge07.com/)\n- [loirevalleylodges.com](https://loirevalleylodges.com/)\n\n## Related\n\n- [Locomotive Boilerplate 🚂](https://github.com/locomotivemtl/locomotive-boilerplate)\n\n[smooth-only]: https://img.shields.io/badge/smooth-only-blue\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocomotivemtl%2Flocomotive-scroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocomotivemtl%2Flocomotive-scroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocomotivemtl%2Flocomotive-scroll/lists"}