GSAP with React

When to Use This Skill

Installation

# Install the GSAP library
npm install gsap
# Install the GSAP React package
npm install @gsap/react

Prefer the useGSAP() Hook

useEffect()

import { useGSAP } from "@gsap/react";

gsap.registerPlugin(useGSAP); // register before running useGSAP or any GSAP code

const containerRef = useRef(null);

useGSAP(() => {
  gsap.to(".box", { x: 100 });
  gsap.from(".item", { opacity: 0, stagger: 0.1 });
}, { scope: containerRef });

• ✅ Pass a scope (ref or element) so selectors like

  .box

  are scoped to that root.
• ✅ Cleanup (reverting animations and ScrollTriggers) runs automatically on unmount.
• ✅ Use contextSafe from the hook's return value to wrap callbacks (e.g. onComplete) so they no-op after unmount and avoid React warnings.

Refs for Targets

scope

gsap.context()

Dependency array, scope, and revertOnUpdate

useGSAP(() => {
		// gsap code here, just like in a useEffect()
},{ 
  dependencies: [endX], // dependency array (optional)
  scope: container,     // scope selector text (optional, recommended)
  revertOnUpdate: true  // causes the context to be reverted and the cleanup function to run every time the hook re-synchronizes (when any dependency changes)
});

gsap.context() in useEffect (when useGSAP isn't used)

useEffect(() => {
  const ctx = gsap.context(() => {
    gsap.to(".box", { x: 100 });
    gsap.from(".item", { opacity: 0, stagger: 0.1 });
  }, containerRef);
  return () => ctx.revert();
}, []);

• ✅ Pass a scope (ref or element) as the second argument so selectors are scoped to that node.
• ✅ Always return a cleanup that calls ctx.revert().

Context-Safe Callbacks

const container = useRef();
const badRef = useRef();
const goodRef = useRef();

useGSAP((context, contextSafe) => {
	// ✅ safe, created during execution
	gsap.to(goodRef.current, { x: 100 });

	// ❌ DANGER! This animation is created in an event handler that executes AFTER useGSAP() executes. It's not added to the context so it won't get cleaned up (reverted). The event listener isn't removed in cleanup function below either, so it persists between component renders (bad).
	badRef.current.addEventListener('click', () => {
		gsap.to(badRef.current, { y: 100 });
	});

	// ✅ safe, wrapped in contextSafe() function
	const onClickGood = contextSafe(() => {
		gsap.to(goodRef.current, { rotation: 180 });
	});

	goodRef.current.addEventListener('click', onClickGood);

	// 👍 we remove the event listener in the cleanup function below.
	return () => {
		// <-- cleanup
		goodRef.current.removeEventListener('click', onClickGood);
	};
},{ scope: container });

Server-Side Rendering (Next.js, etc.)

• Use useGSAP (or useEffect) so all GSAP code runs only on the client.
• If GSAP is imported at top level, ensure the app does not execute gsap.* or ScrollTrigger.* during server render. Dynamic import inside useEffect is an option if tree-shaking or bundle size is a concern.

Best practices

• ✅ Prefer useGSAP() from

  @gsap/react

  rather than

  useEffect()

  /

  useLayoutEffect()

  ; use gsap.context() + ctx.revert() in

  useEffect

  when

  useGSAP

  is not an option.
• ✅ Use refs for targets and pass a scope so selectors are limited to the component.
• ✅ Run GSAP only on the client (useGSAP or useEffect); do not call gsap or ScrollTrigger during SSR.

Do Not

• ❌ Target by selector without a scope; always pass scope (ref or element) in useGSAP or gsap.context() so selectors like

  .box

  are limited to that root and do not match elements outside the component.
• ❌ Animate using selector strings that can match elements outside the current component unless a

  scope

  is defined in useGSAP or gsap.context() so only elements inside the component are affected.
• ❌ Skip cleanup; always revert context or kill tweens/ScrollTriggers in the effect return to avoid leaks and updates on unmounted nodes.
• ❌ Run GSAP or ScrollTrigger during SSR; keep all usage inside client-only lifecycle (e.g. useGSAP).

Learn More