GSAP Grid Notes
Timeline, scroll-linked and text-splitting animation engine. All plugins — including ScrollTrigger, SplitText and MorphSVG — are included under Webflow's no-charge licence.
Install and prerequisites
npm install gsap @gsap/reactgsap@gsap/reactClient components in Next.js App Router need "use client". Register plugins once with gsap.registerPlugin(ScrollTrigger, SplitText, useGSAP).
Framework setup
Scoped animations with useGSAP and matchMedia
Wrap scroll and entrance animations in useGSAP with a container scope and gsap.matchMedia() so tweens revert automatically on unmount or when reduced motion turns on.
"use client";
import { useRef, type ReactNode } from "react";
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { useGSAP } from "@gsap/react";
gsap.registerPlugin(ScrollTrigger, useGSAP);
export function RevealSection({ children }: { children: ReactNode }) {
const scope = useRef<HTMLDivElement>(null);
useGSAP(
() => {
const mm = gsap.matchMedia();
mm.add("(prefers-reduced-motion: no-preference)", () => {
gsap.from("[data-reveal]", {
y: 16,
opacity: 0,
duration: 0.45,
stagger: 0.06,
ease: "power2.out",
scrollTrigger: { trigger: scope.current, start: "top 85%", once: true },
});
});
},
{ scope },
);
return <div ref={scope}>{children}</div>;
}Event callbacks with contextSafe
Tweens created after useGSAP runs (such as inside click or pointer handlers) are not cleaned up unless wrapped in contextSafe.
const { contextSafe } = useGSAP({ scope: buttonRef });
const onClick = contextSafe(() => {
gsap.fromTo(buttonRef.current, { scale: 0.97 }, { scale: 1, duration: 0.15, ease: "power2.out" });
});Gotchas for agents
Webflow Standard 'No Charge' licence restriction
GSAP is free for commercial sites and apps, except in tools that let users build visual animations without code in competition with Webflow. Keep GSAP out of visual animation/easing builders (and disable link prefetching to GSAP routes from those pages).
Never hide content in base CSS without a JS gate
If
[data-reveal] { opacity: 0 }is set unconditionally, pages stay blank when JavaScript fails or before hydration finishes. Scope initial hidden states underhtml[data-motion="on"]set by an inline script, and keep the<h1>visible from first paint.SplitText screen-reader duplication
SplitText's built-in
ariaoption putsaria-labelon the parent element, which is unreliable on generic tags across screen readers. Instead, render<span className="sr-only">{text}</span>beside<span aria-hidden="true" data-split>{text}</span>, and split by lines or words — never letters.Bundle size and idle setup
GSAP core + ScrollTrigger + SplitText is about
48.7 kBgzip. Schedule non-critical ScrollTrigger setup inrequestIdleCallback(wrapped incontextSafe) so hydration doesn't become a single >50 ms long task.
Accessibility and reduced motion
Reduced motion
Put every transform, parallax, stagger and loop inside gsap.matchMedia().add('(prefers-reduced-motion: no-preference)', ...). When the media query stops matching, GSAP automatically reverts all tweens and inline styles created inside it.
Keyboard and screen readers
Loops that run longer than 5 seconds require a visible Pause control (WCAG 2.2.2). Never animate focus outlines or move focus during a scroll timeline.
export function SplitHeading({ label, children }: { label: string; children: React.ReactNode }) {
return (
<h2>
<span className="sr-only">{label}</span>
<span aria-hidden="true" data-split className="block">
{children}
</span>
</h2>
);
}More Grid Notes
- LenisLightweight smooth-scroll engine that keeps native browser scrolling, sticky positioning and intersection observers intact, and pairs cleanly with GSAP ScrollTrigger.
- MotionMIT-licensed animation library for React and JavaScript (formerly Framer Motion), offering a 3.3 kB `motion/mini` WAAPI build as well as layout, gesture and spring animations.
- dotLottieLottieFiles' WebAssembly-powered player for `.lottie` archives and Lottie JSON animations, with official wrappers for React, Vue, Svelte and plain web canvas.
- NumberFlowDependency-free animated number component for React, Vue and Svelte that rolls individual digits into place and formats values with `Intl.NumberFormat`.
- RiveInteractive state-machine graphics packaged in compact `.riv` files and driven at 60–120 fps by Rive's open-source WebGL2 and Canvas runtimes.
- Theatre.jsKeyframe timeline engine and visual studio overlay for choreographing Three.js / React Three Fiber cameras, lights and DOM properties.



