Locomotive Scroll

https://scroll.locomotive.ca/docs
Admin
Locomotive Scroll is a lightweight JavaScript library for smooth scrolling animations, advanced...
Tokens:15,734
Snippets:145
Trust Score:9.6
Update:8 months ago
Show doc for...
Tokens:
Raw
### Locomotive Scroll v4 Instance Options Example

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

An example of initializing Locomotive Scroll v4 with various instance options, including element selection, smooth scrolling, direction, lerp, multiplier, and classes.

```javascript
const scroll = new LocomotiveScroll({  
    el: document.querySelector('[data-scroll-container]'),  
    smooth: true,  
    direction: 'vertical',  
    lerp: 0.1,  
    multiplier: 1,  
    class: 'is-inview',  
    scrollbarClass: 'c-scrollbar',  
});  
```

--------------------------------

### v4 Migration: JavaScript Initialization Example

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows a typical JavaScript initialization for Locomotive Scroll v4, including options like `el`, `smooth`, `direction`, `lerp`, and event listeners for 'scroll' and 'call'.

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

const scroll = new LocomotiveScroll({
    el: document.querySelector('[data-scroll-container]'),
    smooth: true,
    direction: 'vertical',
    lerp: 0.1,
    class: 'is-inview',
});

scroll.on('scroll', (args) => {
    if (args.currentElements['hero']) {
        console.log(args.currentElements['hero'].progress);
    }
});

scroll.on('call', (func) => {
    this.call(...func); // ModularJS
});
```

--------------------------------

### Locomotive Scroll v4 Basic Setup (HTML and JS)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates the basic HTML structure and JavaScript initialization for Locomotive Scroll v4. It requires specific data attributes for the scroll container and sections.

```html
<div data-scroll-container>  
    <div data-scroll-section>  
        <h1 data-scroll>Hey</h1>  
    </div>  
</div>  
```

```javascript
import LocomotiveScroll from 'locomotive-scroll';  
  
const scroll = new LocomotiveScroll({  
    el: document.querySelector('[data-scroll-container]'),  
    smooth: true,  
});  
```

--------------------------------

### Methods (v4 vs v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Compares the available methods in v4 and v5, noting updates, removals, and renames.

```APIDOC
## Methods

### Description
This section outlines the methods available for controlling the scroll behavior, highlighting changes between v4 and v5, including renamed and removed methods.

### Updated Methods
| Method      | v4 | v5 | Notes                     |
|-------------|----|----|---------------------------|
| `destroy()` | ✅ | ✅ | Same API                  |
| `start()`   | ✅ | ✅ | Same API                  |
| `stop()`    | ✅ | ✅ | Same API                  |
| `scrollTo(target)` | ✅ | ✅ | Delegated to Lenis        |
| `update()`  | ✅ | ❌ | Renamed to `resize()`     |
| `init()`    | ✅ | ❌ | No longer needed          |

### v4 Example
```javascript
scroll.update();
scroll.destroy();
scroll.init(); // Reinitialize
```
```

--------------------------------

### v4 Migration: HTML Structure Example

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Presents an example of HTML structure used with Locomotive Scroll v4, including attributes like `data-scroll-container`, `data-scroll-section`, `data-scroll-sticky`, and `data-scroll-call`.

```html
<div data-scroll-container>
    <div data-scroll-section>
        <h1 data-scroll data-scroll-id="hero">Hero</h1>
        <div data-scroll data-scroll-speed="2">Parallax</div>
        <div data-scroll data-scroll-call="videoPlay, VideoModule">Video</div>
        <div data-scroll-sticky data-scroll-target="#end">Sticky</div>
    </div>
    <div id="end" data-scroll-section>End</div>
</div>
```

--------------------------------

### Locomotive Scroll v5 Basic Setup (HTML and JS)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows the simplified HTML structure and JavaScript initialization for Locomotive Scroll v5. Version 5, built on Lenis, does not require specific data attributes for the scroll container.

```html
<main>  
    <h1 data-scroll>Hey</h1>  
</main>  
```

```javascript
import LocomotiveScroll from 'locomotive-scroll';  
  
const scroll = new LocomotiveScroll();  
```

--------------------------------

### Install Locomotive Scroll v4

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Installs version 4.1.4 of the Locomotive Scroll library using npm.

```bash
npm install locomotive-scroll@4.1.4  
```

--------------------------------

### autoStart Configuration

Source: https://scroll.locomotive.ca/docs/documentation/options

Explains the `autoStart` option, which controls whether the Request Animation Frame (RAF) starts automatically upon initialization.

```APIDOC
## POST /websites/scroll_locomotive_ca/auto-start

### Description
Configures the `autoStart` option to control the automatic starting of the Request Animation Frame (RAF) when Locomotive Scroll is initialized. Setting it to `false` allows for manual control over starting the RAF.

### Method
POST

### Endpoint
/websites/scroll_locomotive_ca/auto-start

### Parameters
#### Request Body
- **autoStart** (boolean) - Optional - Enable or disable the automatic starting of the RAF. Defaults to `true`.

### Request Example
```json
{
  "autoStart": false
}
```

### Manual Control Example
```javascript
// Initialize with autoStart set to false
const locomotiveScroll = new LocomotiveScroll({
    autoStart: false
});

// Manually start the RAF after a delay
setTimeout(() => {
    locomotiveScroll.start();
}, 2000);
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful configuration.

#### Response Example
```json
{
  "message": "autoStart configured successfully."
}
```
```

--------------------------------

### Custom Scroll Container Setup (v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows how to configure custom scroll containers in Locomotive Scroll v5 using `lenisOptions`. This allows for more flexible scrolling behavior compared to v4's full-page only scrolling.

```javascript
const scroll = new LocomotiveScroll({
    lenisOptions: {
        wrapper: document.querySelector('.scroll-container'),
        content: document.querySelector('.scroll-content'),
    },
});
```

--------------------------------

### v5 Progress Tracking using `data-scroll-event-progress` (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Provides an example of listening for the CustomEvent dispatched by `data-scroll-event-progress` in v5. It logs the progress detail of the event.

```javascript
window.addEventListener('heroProgress', (e) => {
    console.log(e.detail.progress); // 0 to 1
});
```

--------------------------------

### v5 Native CustomEvents for Scroll Calls (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Provides an example of listening for and handling native CustomEvents in v5. This code snippet shows how to play a video when a specific scroll event is triggered.

```javascript
window.addEventListener('videoTrigger', (e) => {
    const { target, way, from } = e.detail;
    // way: 'enter' | 'leave'
    // from: 'start' | 'end'

    if (way === 'enter') {
        target.querySelector('video').play();
    }
});
```

--------------------------------

### Install Locomotive Scroll via NPM

Source: https://scroll.locomotive.ca/docs/getting-started/installation

Installs the latest version of Locomotive Scroll using the Node Package Manager (NPM). This is the recommended method for integrating the library into your project.

```bash
npm install locomotive-scroll
```

--------------------------------

### Install Locomotive Scroll v5

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Installs the latest version of the Locomotive Scroll library using npm. This version is built on Lenis and offers improved performance and features.

```bash
npm install locomotive-scroll  
```

--------------------------------

### v4 Method Usage (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates the usage of methods like `update()`, `destroy()`, and `init()` in v4. Note that `update()` is renamed to `resize()` and `init()` is removed in v5.

```javascript
scroll.update();
scroll.destroy();
scroll.init(); // Reinitialize
```

--------------------------------

### Events & Callbacks (v4 vs v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Compares the event and callback mechanisms between v4 (ModularJS integration) and v5 (Native CustomEvents).

```APIDOC
## Events & Callbacks

### Description
This section contrasts the event and callback handling between v4 and v5, showing the shift from ModularJS integration to native CustomEvents.

### v4: ModularJS Integration
```html
<div data-scroll data-scroll-call="myMethod, MyModule">Trigger</div>
```
```javascript
scroll.on('call', (func) => {
    this.call(...func); // ModularJS
});
```

### v5: Native CustomEvents
```html
<div data-scroll data-scroll-call="videoTrigger">Trigger</div>
```
```javascript
window.addEventListener('videoTrigger', (e) => {
    const { target, way, from } = e.detail;
    // way: 'enter' | 'leave'
    // from: 'start' | 'end'

    if (way === 'enter') {
        target.querySelector('video').play();
    }
});
```

### Migration Tip
Replace all ModularJS `data-scroll-call` patterns with native CustomEvent listeners for simplicity and to remove dependencies.
```

--------------------------------

### Manually Start Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/methods

The `start()` method allows manual initiation of scrolling. This is useful when `autoStart` is set to `false`, providing programmatic control over when the scroll begins. It typically uses `requestAnimationFrame` for smooth activation.

```javascript
const locomotiveScroll = new LocomotiveScroll({ autoStart: false });

requestAnimationFrame(() => {
    locomotiveScroll.start();
});
```

--------------------------------

### Example HTML Structure for Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/getting-started/usage

A practical example demonstrating the HTML structure needed to implement scrollable content with Locomotive Scroll. It includes elements with `data-scroll` attributes for scroll effects.

```html
<main style="height: 150vh;">
    <div>
        <h1>Hello 👋</h1>
    </div>
    <div>
        <h2 data-scroll data-scroll-speed="0.5">What's up?</h2>
        <p data-scroll data-scroll-speed="0.8">😬</p>
    </div>
</main>
```

--------------------------------

### Scroll Events (v4 vs v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Illustrates how scroll events are handled in v4 and v5, showing the different callback structures.

```APIDOC
## Scroll Events

### Description
This section compares the handling of scroll events in v4 and v5, demonstrating the different callback signatures and available data.

### v4 Example
```javascript
scroll.on('scroll', (args) => {
    console.log(args.scroll.y);
    console.log(args.direction);
    console.log(args.speed);
});
```

### v5 Example
```javascript
const scroll = new LocomotiveScroll({
    scrollCallback: ({ scroll, velocity, direction, progress }) => {
        console.log(scroll); // Current scroll position
        console.log(velocity); // Scroll speed
        console.log(direction); // 1 (down/right), -1 (up/left), 0 (stopped)
        console.log(progress); // 0 to 1
    },
});
```
```

--------------------------------

### v5 Scroll Callback Configuration (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates how to configure a scroll callback in v5 using the `scrollCallback` option during initialization. This provides detailed scroll information.

```javascript
const scroll = new LocomotiveScroll({
    scrollCallback: ({ scroll, velocity, direction, progress }) => {
        console.log(scroll); // Current scroll position
        console.log(velocity); // Scroll speed
        console.log(direction); // 1 (down/right), -1 (up/left), 0 (stopped)
        console.log(progress); // 0 to 1
    },
});
```

--------------------------------

### Control RAF Starting with Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/options

The autoStart option determines whether the Request Animation Frame (RAF) starts automatically upon initialization of Locomotive Scroll. Setting it to `false` allows for manual control over when the RAF begins, which can be useful for synchronizing animations or delaying the start.

```javascript
const locomotiveScroll = new LocomotiveScroll({
    autoStart: false,
});

// Manually start the RAF
setTimeout(() => {
    locomotiveScroll.start();
}, 2000)
```

--------------------------------

### Locomotive Scroll v5 Instance Options Equivalent

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates initializing Locomotive Scroll v5 with equivalent options mapped to Lenis. It shows how to configure Lenis options and access Lenis instance properties like direction and velocity.

```javascript
const scroll = new LocomotiveScroll({  
    lenisOptions: {  
        orientation: 'vertical',  
        lerp: 0.1,  
        wheelMultiplier: 1,  
    },  
});  
  
// Access Lenis directly for more control  
console.log(scroll.lenisInstance.direction); // Get direction  
console.log(scroll.lenisInstance.velocity); // Get speed  
```

--------------------------------

### HTML Structure for Locomotive Scroll v5

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Example HTML structure using data attributes for Locomotive Scroll v5. Attributes like `data-scroll`, `data-scroll-speed`, and `data-scroll-event-progress` are used to configure scroll behavior.

```html
<main>
    <h1 data-scroll data-scroll-event-progress="heroProgress">Hero</h1>
    <div data-scroll data-scroll-speed="2">Parallax</div>
    <div data-scroll data-scroll-call="videoPlay">Video</div>
    <div class="sticky">Sticky</div>
    <div>End</div>
</main>
```

--------------------------------

### Locomotive Scroll v5 Initialization and Control

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates basic v5 scroll instance control, including resizing and destruction. Initialization is now done by creating a new instance, replacing the older `init()` method.

```javascript
scroll.resize(); // Rarely needed (auto-synced with Lenis)
scroll.destroy();
// No init() - create new instance instead
```

--------------------------------

### JavaScript Initialization and Event Handling for Locomotive Scroll v5

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates initializing Locomotive Scroll v5 with custom options and handling scroll events like progress tracking and video playback. It uses native CustomEvents for callbacks.

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

const scroll = new LocomotiveScroll({
    lenisOptions: {
        orientation: 'vertical',
        lerp: 0.1,
    },
    scrollCallback: ({ scroll, velocity, direction, progress }) => {
        // Global scroll callback if needed
    },
});

// Progress tracking
window.addEventListener('heroProgress', (e) => {
    console.log(e.detail.progress);
});

// Video callback
window.addEventListener('videoPlay', (e) => {
    const { target, way } = e.detail;
    if (way === 'enter') {
        target.querySelector('video').play();
    }
});
```

--------------------------------

### v5 Progress Tracking using `data-scroll-event-progress` (HTML)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates how to enable progress tracking via CustomEvents in v5 using the `data-scroll-event-progress` attribute. This allows for event-driven progress updates.

```html
<h1 data-scroll data-scroll-event-progress="heroProgress">Hero</h1>
```

--------------------------------

### v4 ModularJS Integration for Scroll Calls (HTML)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows how to trigger methods in v4 using the `data-scroll-call` attribute, integrating with ModularJS. This approach is replaced by native CustomEvents in v5.

```html
<div data-scroll data-scroll-call="myMethod, MyModule">Trigger</div>
```

--------------------------------

### New Attributes

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Explains new attributes for scroll behavior, including CSS progress variables, custom event progress, and touch speed enablement.

```APIDOC
## New Attributes

### Description
These attributes enhance scroll behavior by providing CSS variables for progress, emitting custom events for progress tracking, and enabling touch speed for parallax on mobile devices.

### Attributes
- **`data-scroll-css-progress`** (boolean) - Adds `--progress` CSS variable (0-1) to the element.
- **`data-scroll-event-progress`** (string) - Emits progress via CustomEvent with the specified event name (e.g., `heroProgress`).
- **`data-scroll-enable-touch-speed`** (boolean) - Enables parallax on touch devices.
```

--------------------------------

### Progress Tracking (v4 vs v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Explains how scroll progress is tracked in v4 using `data-scroll-id` and in v5 using CustomEvents or CSS variables.

```APIDOC
## Progress Tracking

### Description
This section details the methods for tracking scroll progress, comparing v4's `data-scroll-id` approach with v5's `data-scroll-event-progress` CustomEvents and `data-scroll-css-progress` CSS variables.

### v4: Using `data-scroll-id`
```html
<h1 data-scroll data-scroll-id="hero">Hero</h1>
```
```javascript
scroll.on('scroll', (args) => {
    if (args.currentElements['hero']) {
        let progress = args.currentElements['hero'].progress;
        console.log(progress); // 0 to 1
    }
});
```

### v5: Using Progress Events
```html
<h1 data-scroll data-scroll-event-progress="heroProgress">Hero</h1>
```
```javascript
window.addEventListener('heroProgress', (e) => {
    console.log(e.detail.progress); // 0 to 1
});
```

### v5: Using CSS Variables
```html
<h1 data-scroll data-scroll-css-progress>Hero</h1>
```
```css
[data-scroll-css-progress] {
    opacity: calc(var(--progress) * 1);
    transform: translateY(calc((1 - var(--progress)) * 100px));
}
```
```

--------------------------------

### v5 Native CustomEvents for Scroll Calls (HTML)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates how to trigger native CustomEvents in v5 using the `data-scroll-call` attribute. This replaces the v4 ModularJS integration.

```html
<div data-scroll data-scroll-call="videoTrigger">Trigger</div>
```

--------------------------------

### Parallax (v4 vs v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Details the parallax implementation in v4 and v5, including changes in touch device handling and speed calculation.

```APIDOC
## Parallax

### Description
This section details the parallax implementation, highlighting key differences between v4 and v5, particularly regarding touch device support and the redesigned speed calculation.

### v4 Example
```html
<div data-scroll data-scroll-speed="2">Fast parallax</div>
```

### v5 Example
```html
<!-- Parallax disabled on touch by default -->
<div data-scroll data-scroll-speed=".5">Fast parallax (desktop only)</div>

<!-- Enable on touch devices -->
<div data-scroll data-scroll-speed=".5" data-scroll-enable-touch-speed>
    Fast parallax (all devices)
</div>
```

### Key Changes in v5
1. **Touch Device Handling**: Parallax is automatically disabled on touch devices in v5 to use native scrolling. Use `data-scroll-enable-touch-speed` to override this.
2. **Speed Calculation**: Speed calculation is completely redesigned in v5, based on scroll container size, not arbitrary values.

### How `data-scroll-speed` Works in v5
- **Formula:** `translateValue = progress × containerSize × speed × -1`
- `containerSize`: Height (vertical) or width (horizontal) of the scroll container.
- `progress`: Ranges from -1 to 1 for normal elements, and 0 to 1 for elements visible on page load.

**Examples with `data-scroll-speed="1"` (vertical scrolling):**
- **Normal element**: Moves from `+containerHeight` to `-containerHeight`.
- **In-fold element**: Moves from `0` to `-containerHeight`.

**Migration Tip**: Start with smaller v5 speed values (0.1 to 0.5) and adjust based on container size and viewport.
```

--------------------------------

### v5 Progress Tracking using CSS Variables (CSS)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Illustrates how to use the `--progress` CSS variable, automatically set by `data-scroll-css-progress` in v5, to style elements based on their scroll progress.

```css
[data-scroll-css-progress] {
    opacity: calc(var(--progress) * 1);
    transform: translateY(calc((1 - var(--progress)) * 100px));
}
```

--------------------------------

### CSS for Sticky Elements (v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Provides the CSS required for implementing sticky elements in v5 using the native `position: sticky` property. This approach is performant and requires no JavaScript.

```css
.sticky-element {
    position: sticky;
    top: 0;
}
```

--------------------------------

### v5 Progress Tracking using CSS Variables (HTML)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows how to enable progress tracking via CSS variables in v5 using the `data-scroll-css-progress` attribute. This allows for direct styling based on scroll progress.

```html
<h1 data-scroll data-scroll-css-progress>Hero</h1>
```

--------------------------------

### v4 Performance Optimization Pattern

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates a performance optimization technique used in v4 by splitting content into sections using `data-scroll-container` and `data-scroll-section` attributes. This helped in managing scroll events and rendering.

```html
<!-- Recommended: Split into sections for better performance -->
<div data-scroll-container>
    <div data-scroll-section>
        <!-- Content here -->
    </div>
    <div data-scroll-section>
        <!-- More content -->
    </div>
</div>
```

--------------------------------

### v4 ModularJS Integration for Scroll Calls (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Illustrates the JavaScript code in v4 that handles scroll call events, specifically for integrating with ModularJS. This functionality is deprecated in v5.

```javascript
scroll.on('call', (func) => {
    this.call(...func); // ModularJS
});
```

--------------------------------

### v4 Scroll Event Listener (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows how to listen for generic scroll events in v4 and access scroll position, direction, and speed. This is replaced by a more structured callback in v5.

```javascript
scroll.on('scroll', (args) => {
    console.log(args.scroll.y);
    console.log(args.direction);
    console.log(args.speed);
});
```

--------------------------------

### Sticky Element Implementation (v4 vs v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Compares the implementation of sticky elements between v4 and v5. v4 used a custom `data-scroll-sticky` attribute, while v5 recommends using native CSS `position: sticky` for better performance and simplicity.

```html
<div data-scroll data-scroll-sticky data-scroll-target="#target">
    Sticky element
</div>

<div id="target">Target</div>
```

```html
<div class="sticky-element">Sticky element</div>
```

--------------------------------

### Set Scroll Position Trigger with data-scroll-position

Source: https://scroll.locomotive.ca/docs/documentation/attributes

The `data-scroll-position` attribute defines when an element triggers its in-view state relative to the scroll container. It accepts two values (e.g., 'start,end') for entry and exit points, using keywords like 'start', 'middle', or 'end'.

```html
<div data-scroll data-scroll-position="start, start"></div>
```

--------------------------------

### v4 Progress Tracking using `data-scroll-id` (HTML)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Illustrates how to track element scroll progress in v4 using the `data-scroll-id` attribute. This method is superseded by CustomEvents and CSS variables in v5.

```html
<h1 data-scroll data-scroll-id="hero">Hero</h1>
```

--------------------------------

### HTML Structure for Custom Scroll Containers (v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Illustrates the HTML structure needed to implement custom scroll containers in v5. It requires a wrapper element with overflow hidden and a content element inside.

```html
<div class="scroll-container" style="height: 100vh; overflow: hidden;">
    <div class="scroll-content">
        <div data-scroll data-scroll-speed="0.5">Parallax works here too!</div>
    </div>
</div>
```

--------------------------------

### Parallax Configuration in v5 (HTML)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Demonstrates how to configure parallax scrolling in Locomotive Scroll v5 using HTML attributes. It shows the default behavior (disabled on touch) and how to enable it using `data-scroll-enable-touch-speed`.

```html
<div data-scroll data-scroll-speed="2">Fast parallax</div>
```

```html
<!-- Parallax disabled on touch by default -->
<div data-scroll data-scroll-speed=".5">Fast parallax (desktop only)</div>

<!-- Enable on touch devices -->
<div data-scroll data-scroll-speed=".5" data-scroll-enable-touch-speed>
    Fast parallax (all devices)
</div>
```

--------------------------------

### v4 Progress Tracking using `data-scroll-id` (JavaScript)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Shows the JavaScript code in v4 for accessing the scroll progress of an element identified by `data-scroll-id`. This is replaced by more direct event-based tracking in v5.

```javascript
scroll.on('scroll', (args) => {
    if (args.currentElements['hero']) {
        let progress = args.currentElements['hero'].progress;
        console.log(progress); // 0 to 1
    }
});
```

--------------------------------

### CSS for Sticky Elements in Locomotive Scroll v5

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Basic CSS to enable sticky positioning for elements within Locomotive Scroll v5. This replaces the older `data-scroll-sticky` attribute with standard CSS.

```css
.sticky {
    position: sticky;
    top: 0;
}
```

--------------------------------

### Parallax Calculation Formula (v5)

Source: https://scroll.locomotive.ca/docs/extras/migration-guide

Explains the formula used in Locomotive Scroll v5 for calculating parallax translation values. It defines the variables involved, including progress, container size, and speed.

```text
translateValue = progress × containerSize × speed × -1

Where:
  * containerSize = Height (vertical) or width (horizontal) of Lenis scroll container
  * progress ranges from -1 to 1 for normal elements
  * progress ranges from 0 to 1 for elements visible on page load (in fold)
```

--------------------------------

### HTML Structure for Custom Scroll Container

Source: https://scroll.locomotive.ca/docs/documentation/options

This HTML structure demonstrates how to set up a custom scroll container for Locomotive Scroll. The wrapper element requires a fixed height and `overflow: hidden` (or `auto`/`scroll`). The content element must be a direct child of the wrapper. Intersection Observers and Resize detection will automatically synchronize with this setup.

```html
<div class="scroll-container" style="height: 100vh; overflow: hidden;">
    <div class="scroll-content">
        <div data-scroll data-scroll-speed="0.5">Parallax element</div>
    </div>
</div>
```

--------------------------------

### Locomotive Scroll Initialization with lenisOptions

Source: https://scroll.locomotive.ca/docs/documentation/options

Demonstrates how to initialize Locomotive Scroll with detailed Lenis options for fine-grained control over scrolling behavior.

```APIDOC
## POST /websites/scroll_locomotive_ca

### Description
Initializes Locomotive Scroll with customizable Lenis options to control scrolling behavior, such as wrapper, content, lerp, duration, orientation, and more.

### Method
POST

### Endpoint
/websites/scroll_locomotive_ca

### Parameters
#### Request Body
- **lenisOptions** (object) - Optional - An object to configure Lenis instance settings.
  - **wrapper** (HTMLElement|Window) - Optional - The element to use as the scroll container. Defaults to `window`.
  - **content** (HTMLElement) - Optional - The element containing the scrollable content. Defaults to `document.documentElement`.
  - **lerp** (number) - Optional - The intensity of linear interpolation between frames (0 to 1). Defaults to 0.1.
  - **duration** (number) - Optional - The duration of the animation. Defaults to 1.2.
  - **orientation** (string) - Optional - The scrolling orientation ('vertical' or 'horizontal'). Defaults to 'vertical'.
  - **gestureOrientation** (string) - Optional - The orientation of gestures ('vertical', 'horizontal', or 'both'). Defaults to 'vertical'.
  - **smoothWheel** (boolean) - Optional - Enable smooth scrolling for mouse wheel events. Defaults to true.
  - **smoothTouch** (boolean) - Optional - Enable smooth scrolling for touch events. Defaults to false.
  - **wheelMultiplier** (number) - Optional - Multiplier for mouse wheel events. Defaults to 1.
  - **touchMultiplier** (number) - Optional - Multiplier for touch events. Defaults to 2.
  - **normalizeWheel** (boolean) - Optional - Normalize wheel inputs across browsers. Defaults to true.
  - **easing** (function) - Optional - A function defining the rate of change for values.

### Request Example
```json
{
  "lenisOptions": {
    "wrapper": window,
    "content": document.documentElement,
    "lerp": 0.1,
    "duration": 1.2,
    "orientation": "vertical",
    "gestureOrientation": "vertical",
    "smoothWheel": true,
    "smoothTouch": false,
    "wheelMultiplier": 1,
    "touchMultiplier": 2,
    "normalizeWheel": true,
    "easing": "(t) => Math.min(1, 1.001 - Math.pow(2, -10 * t))"
  }
}
```

### Response
#### Success Response (200)
- **instance** (object) - The initialized Locomotive Scroll instance.

#### Response Example
```json
{
  "message": "Locomotive Scroll initialized successfully."
}
```
```

--------------------------------

### Initialize Locomotive Scroll with Bundler (Javascript)

Source: https://scroll.locomotive.ca/docs/getting-started/usage

Demonstrates how to import and initialize Locomotive Scroll when using a Javascript bundler like Webpack or Rollup. This is the recommended approach for modern Javascript projects.

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

const locomotiveScroll = new LocomotiveScroll();
```

--------------------------------

### Initialize Locomotive Scroll Without Bundler (Javascript)

Source: https://scroll.locomotive.ca/docs/getting-started/usage

Shows how to include and initialize Locomotive Scroll using a CDN link for direct script inclusion in HTML. This method is suitable for projects that do not use a Javascript bundler.

```html
<script src="https://cdn.jsdelivr.net/npm/locomotive-scroll/bundled/locomotive-scroll.min.js"></script>
<script>
    const locomotiveScroll = new LocomotiveScroll();
</script>
```

--------------------------------

### Configure Lenis Instance Settings with Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/options

The lenisOptions parameter allows detailed configuration of Lenis's instance settings. This includes specifying the scroll wrapper and content elements, lerp intensity, animation duration, orientation, gesture orientation, and various smoothing and multiplier options for wheel and touch events. It also supports custom easing functions.

```javascript
const locomotiveScroll = new LocomotiveScroll({
    lenisOptions: {
        wrapper: window,
        content: document.documentElement,
        lerp: 0.1,
        duration: 1.2,
        orientation: 'vertical',
        gestureOrientation: 'vertical',
        smoothWheel: true,
        smoothTouch: false,
        wheelMultiplier: 1,
        touchMultiplier: 2,
        normalizeWheel: true,
        easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
    },
});
```

```javascript
const locomotiveScroll = new LocomotiveScroll({
    lenisOptions: {
        wrapper: document.querySelector('.scroll-container'),
        content: document.querySelector('.scroll-content'),
    },
});
```

--------------------------------

### Include Essential Locomotive Scroll Styles (CSS)

Source: https://scroll.locomotive.ca/docs/getting-started/usage

Provides instructions for adding the base styles required for Locomotive Scroll. This can be done by importing the CSS file or linking to the bundled CSS via CDN.

```css
@import 'locomotive-scroll/dist/locomotive-scroll.css';
```

```html
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/locomotive-scroll/bundled/locomotive-scroll.css"
/>
```

--------------------------------

### Initialize Custom Ticker with Locomotive Scroll and GSAP

Source: https://scroll.locomotive.ca/docs/documentation/options

Allows the initialization of an external ticker, such as GSAP's ticker, to manage animations instead of Locomotive Scroll's default request animation frame. Requires a corresponding `destroyCustomTicker` function.

```javascript
import LocomotiveScroll from 'locomotive-scroll';  
import { gsap } from 'gsap/all';  
  
const locomotiveScroll = new LocomotiveScroll({  
    initCustomTicker: (render) => {  
        gsap.ticker.add(render);  
    },  
    destroyCustomTicker: (render) => {  
        gsap.ticker.remove(render);  
    },  
});  
```

--------------------------------

### initCustomTicker and destroyCustomTicker

Source: https://scroll.locomotive.ca/docs/documentation/options

These options allow you to integrate an external ticker (like GSAP's ticker) instead of Locomotive Scroll's default request animation frame, providing more control over the animation loop.

```APIDOC
## initCustomTicker & destroyCustomTicker

### Description
_(Optional)_ `initCustomTicker` specifies a callback function to initialize an external ticker. `destroyCustomTicker` specifies a callback function to destroy an external ticker. This allows overriding Locomotive Scroll's default request animation frame.

### Method
Configuration Options

### Parameters
#### Request Body
- **initCustomTicker** (function) - Optional - A function to initialize the custom ticker. It receives a `render` function as an argument.
- **destroyCustomTicker** (function) - Optional - A function to destroy the custom ticker. It receives the `render` function as an argument.

### Request Example
```javascript
import LocomotiveScroll from 'locomotive-scroll';
import { gsap } from 'gsap/all';

const locomotiveScroll = new LocomotiveScroll({
    initCustomTicker: (render) => {
        gsap.ticker.add(render);
    },
    destroyCustomTicker: (render) => {
        gsap.ticker.remove(render);
    },
});
```

### Response
#### Success Response (N/A)
These are configuration options, not endpoints that return a response.

#### Response Example
N/A
```

--------------------------------

### Sass Import for Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/getting-started/usage

Illustrates how to import Locomotive Scroll styles using Sass, allowing for better organization and customization within Sass projects. This method assumes you have Sass set up in your project.

```sass
// Vendors
@import 'node_modules/locomotive-scroll/dist/locomotive-scroll';
```

--------------------------------

### Custom Scroll Container Configuration

Source: https://scroll.locomotive.ca/docs/documentation/options

Illustrates how to configure Locomotive Scroll to use a custom scroll container instead of the default full-page scroll.

```APIDOC
## POST /websites/scroll_locomotive_ca/custom-container

### Description
Initializes Locomotive Scroll using a custom scroll container and content element, allowing for contained scrolling experiences.

### Method
POST

### Endpoint
/websites/scroll_locomotive_ca/custom-container

### Parameters
#### Request Body
- **lenisOptions** (object) - Required - An object containing `wrapper` and `content` properties for custom container setup.
  - **wrapper** (HTMLElement) - Required - The element to be used as the scroll container. Must have a fixed height and `overflow: hidden`.
  - **content** (HTMLElement) - Required - The direct child element of the wrapper that contains the scrollable content.

### Request Example
```json
{
  "lenisOptions": {
    "wrapper": "document.querySelector('.scroll-container')",
    "content": "document.querySelector('.scroll-content')"
  }
}
```

### HTML Structure Example
```html
<div class="scroll-container" style="height: 100vh; overflow: hidden;">
    <div class="scroll-content">
        <div data-scroll data-scroll-speed="0.5">Parallax element</div>
    </div>
</div>
```

### Requirements
- The `wrapper` element must have a fixed height and `overflow: hidden` (or `auto`/`scroll`).
- The `content` element must be a direct child of the `wrapper`.
- Intersection Observers will automatically use the `wrapper` as their root.
- Resize detection is automatically synchronized with Lenis's ResizeObservers.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful initialization.

#### Response Example
```json
{
  "message": "Locomotive Scroll initialized with custom container."
}
```
```

--------------------------------

### triggerRootMargin Configuration

Source: https://scroll.locomotive.ca/docs/documentation/options

Explains how to configure the `triggerRootMargin` option for IntersectionObserver, affecting when scroll elements are triggered.

```APIDOC
## POST /websites/scroll_locomotive_ca/trigger-root-margin

### Description
Configures the `triggerRootMargin` option for the IntersectionObserver, which defines the margin around the root element used for triggering scroll events.

### Method
POST

### Endpoint
/websites/scroll_locomotive_ca/trigger-root-margin

### Parameters
#### Request Body
- **triggerRootMargin** (string) - Optional - Specifies the root margin for scroll elements. Defaults to `'-1px -1px -1px -1px'`.

### Request Example
```json
{
  "triggerRootMargin": "-1px -1px -1px -1px"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful configuration.

#### Response Example
```json
{
  "message": "triggerRootMargin configured successfully."
}
```
```

--------------------------------

### Prevent Scroll Smoothing for Injected Popups with Lenis

Source: https://scroll.locomotive.ca/docs/extras/limitations

Demonstrates how to prevent scroll smoothing for dynamically injected popups using Lenis's 'prevent' option. This is useful when the 'data-lenis-prevent' attribute cannot be applied directly to the DOM element.

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

const locomotiveScroll = new LocomotiveScroll({
    lenisOptions: {
        prevent: (node) => node.getAttribute('id') === 'modalSelector',
    },
});
```

--------------------------------

### Scroll to Target with Options using Locomotive Scroll (JavaScript)

Source: https://scroll.locomotive.ca/docs/documentation/methods

This snippet demonstrates how to use the scrollTo method from Locomotive Scroll to programmatically scroll to a target element. It shows the import, initialization, and invocation of the scrollTo method with a target and an empty options object. This method is useful for creating custom navigation or scroll-triggered animations.

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

const locomotiveScroll = new LocomotiveScroll();
const $target = document.getElementById('jsTarget');

function scrollTo(params) {
    const { target, options } = params;
    locomotiveScroll.scrollTo(target, options);
}

scrollTo({ target: $target, options: {} });
```

--------------------------------

### rafRootMargin Configuration

Source: https://scroll.locomotive.ca/docs/documentation/options

Details the `rafRootMargin` option, which specifies the root margin for scroll elements triggered by RequestAnimationFrame.

```APIDOC
## POST /websites/scroll_locomotive_ca/raf-root-margin

### Description
Configures the `rafRootMargin` option, which specifies the root margin for scroll elements triggered by RequestAnimationFrame. This is relevant for elements with specific data attributes like `data-scroll-offset` or `data-scroll-speed`.

### Method
POST

### Endpoint
/websites/scroll_locomotive_ca/raf-root-margin

### Parameters
#### Request Body
- **rafRootMargin** (string) - Optional - Specifies the root margin for RequestAnimationFrame-based triggers. Defaults to `'100% 100% 100% 100%'`.

### Request Example
```json
{
  "rafRootMargin": "100% 100% 100% 100%"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful configuration.

#### Response Example
```json
{
  "message": "rafRootMargin configured successfully."
}
```
```

--------------------------------

### Implement Scroll Callback with Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/options

Defines a callback function to receive scroll-related data such as scroll position, limits, velocity, direction, and progress. This leverages Locomotive Scroll's built-in scroll callback feature.

```javascript
import LocomotiveScroll from 'locomotive-scroll';  
  
function onScroll({ scroll, limit, velocity, direction, progress }) {  
    console.log(scroll, limit, velocity, direction, progress);  
}  
  
const locomotiveScroll = new LocomotiveScroll({  
    scrollCallback: onScroll,  
});  
```

--------------------------------

### Manually Trigger Resize in Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/methods

The `resize()` method manually triggers the resize callback for the Locomotive Scroll instance. This is useful for updating scroll calculations after dynamic layout changes that might not be automatically detected.

```javascript
const locomotiveScroll = new LocomotiveScroll();
locomotiveScroll.resize();
```

--------------------------------

### Apply CSS for Horizontal Scrolling with Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/getting-started/usage

Details the specific CSS rules necessary when utilizing the horizontal scrolling feature of Locomotive Scroll. These styles ensure correct layout and behavior for horizontal content.

```css
/* Only necessary with horizontal scrolling */
html[data-scroll-orientation='horizontal'] {
    body {
        width: fit-content;
    }
    [data-scroll-container] {
        display: flex;
    }
}
```

--------------------------------

### Add Scroll Elements Dynamically

Source: https://scroll.locomotive.ca/docs/documentation/methods

The `addScrollElements($newContainer)` method observes scroll elements within a provided container. This is crucial for dynamic content loading (e.g., Ajax) to ensure new elements are correctly integrated into the scroll tracking.

```javascript
const locomotiveScroll = new LocomotiveScroll();
const $newContainer = document.getElementById('containerToAdd');

locomotiveScroll.addScrollElements($newContainer);
```

--------------------------------

### scrollCallback

Source: https://scroll.locomotive.ca/docs/documentation/options

Allows you to specify a callback function that is executed during scroll events. This function receives scroll-related data and can be used to trigger custom animations or logic.

```APIDOC
## scrollCallback

### Description
_(Optional)_ Specifies a callback function that can return an object with the following properties: `{ scroll, limit, velocity, direction, progress }`. This functionality is made possible by Lenis's scroll callback feature.

### Method
Configuration Option

### Parameters
#### Request Body
- **scrollCallback** (function) - Optional - A function that will be called on scroll. It receives an object with scroll properties.

### Request Example
```javascript
import LocomotiveScroll from 'locomotive-scroll';

function onScroll({ scroll, limit, velocity, direction, progress }) {
    console.log(scroll, limit, velocity, direction, progress);
}

const locomotiveScroll = new LocomotiveScroll({
    scrollCallback: onScroll,
});
```

### Response
#### Success Response (N/A)
This is a configuration option, not an endpoint that returns a response.

#### Response Example
N/A
```

--------------------------------

### Listen for Custom Scroll Events in JavaScript

Source: https://scroll.locomotive.ca/docs/documentation/attributes

This JavaScript code demonstrates how to listen for a custom scroll event triggered by the `data-scroll-call` attribute. It logs the target element, scroll direction ('way'), and scroll position ('from') to the console.

```javascript
window.addEventListener('scrollEvent', (e) => {
    const { target, way, from } = e.detail;
    console.log(`target: ${target}`, `way: ${way}`, `from: ${from}`);
});

```

--------------------------------

### Configure RAF Root Margin for Scroll Elements with Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/options

The rafRootMargin option defines the root margin for scroll elements that are triggered based on a RequestAnimationFrame. This is particularly relevant for elements with attributes like `data-scroll-offset`, `data-scroll-position`, `data-scroll-css-progress`, `data-scroll-event-progress`, or `data-scroll-speed`.

```javascript
const locomotiveScroll = new LocomotiveScroll({
    rafRootMargin: '100% 100% 100% 100%',
});
```

--------------------------------

### scrollTo(target, options)

Source: https://scroll.locomotive.ca/docs/documentation/methods

The scrollTo method allows you to programmatically scroll to a specific target on the page with various configuration options for smooth scrolling behavior.

```APIDOC
## scrollTo(target, options)

### Description
Allows you to scroll to a specific target on the page. This method provides smooth scrolling with customizable options.

### Method
`scrollTo`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **target** (number / HTMLElement / string) - Optional - The target to scroll to. Can be a scroll position (number), a DOM element (HTMLElement), or a CSS selector/keyword (string like 'top', 'left', 'bottom', 'right', 'start', 'end').
* **options** (ILenisScrollToOptions) - Optional - An object configuring the scroll behavior. Available options include:
    * **offset** (number) - Specifies an offset from the top of the target element.
    * **lerp** (number) - Controls the intensity of the scroll animation.
    * **duration** (number) - The duration of the scroll animation in seconds.
    * **immediate** (boolean) - If true, scrolls immediately, ignoring duration and easing.
    * **lock** (boolean) - Prevents user scrolling until the target is reached.
    * **force** (boolean) - Forces scrolling to the target even if the instance is stopped.
    * **onComplete** (function) - A callback function executed when the target is reached.
    * **easing** (function) - A function defining the easing curve for the scroll animation.

### Request Example
```javascript
import LocomotiveScroll from 'locomotive-scroll';

const locomotiveScroll = new LocomotiveScroll();
const $target = document.getElementById('jsTarget');

locomotiveScroll.scrollTo($target, {
    offset: 0,
    lerp: 0.1,
    duration: 1,
    easing: (t) => Math.min(1, t * 2), // Example easing function
    onComplete: () => {
        console.log('Scroll complete!');
    }
});
```

### Response
#### Success Response (200)
This method does not return a value directly but performs a scroll action.

#### Response Example
N/A
```

--------------------------------

### Destroy Locomotive Scroll Instance

Source: https://scroll.locomotive.ca/docs/documentation/methods

The `destroy()` method cleans up the Locomotive Scroll instance and removes associated event listeners. It's useful for removing scroll functionality from an element or completely uninitializing the instance.

```javascript
const locomotiveScroll = new LocomotiveScroll();
locomotiveScroll.destroy();
```

--------------------------------

### Configure Intersection Observer Root Margin with Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/options

The triggerRootMargin option allows you to specify the root margin for scroll elements that are triggered by the IntersectionObserver. This affects when elements are considered 'visible' or 'intersecting'.

```javascript
const locomotiveScroll = new LocomotiveScroll({
    triggerRootMargin: '-1px -1px -1px -1px',
});
```

--------------------------------

### Manually Stop Locomotive Scroll

Source: https://scroll.locomotive.ca/docs/documentation/methods

The `stop()` method halts the scroll motion. This method is used to programmatically pause the scrolling behavior, often within an animation frame for a smooth transition.

```javascript
const locomotiveScroll = new LocomotiveScroll();

requestAnimationFrame(() => {
    locomotiveScroll.stop();
});
```

--------------------------------

### Configure Scroll Offset Trigger with data-scroll-offset

Source: https://scroll.locomotive.ca/docs/documentation/attributes

The `data-scroll-offset` attribute specifies custom offsets for when an element triggers its in-view state. It accepts pixel or percentage values (e.g., '400, 50%') for entry and exit points, relative to the viewport height.

```html
<div data-scroll data-scroll-offset="400, 200"></div>
```

--------------------------------

### Enable Repeating In-View Detection with data-scroll-repeat

Source: https://scroll.locomotive.ca/docs/documentation/attributes

The `data-scroll-repeat` attribute is a boolean attribute that, when present, enables the in-view detection to repeat for an element. By default, detection does not repeat, meaning an element's in-view state is only registered once.

```html
<div data-scroll data-scroll-repeat></div>
```
Tokens:
Raw