Минимальная конфигурация

Для начала необходимо установить библиотеку. В современных проектах это можно сделать через npm или yarn:

npm install locomotive-scroll
# или
yarn add locomotive-scroll

После установки подключение выполняется в JavaScript-файле проекта:

import LocomotiveScroll from 'locomotive-scroll';
import 'locomotive-scroll/dist/locomotive-scroll.css';

Важно подключать CSS-файл библиотеки, так как он содержит базовые стили, необходимые для корректной работы скролла.

Создание контейнера скролла

Locomotive Scroll требует наличия контейнера, в котором будет происходить управление прокруткой. Обычно используется элемент с классом scroll-container:

<div class="scroll-container" data-scroll-container>
    <section data-scroll-section>
        <h1 data-scroll data-scroll-speed="1">Заголовок</h1>
        <p data-scroll data-scroll-speed="2">Текст параграфа</p>
    </section>
    <section data-scroll-section>
        <h2 data-scroll data-scroll-speed="1">Второй блок</h2>
    </section>
</div>

Ключевые моменты:

  • Атрибут data-scroll-container указывает Locomotive Scroll, какой элемент использовать как основной контейнер.
  • Каждый блок, который должен быть отдельной секцией для скролла, получает data-scroll-section.
  • Любые элементы, требующие анимации при прокрутке, помечаются data-scroll. Скорость анимации задаётся через data-scroll-speed.

Инициализация библиотеки

Минимальная конфигурация инициализации выглядит следующим образом:

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

Объяснение параметров:

  • el — DOM-элемент контейнера, на котором будет применяться прокрутка.
  • smooth — включает плавную прокрутку (true/false). Без этого параметра прокрутка будет обычной, браузерной.

Основные атрибуты элементов

  1. data-scroll Помечает элемент для отслеживания при скролле. Позволяет управлять скоростью и направлением.

  2. data-scroll-speed Задаёт скорость движения элемента относительно скролла.

    • 1 — обычная скорость
    • 2 — в два раза быстрее
    • -1 — движение в противоположном направлении

  3. data-scroll-direction Определяет направление движения элемента:

    • vertical (по умолчанию)
    • horizontal — для горизонтального эффекта

  4. data-scroll-repeat Позволяет анимации повторяться каждый раз, когда элемент появляется в области видимости.

Основные методы

  • update() — обновляет состояние скролла, полезно при динамическом изменении DOM:
scroll.update();
  • scrollTo(target, options) — плавно перемещает страницу к элементу или позиции:
scroll.scrollTo('#section2', {
    offset: -50, // смещение относительно верха
    duration: 1000, // время анимации в мс
    easing: [0.25, 0.0, 0.35, 1.0] // кривая ускорения
});
  • destroy() — отключает Locomotive Scroll и возвращает страницу к стандартной прокрутке:
scroll.destroy();

Адаптация к изменениям DOM и ресайзу

При добавлении новых элементов или изменении размера окна необходимо вызывать update():

window.addEventListener('resize', () => {
    scroll.update();
});

Это гарантирует, что библиотека правильно вычислит позиции всех элементов.

Минимальная конфигурация для работы на мобильных устройствах

Locomotive Scroll по умолчанию поддерживает мобильные устройства, но иногда рекомендуется включить определённые параметры:

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

Такой подход гарантирует, что плавная прокрутка будет работать на всех типах устройств.

Проверка работы

После инициализации и добавления data-scroll элементов, прокрутка должна быть плавной, а элементы с разной скоростью движения будут создавать эффект параллакса. Если элементы не реагируют на скролл, необходимо проверить:

  • наличие атрибута data-scroll-container на корневом элементе;
  • корректность подключения CSS;
  • правильность инициализации объекта LocomotiveScroll.

Рекомендации по производительности

  • Избегать слишком большого количества элементов с data-scroll-speed > 2, чтобы не нагружать рендер;
  • Минимизировать тяжелые DOM-структуры внутри скролл-контейнера;
  • Вызывать update() только при необходимости, например после изменения контента или ресайза.
Оглавление