Built for Motion
Log in
All posts

GSAP SplitText in React and Next.js: Text Reveals

Masked line reveals, staggered words and letters that survive font loading and resizes: how to use the rewritten SplitText with useGSAP in a Next.js app.

Most of the text animation you see on award-winning sites is the same idea: break a heading into lines, words or letters, then move the pieces one after another. GSAP's SplitText does the breaking. Since GSAP 3.13 it is free, it ships inside the regular gsap package, and it was rewritten to be smaller, to handle accessibility for you, and to re-split itself when fonts load or the layout changes.

Here is how to use it in React and Next.js without the usual problems.

1. Register it next to useGSAP

Nothing extra to install beyond gsap and @gsap/react. Import the plugin, register it once at the top of the module, and mark the file as a client component: SplitText measures the text in the browser, so it can't run on the server.

2. A masked line reveal

The effect people ask for most: each line slides up from behind an invisible edge. mask: "lines" wraps every line in a clipping element, so the words can start below it and rise into view.

components/reveal-heading.tsx
"use client";

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

gsap.registerPlugin(useGSAP, SplitText);

export function RevealHeading({ children }: { children: string }) {
  const ref = useRef<HTMLHeadingElement>(null);

  useGSAP(
    () => {
      SplitText.create(ref.current, {
        type: "lines, words",
        mask: "lines",
        autoSplit: true,
        onSplit(self) {
          // Returned, so a re-split picks up where this animation left off.
          return gsap.from(self.words, {
            yPercent: 110,
            duration: 0.9,
            ease: "expo.out",
            stagger: 0.04,
          });
        },
      });
    },
    { scope: ref },
  );

  return <h1 ref={ref}>{children}</h1>;
}

Because the split happens inside useGSAP, it is reverted with everything else when the component unmounts, and React's double mount in development doesn't leave nested spans behind.

3. Why autoSplit and onSplit matter

Lines are only known once the text is laid out. If you split before your web font arrives, the lines are measured in the fallback font, and the real font then wraps differently: words jump between lines mid-animation. The same happens when the window is resized.

autoSplit: true re-splits when fonts finish loading and when the element's width changes. Create your animation inside onSplit and return it, and SplitText reverts the old animation and builds the new one at the same progress, so nobody sees the swap.

4. Play it on scroll

For headings further down the page, add a ScrollTrigger to the same tween:

onSplit, with ScrollTrigger
onSplit(self) {
  return gsap.from(self.lines, {
    yPercent: 100,
    duration: 1,
    ease: "expo.out",
    stagger: 0.08,
    scrollTrigger: { trigger: ref.current, start: "top 85%" },
  });
},

Remember to register ScrollTrigger as well. Animating self.lines instead of words gives a calmer, editorial feel; self.chars with a tiny stagger suits short, loud headlines.

5. Screen readers still read one sentence

A heading split into forty spans can be read out letter by letter. The rewritten SplitText handles this by default: it puts an aria-label with the full text on the element and hides the pieces from assistive technology. Leave that on unless you have your own solution.

6. Things that catch people out

  • Gradient text disappears. A background-clip: text gradient on the heading doesn't carry into the split pieces, especially once they are inline-block. Put the gradient on the pieces themselves, or keep the gradient line out of the split.
  • Server markup and client markup differ. That is expected: SplitText rewrites the DOM after hydration. Split a plain element whose children React won't re-render, like a heading with a string inside, rather than one that changes with state.
  • Reduced motion. Wrap the animation in gsap.matchMedia() with (prefers-reduced-motion: no-preference), and the text simply appears for people who ask for less movement.
  • Text hidden before JavaScript runs. If you hide the heading in CSS to avoid a flash, make sure it becomes visible again when the animation starts, or it stays hidden without JavaScript.

Ready-made text animations

Every text component in the library is built this way. Try Scramble Text, Rubber Band Letters or the variable font manifesto, each with a live preview, or browse all components.