textimation

A tiny React component that animates text with a typewriter / scramble effect: characters shuffle through random glyphs before settling on the final string. It animates the first time it scrolls into view, and re-animates whenever the text prop changes.

Installation

npm install textimation
# or: bun add textimation · pnpm add textimation · yarn add textimation

React 18 or 19 is required (peer dependency).

Usage

import 'textimation/styles.css'
import { Textimation } from 'textimation'

function App() {
  return (
    <Textimation
      text="Hello, world!"
      Comp="p"
      animationSpeed={30}
      keepCorrectChars
    />
  )
}

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | text | string | (required) | The text to animate to. Changing it re-runs the animation. | | animationSpeed | number | 50 | Milliseconds between character changes — lower is faster. Timing is frame-accurate (requestAnimationFrame-driven); 0 means "as fast as possible", bounded per display frame. | | type | 'random' or 'incremental' | 'random' | random scrambles every character for a similar duration; incremental settles characters roughly left-to-right. | | keepCorrectChars | boolean | false | On text changes, leave already-correct characters untouched instead of re-scrambling them. | | Comp | ElementType | 'span' | The wrapper element/component to render (e.g. 'p', 'h1'). | | className | string | — | Class applied to the wrapper element. |

Styling

Importing textimation/styles.css ships sensible defaults. While animating, each character is wrapped in a <span> carrying one of two classes that you can override:

• .textimation-correctChar — a character that has reached its final value.
• .textimation-incorrectChar — a character that is still scrambling.

.textimation-correctChar {
  transition: opacity 0.2s ease-in-out;
  opacity: 1;
}

.textimation-incorrectChar {
  transition: opacity 0.2s ease-in-out;
  opacity: 0.2;
}

Prefer to ship your own styles? Skip the CSS import and define those two classes yourself.

Design notes

• Monospace fonts. The effect is designed for monospace fonts, where every scramble glyph has the same width. In a variable-width font the text will jitter horizontally while scrambling — that's an accepted tradeoff, not a bug; there is no per-character width reservation.
• Reduced motion. When the user's system sets prefers-reduced-motion: reduce, the scramble is skipped entirely and the final text appears immediately. This is checked at the start of each animation; there is no prop to override it.
• Background tabs. The animation is requestAnimationFrame-driven, so it pauses in hidden tabs and resumes on focus without a catch-up burst.
• Unicode. Text is split by code points, so surrogate-pair characters like emoji animate as single units. Multi-code-point grapheme clusters (ZWJ sequences such as 👨‍👩‍👧, flags, skin-tone modifiers) still split into their components while animating — a known limitation. Note that emoji are usually double-width even in monospace fonts, so expect minor width wobble on those slots.

Contributing

Please see CONTRIBUTING.md for contribution guidelines.

License

MIT License