/locomotive-scroll

Locomotive Scroll API Reference

Complete API documentation for Locomotive Scroll.

Table of Contents

• Constructor Options
• Data Attributes
• Instance Methods
• Events
• Properties

Constructor Options

new LocomotiveScroll(options)

Global Options

Mobile/Tablet Options

{
  tablet: {
    smooth: boolean,
    direction: string,
    gestureDirection: string,
    breakpoint: number  // Default: 1024
  },
  smartphone: {
    smooth: boolean,
    direction: string,
    gestureDirection: string,
    breakpoint: number  // Default: 767
  }
}

Example:

new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  tablet: {
    smooth: true,
    breakpoint: 1024
  },
  smartphone: {
    smooth: false,
    breakpoint: 768
  }
});

Data Attributes

Container Attributes

Example:

<div data-scroll-container>
  <div data-scroll-section>
    <!-- Content -->
  </div>
</div>

Element Attributes

Detailed Attribute Explanations

data-scroll-speed

Controls parallax intensity:

• Positive values: Element moves faster than scroll
• Negative values: Element moves in opposite direction
• 0-1: Element moves slower than scroll
• > 1: Element moves faster than scroll

<!-- Background layer (slow) -->
<div data-scroll data-scroll-speed="0.5">Slow</div>

<!-- Normal speed -->
<div data-scroll data-scroll-speed="1">Normal</div>

<!-- Foreground layer (fast) -->
<div data-scroll data-scroll-speed="3">Fast</div>

<!-- Reverse -->
<div data-scroll data-scroll-speed="-2">Reverse</div>

data-scroll-direction

Axis for parallax effect:

<!-- Vertical parallax (default) -->
<div data-scroll data-scroll-speed="2" data-scroll-direction="vertical">V</div>

<!-- Horizontal parallax -->
<div data-scroll data-scroll-speed="2" data-scroll-direction="horizontal">H</div>

data-scroll-offset

Custom trigger point:

<!-- Trigger when element is 20% from bottom -->
<div data-scroll data-scroll-offset="20%">Offset %</div>

<!-- Trigger 100px from bottom -->
<div data-scroll data-scroll-offset="100">Offset px</div>

<!-- Different bottom/top offsets -->
<div data-scroll data-scroll-offset="10%,30%">Custom offsets</div>

data-scroll-sticky

Pin element within boundaries:

<!-- Sticky within section -->
<div data-scroll-section>
  <div data-scroll data-scroll-sticky>
    Sticks within section
  </div>
</div>

<!-- Sticky with custom target -->
<div id="container">
  <div data-scroll data-scroll-sticky data-scroll-target="#container">
    Sticks within #container
  </div>
</div>

data-scroll-call

Trigger callback when in view:

<div data-scroll data-scroll-call="myFunction">
  Triggers 'myFunction' when visible
</div>

scroll.on('call', (func, way, obj) => {
  if (func === 'myFunction') {
    console.log('Element is', way); // 'enter' or 'exit'
  }
});

data-scroll-repeat

Re-trigger detection on each scroll:

<!-- Fires once (default) -->
<div data-scroll>Fires once</div>

<!-- Fires every time -->
<div data-scroll data-scroll-repeat>Fires repeatedly</div>

Instance Methods

init()

Reinitialize scroll instance.

scroll.init();

update()

Recalculate element positions. Call after DOM changes.

// After adding content
addContent();
scroll.update();

destroy()

Remove event listeners and clean up. Essential for SPAs.

scroll.destroy();

start()

Resume scrolling after stop().

scroll.start();

stop()

Pause scrolling (disable smooth scroll).

scroll.stop();

scrollTo(target, options)

Programmatically scroll to target.

Parameters:

• target: Can be:

  • 'top' - Scroll to top
  • 'bottom' - Scroll to bottom
  • number - Pixel value
  • string - CSS selector
  • HTMLElement - DOM element

• options (optional):

  {
    offset: number,           // Offset in pixels (default: 0)
    callback: function,       // Callback after scroll
    duration: number,         // Duration in ms (default: 1000)
    easing: [n,n,n,n],       // Cubic bezier array (default: [0.25, 0.00, 0.35, 1.00])
    disableLerp: boolean,    // Disable smooth lerp (default: false)
    onComplete: function     // Same as callback
  }

Examples:

// Scroll to top
scroll.scrollTo('top');

// Scroll to element
scroll.scrollTo('#section');

// Scroll to pixel value
scroll.scrollTo(500);

// Scroll with options
scroll.scrollTo('#section', {
  offset: -100,
  duration: 2000,
  easing: [0.25, 0.0, 0.35, 1.0],
  callback: () => console.log('Done!')
});

// Instant scroll (no smooth)
scroll.scrollTo('#section', {
  disableLerp: true
});

setScroll(x, y)

Set scroll position instantly without animation.

scroll.setScroll(0, 500); // x, y

on(event, callback)

Add event listener.

scroll.on('scroll', (args) => {
  console.log(args);
});

off(event, callback)

Remove event listener.

const handler = (args) => console.log(args);
scroll.on('scroll', handler);
scroll.off('scroll', handler);

Events

scroll

Fires on scroll. Receives object with:

scroll.on('scroll', (args) => {
  // Scroll position
  console.log(args.scroll.x);     // Horizontal scroll
  console.log(args.scroll.y);     // Vertical scroll

  // Scroll limits
  console.log(args.limit.x);      // Max horizontal scroll
  console.log(args.limit.y);      // Max vertical scroll

  // Speed (if getSpeed: true)
  console.log(args.speed);

  // Direction (if getDirection: true)
  console.log(args.direction);    // 'up', 'down', 'left', 'right'

  // Current in-view elements
  console.log(args.currentElements);

  // Access specific element
  if (args.currentElements['hero']) {
    const el = args.currentElements['hero'];
    console.log(el.progress);  // 0 to 1
    console.log(el.el);        // DOM element
    console.log(el.id);        // data-scroll-id value
  }
});

currentElements structure:

{
  'element-id': {
    el: HTMLElement,      // DOM element
    id: string,           // data-scroll-id
    class: string,        // data-scroll-class
    top: number,          // Distance from top
    middle: number,       // Distance from middle
    bottom: number,       // Distance from bottom
    offset: object,       // {top, bottom}
    progress: number,     // 0 to 1
    inView: boolean,      // Is in view
    call: string          // data-scroll-call value
  }
}

call

Fires when element with data-scroll-call enters/exits viewport.

scroll.on('call', (func, way, obj) => {
  console.log(func);  // data-scroll-call value
  console.log(way);   // 'enter' or 'exit'
  console.log(obj);   // {el, id}
});

Example:

<div data-scroll data-scroll-call="playVideo">Video</div>

scroll.on('call', (func, way) => {
  if (func === 'playVideo' && way === 'enter') {
    video.play();
  }
});

Properties

scroll.scroll

Current scroll state:

console.log(scroll.scroll);
// {
//   x: 0,      // Horizontal position
//   y: 150     // Vertical position
// }

scroll.limit

Max scroll values:

console.log(scroll.limit);
// {
//   x: 0,      // Max horizontal
//   y: 2500    // Max vertical
// }

scroll.speed

Current scroll speed (if getSpeed: true):

console.log(scroll.speed); // Number

scroll.direction

Current scroll direction (if getDirection: true):

console.log(scroll.direction); // 'up' | 'down' | 'left' | 'right'

Complete Usage Example

import LocomotiveScroll from 'locomotive-scroll';

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  lerp: 0.05,
  multiplier: 1,
  class: 'is-inview',
  repeat: false,
  offset: ['10%', 0],
  getSpeed: true,
  getDirection: true,
  smartphone: {
    smooth: false,
    breakpoint: 768
  }
});

// Track scroll
scroll.on('scroll', (args) => {
  console.log(args.scroll.y);

  if (args.currentElements['hero']) {
    const progress = args.currentElements['hero'].progress;
    // Sync with animation
  }
});

// Handle call events
scroll.on('call', (func, way) => {
  if (func === 'lazyLoad' && way === 'enter') {
    loadImages();
  }
});

// Update on window resize
window.addEventListener('resize', () => scroll.update());

// Cleanup on unmount
window.addEventListener('beforeunload', () => scroll.destroy());