Skip to main content

Options

lenisOptions​

  • Type: object

(Optional) The lenisOptions parameter is an optional object that allows you to configure specific settings based on some of Lenis's instance settings:

  • wrapper (HTMLElement|Window): Specifies the element that will be used as the scroll container. Defaults to window for full-page scrolling. Can be set to a custom element for contained scrolling (e.g., document.querySelector('.scroll-container')).
  • content (HTMLElement): Specifies the element that contains the content that will be scrolled, usually wrapper's direct child. Defaults to document.documentElement. Can be set to a custom element when using a custom wrapper.
  • lerp (number): Specifies the intensity of linear interpolation (lerp) between frames, ranging from 0 to 1.
  • duration (number): Specifies the duration of the animation.
  • orientation (string): Specifies whether the scrolling is vertical or horizontal. It adds a data-scroll-orientation attribute on the <html> tag.
  • gestureOrientation (boolean): Specifies the orientation of the gestures. It can be set to vertical, horizontal, or both.
  • smoothWheel (boolean): Specifies whether to enable smooth scrolling for mouse wheel events.
  • smoothTouch (boolean): Specifies whether to enable smooth scrolling for touch events. Note that it is disabled by default because it is impossible to mimic the native smoothness of touch devices.
  • wheelMultiplier (number): Specifies the multiplier to use for mouse wheel events.
  • touchMultiplier (number): Specifies the multiplier to use for touch events.
  • normalizeWheel (boolean): Specifies whether to normalize wheel inputs across different browsers.
  • easing (function): Specifies the rate of change of a specific value. Our default easing is custom, but you can choose one from Easings.net.

Here's an example of using lenisOptions with its default values:

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)), // https://www.desmos.com/calculator/brs54l4xou
    },
});

Custom Scroll Container​

You can use a custom scroll container instead of the default full-page scroll:

const locomotiveScroll = new LocomotiveScroll({
    lenisOptions: {
        wrapper: document.querySelector('.scroll-container'),
        content: document.querySelector('.scroll-content'),
    },
});
<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 must have a fixed height and overflow: hidden (or auto/scroll)
  • The content 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

triggerRootMargin​

  • Type: string
  • Default: '-1px -1px -1px -1px'

(Optional) Specifies the root margin for scroll elements that need to be triggered by the IntersectionObserver.

// Default Value
const locomotiveScroll = new LocomotiveScroll({
    triggerRootMargin: '-1px -1px -1px -1px',
});

rafRootMargin​

  • Type: string
  • Default: '100% 100% 100% 100%'

(Optional) Specifies the root margin for scroll elements that need to be triggered by the IntersectionObserver based on a RequestAnimationFrame. This option is relevant for elements with any of the following attributes: data-scroll-offset, data-scroll-position, data-scroll-css-progress, data-scroll-event-progress, data-scroll-speed.

// Default Value
const locomotiveScroll = new LocomotiveScroll({
    rafRootMargin: '100% 100% 100% 100%',
});

autoStart​

  • Type: boolean
  • Default: true

(Optional) Enable or disable the RAF (Request Animation Frame) starting. By default, the RAF starts automatically when Locomotive Scroll is initialized.

If you want to manually control when the RAF starts, you can set autoStart to false.

// Default Value
const locomotiveScroll = new LocomotiveScroll({
    autoStart: false,
});

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

scrollCallback​

  • Type: function

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

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,
});

initCustomTicker​

  • Type: function

(Optional) Specifies a callback function to initialize an external ticker instead of Locomotive Scroll's default request animation frame. The destroyCustomTicker function also needs to be declared.

You can use an external ticker by following this example, which overrides the default request animation frame used by Locomotive Scroll:

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);
    },
});

destroyCustomTicker​

  • Type: function

(Optional) Specifies a callback function to destroy an external ticker instead of Locomotive Scroll's default request animation frame. The initCustomTicker function also needs to be declared.

You can use an external ticker by following this example, which overrides the default request animation frame used by Locomotive Scroll:

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);
    },
});