Подключение GSAP к проекту

Для интеграции анимаций с Locomotive Scroll необходимо подключить библиотеку GSAP. Она доступна несколькими способами: через CDN, npm или yarn.

Через CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.13.0/gsap.min.js"></script>

Через npm:

npm install gsap

После установки через npm импорт выполняется следующим образом:

import gsap from "gsap";

Если планируется использование плагинов GSAP, например, ScrollTrigger, необходимо подключить их отдельно:

import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

Интеграция с Locomotive Scroll

Locomotive Scroll использует виртуальный скролл, поэтому стандартные события прокрутки браузера не применимы напрямую для GSAP ScrollTrigger. Для корректной работы необходимо синхронизировать скролл с GSAP.

Инициализация Locomotive Scroll

import LocomotiveScroll from "locomotive-scroll";

const scrollContainer = document.querySelector("[data-scroll-container]");

const locoScroll = new LocomotiveScroll({
  el: scrollContainer,
  smooth: true,
  multiplier: 1.2,
  lerp: 0.1
});

Здесь el — контейнер с атрибутом data-scroll-container, smooth включает плавную прокрутку, multiplier управляет скоростью, а lerp задаёт сглаживание.

Связь с GSAP ScrollTrigger

GSAP ScrollTrigger необходимо уведомить о позициях скролла Locomotive Scroll:

locoScroll.on("scroll", ScrollTrigger.update);

ScrollTrigger.scrollerProxy(scrollContainer, {
  scrollTop(value) {
    return arguments.length ? locoScroll.scrollTo(value, 0, 0) : locoScroll.scroll.instance.scroll.y;
  },
  getBoundingClientRect() {
    return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
  },
  pinType: scrollContainer.style.transform ? "transform" : "fixed"
});
  • scrollTop синхронизирует позицию прокрутки с GSAP.
  • getBoundingClientRect возвращает размеры видимой области.
  • pinType определяет способ закрепления элементов (через transform или fixed) в зависимости от возможностей браузера.

После настройки необходимо обновлять ScrollTrigger при ресайзе и инициализации:

ScrollTrigger.addEventListener("refresh", () => locoScroll.update());
ScrollTrigger.refresh();

Создание анимаций с учётом скролла

Пример анимации элемента при скролле:

gsap.to(".box", {
  scrollTrigger: {
    trigger: ".box",
    scroller: scrollContainer, // важный момент для работы с Locomotive Scroll
    start: "top 80%",
    end: "bottom 20%",
    scrub: true,
  },
  x: 500,
  rotation: 360,
  duration: 3
});
  • scroller указывает контейнер Locomotive Scroll.
  • scrub: true синхронизирует анимацию с прокруткой.
  • start и end задают диапазон анимации относительно позиции элемента и окна.

Анимации при использовании pinning

Locomotive Scroll и GSAP ScrollTrigger поддерживают закрепление элементов:

gsap.to(".section", {
  scrollTrigger: {
    trigger: ".section",
    scroller: scrollContainer,
    start: "top top",
    end: "+=100%",
    pin: true,
    pinSpacing: false,
    scrub: true
  },
  backgroundColor: "#ff0000",
});
  • pin: true фиксирует элемент на экране в течение скролла.
  • pinSpacing: false отключает добавление отступов, что важно при кастомном скролле.

Советы по производительности

  1. Минимизировать количество pinned элементов — большое количество фиксированных элементов может тормозить прокрутку.
  2. Использовать scrub аккуратно — плавная синхронизация с прокруткой сильно нагружает рендер, особенно на мобильных устройствах.
  3. Обновлять ScrollTrigger после динамического контента — новые элементы должны регистрироваться для корректного расчёта позиции.

Итоговая структура интеграции

  1. Подключение GSAP и ScrollTrigger.
  2. Инициализация Locomotive Scroll с контейнером.
  3. Настройка scrollerProxy для синхронизации с GSAP.
  4. Создание анимаций с scrollTrigger, указывая контейнер scroller.
  5. Обновление ScrollTrigger и Locomotive Scroll при изменении DOM или размеров окна.

Эта схема позволяет комбинировать плавный виртуальный скролл и мощные анимации GSAP, создавая динамичные, отзывчивые интерфейсы.

Оглавление