Skip to content

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.

Grid NotesVersion 3.15.0MotionChecked 2026-11-11
Setup & agent config

Install and prerequisites

What your agent should install or configure before writing code with this pack.
Terminal
npm install gsap @gsap/react
Packages:gsap@gsap/react

Client components in Next.js App Router need "use client". Register plugins once with gsap.registerPlugin(ScrollTrigger, SplitText, useGSAP).

Framework setup

Production-ready wiring for React 19, Next.js App Router and Tailwind CSS v4.

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.

components/reveal-section.tsx
"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.

components/pulse-button.tsx
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

Real-world traps — version mismatches, licence boundaries, main-thread stalls and CSS layer rules — that trip AI agents up.
  1. 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).

  2. 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 under html[data-motion="on"] set by an inline script, and keep the <h1> visible from first paint.

  3. SplitText screen-reader duplication

    SplitText's built-in aria option puts aria-label on 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.

  4. Bundle size and idle setup

    GSAP core + ScrollTrigger + SplitText is about 48.7 kB gzip. Schedule non-critical ScrollTrigger setup in requestIdleCallback (wrapped in contextSafe) so hydration doesn't become a single >50 ms long task.

Accessibility and reduced motion

How to keep animations and interactive components accessible across keyboard, screen readers and prefers-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.

components/split-heading.tsx
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>
  );
}