gsap-text

GSAP Text — SplitText + ScrambleText

Flow: gsap-setup → gsap-animate → gsap-text → gsap-optimise → gsap-test Key files: composables/useReveal.js, plugins/gsap.js, assets/css/tailwind.css

Companion: For SplitText/ScrambleText API reference, invoke gsap-plugins. This skill covers text animation recipes only. Requires: greensock/gsap-skills

1. SplitText Setup

// Preferred — useReveal handles everything:
const { init, hero, scroll, split } = useReveal(sectionRef)
onMounted(() => init(() => scroll()))

// Manual setup: const { $gsap: gsap, $lazyLoadSplitText, $lazyLoadScramble } = useNuxtApp() let SplitText, ctx const splits = []

onMounted(async () => { await document.fonts.ready // CRITICAL: fonts before split SplitText = await $lazyLoadSplitText() ctx = gsap.context(() => { /* ... */ }, scopeRef.value) })

onUnmounted(() => { splits.forEach(s => s.revert()) splits.length = 0 ctx?.revert() })


### Creating a split

```js
const s = SplitText.create(el, { type: 'words', mask: 'words' })
splits.push(s)
gsap.set(s.words, { y: '100%' })
gsap.set(el, { visibility: 'visible' })

2. Masked Word Slide-Up (Production Pattern)

The standard heading reveal used across 25+ components.

ctx = gsap.context(() => {
  const s = SplitText.create(el, { type: 'words', mask: 'words' })
  splits.push(s)
  gsap.set(s.words, { y: '100%' })
  gsap.set(el, { visibility: 'visible' })

  gsap.to(s.words, {
    y: '0%', duration: 0.8, ease: 'power4.out', stagger: 0.06, force3D: true,
    scrollTrigger: {
      trigger: el, start: 'top 85%',
      toggleActions: 'play none none reverse', invalidateOnRefresh: true,
    },
  })
}, scopeRef.value)

Via useReveal (preferred)

<div ref="sectionRef">
  <div class="reveal">
    <h2 class="text-reveal">HEADING TEXT</h2>
  </div>
</div>

const { init, scroll } = useReveal(sectionRef)
onMounted(() => init(() => scroll()))

3. ScrambleText Decode

See gsap-plugins skill for ScrambleText API reference. Recipe:

gsap.to(el, {
  duration: 0.8 + el.textContent.length * 0.005,
  scrambleText: { text: 'FINAL TEXT', chars: '▓░▒█▀▄╬╠╣▐▌■□', revealDelay: 0.3, speed: 0.4 },
})

4. Gotchas Summary

See references/learnings.md for full details and code examples.

Await document.fonts.ready before SplitText.create()
autoSplit: true is for lines only (responsive reflow) — words/chars don't need it. Always pair with onSplit()
Parent autoAlpha + child mask: use visibility, not autoAlpha
Never blank textContent before scramble
Set overwrite: false on colocated per-word tweens
SplitText preserves <span> — use :deep(div) for gradient styles
CSS .reveal + .text-reveal pre-hide classes prevent FOUC

5. useReveal Composable Reference

Method	Description
`init(fn)`	Async: waits for fonts, lazy-loads SplitText + Scramble, creates gsap.context
`hero(selector?, overrides?)`	Immediate reveal for above-fold. Auto-detects `.text-reveal` children
`scroll(selector?, overrides?)`	Per-element ScrollTrigger reveal with `.reveal` + `.text-reveal`
`split(target)`	SplitText wrapper: creates masked word split, tracks for cleanup

// Hero (above-fold, immediate)
const { init, hero } = useReveal(sectionRef)
onMounted(() => init(() => hero('.reveal', { textDelay: 0.2 })))

// Scroll (below-fold, per-element ScrollTrigger)
const { init, scroll } = useReveal(sectionRef)
onMounted(() => init(() => scroll('.reveal', { start: 'top 75%', once: true })))

Cleanup is automatic — onUnmounted reverts gsap.context and all SplitText instances.

References

references/text-patterns.md — Combined clip+scramble, kinetic character split, elastic type assembly, rolling text (3D slot machine), horizontal text (containerAnimation), masked lines reveal, autoSplit with ScrollTrigger
references/learnings.md — 7 critical gotchas from production debugging