GSAP SplitText

When to use this

• A headline or paragraph needs to animate in per-character, per-word, or per-line rather than as one opaque block.
• You need masked line reveals (text sliding up out of a clipped box, a common "editorial" reveal style).
• You need choreographed per-character effects (wave, scramble-in, color sweep) that require each glyph as its own DOM node.
• You need the split to survive responsive reflow (line breaks change at different viewport widths) without stale, misaligned line wrappers.
• Do NOT use this for simple whole-block fade/slide of a text element; that is a plain tween in gsap-core-timelines and splitting text for a single uniform transform is unnecessary DOM overhead.

Mental model

SplitText's job is to take a block of text and insert wrapper elements around characters, words, and/or lines so each becomes an independently animatable DOM node, then hand you back arrays of references to those nodes (split.chars, split.words, split.lines). Under the hood it does this by reading the text content, measuring rendered character/word/line boundaries via the browser's own layout engine (it must actually render the text first to know where line breaks fall, since that depends on font metrics and container width), and replacing the original text nodes with nested <div>/<span> wrappers positioned to render identically to the original.

Because line breaks are a layout-dependent fact (they change when the container resizes, font loads, or viewport changes), a SplitText line split is only valid for the container width it was measured at. This is why SplitText ships a resize handling story: as of the GSAP 3.13 SplitText rewrite, SplitText.create() supports an autoSplit: true option (or you re-run .split() manually) that automatically re-splits and re-renders on resize, preserving your animation setup rather than leaving stale line wrappers that no longer match the reflowed text.

For masked line reveals, the key structural detail is that SplitText's line-splitting wraps each line in an outer non-animated wrapper (used as the visual clip/mask boundary via overflow: hidden) and an inner animated element that actually moves; you must apply overflow: hidden yourself to the correct wrapper level (SplitText's linesClass targets the right element) for the visual mask effect, since SplitText handles the DOM structure but not your CSS.

Per-character choreography treats each split.chars[i] element as a normal GSAP tween target, so everything from gsap-core-timelines (stagger, position parameter, keyframes) applies directly; the only new mechanic is that "characters" now exist as real elements you can select and animate independently, and reading split.chars.length gives you the true glyph count for computing stagger timing.