TextEngine splits text into letter, word, and line animation slots, each driven by independent react-spring springs. Mixed children are fully supported — plain strings animate alongside React elements, and non-text nodes (SVG icons, images) are treated as single word units.

Installation

npm install spring-text-engine
# peer dependency
npm install @react-spring/web

Import

import TextEngine from 'spring-text-engine';
import type { TextEngineInstance, EngineProps } from 'spring-text-engine';

// named imports
import { TextEngine, ProgressTrigger, tengine } from 'spring-text-engine';

Quick start

import { easings } from '@react-spring/web';
import TextEngine from 'spring-text-engine';

export function Hero() {
  return (
    <TextEngine
      tag="h1"
      mode="once"
      overflow
      lineIn={{ y: 0, opacity: 1 }}
      lineOut={{ y: 60, opacity: 0 }}
      lineStagger={100}
      lineConfig={{ duration: 900, easing: easings.easeOutCubic }}
    >
      The quick brown fox
    </TextEngine>
  );
}

Each word is wrapped in up to 6 nested layers. Layers render only when their corresponding *In prop is non-empty, keeping the DOM flat when a layer is unused.

<wrapLine>          ← overflow clip + line-level spring
  <line>            ← line spring (all words on same line share same delay)
    <wrapWord>      ← overflow clip + word spring
      <word>        ← word spring
        <wrapLetter> ← per-letter overflow clip
          <letter>  ← per-letter spring
        </wrapLetter>
      </word>
    </wrapWord>
  </line>
</wrapLine>

The mode prop controls when animation plays. Default is "always".

These are the CSS / transform properties you can put inside any *In / *Out target object. React-spring animates between the Out value and the In value for each frame.

Spring configs control the physics or timing of animations. Each level has a shared config (applies to both in and out) and optional directional overrides that take precedence.

SpringConfig properties

import { easings } from '@react-spring/web';

// Physics-based spring
wordConfig={{ tension: 200, friction: 18 }}

// Time-based with easing
lineConfig={{ duration: 800, easing: easings.easeOutQuart }}

// Per-direction override: instant out, spring in
letterConfigIn={{ tension: 220, friction: 20 }}
letterConfigOut={{ duration: 0 }}

Stagger adds a cascading delay between elements. Delay adds a global wait before any element starts. All values are in milliseconds.

Global delays

Stagger

Behaviour flags

Wrap layers are containers that sit around each line, word, or letter. They animate with the same spring config and stagger as their content layer, but are driven by their own independent spring — allowing opposing or complementary transforms.

Overflow clip pattern

Set overflow: 'hidden' on the wrap layer to clip content — the letter/word slides inside the masked boundary:

<TextEngine
  overflow
  wrapLetterIn={{ overflow: 'hidden' }}
  letterIn={{ y: '0%', opacity: 1 }}
  letterOut={{ y: '100%', opacity: 0 }}
  letterStagger={35}
  letterConfig={{ tension: 180, friction: 20 }}
>
  Clipped inside each letter.
</TextEngine>

Opposing transform pattern

Animate wrap and content in opposite directions for striking effects:

// Wrapper falls from above, letters rise from below
wrapWordIn={{ y: 0, opacity: 1 }}
wrapWordOut={{ y: -50, opacity: 0 }}
wordConfig={{ tension: 160, friction: 16 }}
letterIn={{ opacity: 1, y: 0 }}
letterOut={{ opacity: 0, y: 24 }}
letterStagger={14}
letterConfig={{ tension: 280, friction: 22 }}

// Wrapper + content counter-skew (parallelogram shear)
wrapWordIn={{ skewX: 0 }}
wrapWordOut={{ skewX: -20 }}
wordIn={{ opacity: 1, skewX: 0 }}
wordOut={{ opacity: 0, skewX: 20 }}

Wires animation directly to scroll position between start and end trigger points. No manual scroll handling needed.

TriggerPos format

"element-edge viewport-edge" — both edges must be one of top | center | bottom. Optional pixel offset with +=N or -=N.

// Toggle — words snap in as you scroll
<TextEngine
  mode="progress"
  type="toggle"
  start="top bottom"
  end="top center"
  wordIn={{ opacity: 1, y: 0 }}
  wordOut={{ opacity: 0, y: 20 }}
  wordStagger={60}
  wordConfig={{ tension: 180, friction: 20 }}
>
  Snaps in as you scroll past.
</TextEngine>

// Interpolate — letters blur away with scroll
<TextEngine
  mode="progress"
  type="interpolate"
  interpolationStaggerCoefficient={0.25}
  start="top bottom"
  end="center center"
  letterIn={{ opacity: 1, y: 0, filter: 'blur(0px)' }}
  letterOut={{ opacity: 0, y: 40, filter: 'blur(16px)' }}
  letterStagger={25}
>
  Blur fades with your scroll.
</TextEngine>

When seo is true (the default), TextEngine renders a visually-hidden copy of the text using the standard accessible visually-hidden pattern. Crawlers and screen readers see the unmodified text; the animated layer is marked aria-hidden="true".

Core structural props and CSS class hooks for each DOM layer. Useful for hover effects, debugging element boundaries, or targeting with CSS animations.

Core props

Class name props

Lifecycle callbacks fired at different stages. Useful for sequencing, analytics, or triggering other effects.

<TextEngine
  onTextFullyPlayed={(type) => {
    if (type === 'in') startNextAnimation();
  }}
  onTextEngine={(ref) => {
    engineRef.current = ref.current;
  }}
  ...
/>

Access the instance via the onTextEngine callback or a ref. Essential for mode="manual".

interface TextEngineInstance {
  mode:          string;            // reflects current mode prop
  enabled:       boolean;           // reflects effective enabled state
  lines:         LineRef[][];       // DOM word refs grouped by line
  words:         string[][];        // all words as char arrays
  letters:       string[];          // all chars
  playIn():      void;              // trigger enter animation
  playOut():     void;              // trigger exit animation
  togglePause(): void;              // freeze / unfreeze animation
  progress:      RefObject<number>; // write 0–1 for progress-based manual control
}

Manual mode example

import { useRef } from 'react';
import TextEngine, { type TextEngineInstance } from 'spring-text-engine';

export function ManualExample() {
  const engineRef = useRef<TextEngineInstance | null>(null);

  return (
    <>
      <button onClick={() => engineRef.current?.playIn()}>Play In</button>
      <button onClick={() => engineRef.current?.playOut()}>Play Out</button>
      <button onClick={() => engineRef.current?.togglePause()}>Pause</button>

      <TextEngine
        mode="manual"
        tag="h1"
        lineIn={{ y: 0, opacity: 1 }}
        lineOut={{ y: 80, opacity: 0 }}
        lineStagger={100}
        overflow
        onTextEngine={(ref) => { engineRef.current = ref.current; }}
      >
        Manual control
      </TextEngine>
    </>
  );
}

Progress-based manual control

// Write 0–1 to instance.progress.current each frame
// The engine polls it via an internal loop

useEffect(() => {
  const onScroll = () => {
    if (!engineRef.current?.progress) return;
    const el = document.getElementById('section')!;
    const { top, height } = el.getBoundingClientRect();
    engineRef.current.progress.current =
      Math.min(1, Math.max(0, 1 - top / (window.innerHeight - height)));
  };
  window.addEventListener('scroll', onScroll);
  return () => window.removeEventListener('scroll', onScroll);
}, []);

<TextEngine mode="manual" type="toggle" ... onTextEngine={...} />

tengine factory

tengine is a Proxy-based factory returning pre-configured TextEngine for any HTML tag — useful when you want typed tags without passing the tag prop.

import { tengine } from 'spring-text-engine';

const H1 = tengine.h1;
const P  = tengine.p;

<H1 lineIn={{ y: 0, opacity: 1 }} lineOut={{ y: 60, opacity: 0 }} lineStagger={100} overflow>
  Heading
</H1>

<P wordIn={{ y: 0, opacity: 1 }} wordOut={{ y: 20, opacity: 0 }} wordStagger={40}>
  Paragraph
</P>

The Playground → lets you configure all props visually and see the result instantly. All settings are encoded in the URL (?te=…) — copy the URL to share an exact configuration.