greensock/GSAP · error

Please gsap.registerPlugin(ScrollSmoother)

Error message

Please gsap.registerPlugin(ScrollSmoother)

What it means

ScrollSmoother is a members-only GSAP plugin whose constructor checks ScrollSmoother.register(gsap) succeeded (_coreInitted). If registration never happened it warns that gsap.registerPlugin(ScrollSmoother) is required; the instance will not function correctly.

Source

Thrown at src/ScrollSmoother.js:48

			change += extraChange;
		}
		return {change, offset};
	},
	_wrap = el => {
		let wrapper = _doc.querySelector(".ScrollSmoother-wrapper"); // some frameworks load multiple times, so one already exists, just use that to avoid duplicates
		if (!wrapper) {
			wrapper = _doc.createElement("div");
			wrapper.classList.add("ScrollSmoother-wrapper");
			el.parentNode.insertBefore(wrapper, el);
			wrapper.appendChild(el);
		}
		return wrapper;
	};

export class ScrollSmoother {

	constructor(vars) {
		_coreInitted || ScrollSmoother.register(gsap) || console.warn("Please gsap.registerPlugin(ScrollSmoother)");
		vars = this.vars = vars || {};

		_mainInstance && _mainInstance.kill();
		_mainInstance = this;
		_context(this);

		let {smoothTouch, onUpdate, onStop, smooth, onFocusIn, normalizeScroll, wholePixels} = vars,
			content, wrapper, height, mainST, effects, sections, intervalID, wrapperCSS, contentCSS, paused, pausedNormalizer, recordedRefreshScroll, recordedRefreshScrub, allowUpdates,
			self = this,
			effectsPrefix = vars.effectsPrefix || "",
			scrollFunc = ScrollTrigger.getScrollFunc(_win),
			smoothDuration = ScrollTrigger.isTouch === 1 ? (smoothTouch === true ? 0.8 : parseFloat(smoothTouch) || 0) : (smooth === 0 || smooth === false) ? 0 : parseFloat(smooth) || 0.8,
			speed = (smoothDuration && +vars.speed) || 1,
			currentY = 0,
			delta = 0,
			startupPhase = 1,
			tracker = _getVelocityProp(0),
			updateVelocity = () => tracker.update(-currentY),

View on GitHub (pinned to 13e2b79054)

Solutions

  1. Call gsap.registerPlugin(ScrollSmoother) before ScrollSmoother.create/new ScrollSmoother
  2. Verify your GSAP license/build actually includes ScrollSmoother (it is a Club GSAP plugin)
  3. Centralize plugin registration in a bootstrap module imported before app code
  4. Check import order so the plugin module is loaded before registration call

Example fix

// before
import { ScrollSmoother } from 'gsap/ScrollSmoother';
const smoother = ScrollSmoother.create({ smooth: 1 });
// after
import { gsap } from 'gsap';
import { ScrollSmoother } from 'gsap/ScrollSmoother';
gsap.registerPlugin(ScrollSmoother);
const smoother = ScrollSmoother.create({ smooth: 1 });
Defensive patterns

Strategy: validation

Validate before calling

import { gsap } from 'gsap';
import { ScrollSmoother } from 'gsap/ScrollSmoother';
gsap.registerPlugin(ScrollSmoother);
if (!gsap.core.globals().ScrollSmoother) throw new Error('ScrollSmoother not registered / not licensed');

Try / catch

try {
  const smoother = ScrollSmoother.create(vars);
} catch (e) {
  console.error('ScrollSmoother unavailable — verify Club GSAP build and registration', e);
}

Prevention

When it happens

Trigger: new ScrollSmoother({...}) without calling gsap.registerPlugin(ScrollSmoother) first, or using ScrollSmoother.create without registration, often because the plugin file was never imported or an unregistered/free build was used.

Common situations: Importing ScrollSmoother without registration in a bundler setup, loading the plugin script after instantiating, or attempting to use ScrollSmoother with a GSAP package that does not include it (it requires a Club GSAP membership).

Related errors

AI-assisted analysis of greensock/GSAP@13e2b79054 (2026-08-29). Data as JSON: /api/errors/2d72ef507be58d20. Report an issue: GitHub.