greensock/GSAP · error

Please gsap.registerPlugin(ScrollTrigger)

Error message

Please gsap.registerPlugin(ScrollTrigger)

What it means

ScrollTrigger's constructor checks that the core was initialized via ScrollTrigger.register(gsap); if not it warns "Please gsap.registerPlugin(ScrollTrigger)". Without registration the plugin's integration with gsap core (context, refresh hooks) is not set up and behavior is unreliable.

Source

Thrown at src/ScrollTrigger.js:600

					onComplete && onComplete.call(tween);
				};
				tween = getTween.tween = gsap.to(scroller, vars);
				return tween;
			};
		scroller[prop] = getScroll;
		getScroll.wheelHandler = () => getTween.tween && getTween.tween.kill() && (getTween.tween = 0);
		_addListener(scroller, "wheel", getScroll.wheelHandler); // Windows machines handle mousewheel scrolling in chunks (like "3 lines per scroll") meaning the typical strategy for cancelling the scroll isn't as sensitive. It's much more likely to match one of the previous 2 scroll event positions. So we kill any snapping as soon as there's a wheel event.
		ScrollTrigger.isTouch && _addListener(scroller, "touchmove", getScroll.wheelHandler);
		return getTween;
	};




export class ScrollTrigger {

	constructor(vars, animation) {
		_coreInitted || ScrollTrigger.register(gsap) || console.warn("Please gsap.registerPlugin(ScrollTrigger)");
		_context(this);
		this.init(vars, animation);
	}

	init(vars, animation) {
		this.progress = this.start = 0;
		this.vars && this.kill(true, true); // in case it's being initted again
		if (!_enabled) {
			this.update = this.refresh = this.kill = _passThrough;
			return;
		}
		vars = _setDefaults((_isString(vars) || _isNumber(vars) || vars.nodeType) ? {trigger: vars} : vars, _defaults);
		let {onUpdate, toggleClass, id, onToggle, onRefresh, scrub, trigger, pin, pinSpacing, invalidateOnRefresh, anticipatePin, onScrubComplete, onSnapComplete, once, snap, pinReparent, pinSpacer, containerAnimation, fastScrollEnd, preventOverlaps} = vars,
			direction = vars.horizontal || (vars.containerAnimation && vars.horizontal !== false) ? _horizontal : _vertical,
			isToggle = !scrub && scrub !== 0,
			scroller = _getTarget(vars.scroller || _win),
			scrollerCache = gsap.core.getCache(scroller),
			isViewport = _isViewport(scroller),

View on GitHub (pinned to 13e2b79054)

Solutions

  1. Call gsap.registerPlugin(ScrollTrigger) at app startup before any scroll-triggered animation
  2. In React use the useGSAP hook / register inside a module evaluated before components
  3. For CDN, after script tags: gsap.registerPlugin(ScrollTrigger)
  4. Combine all plugin registrations into one bootstrap module imported first

Example fix

// before
import { ScrollTrigger } from 'gsap/ScrollTrigger';
ScrollTrigger.create({ trigger: '.box', start: 'top center' });
// after
import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger);
ScrollTrigger.create({ trigger: '.box', start: 'top center' });
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  ScrollTrigger.create(triggerVars);
} catch (e) {
  gsap.registerPlugin(ScrollTrigger);
  ScrollTrigger.create(triggerVars);
}

Prevention

When it happens

Trigger: new ScrollTrigger({...}) or ScrollTrigger.create/gsap.timeline({scrollTrigger: ...}) without prior gsap.registerPlugin(ScrollTrigger); importing ScrollTrigger but not registering it, or registration happening after first use.

Common situations: Bundled apps forgetting registerPlugin after import, using useGSAP/React without registering in the bootstrap, CDN pages that load ScrollTrigger.js but never call registerPlugin, or circular imports delaying registration.

Related errors

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