Kinetic Text

Text that reacts. Every character is an independent animated element — revealed with its own entrance, living with ambient motion, and responsive to narrative events in real time. Pair it with TTS and the text doesn't just display a story, it performs one.

Three effect layers run simultaneously on separate DOM nodes. Reveal controls how text first appears — the entrance style as each character arrives. Continuous effects keep text alive after reveal — ambient loops that sustain mood. One-shot effects fire on demand for dramatic punctuation. All three compose without interfering — text can be mid-reveal while a continuous loop runs and a one-shot fires. A built-in skeleton loader derives its geometry from the same layout engine, so line count and widths match the real text exactly before it arrives.

How it works

Layout starts with Pretext — Cheng Lou's zero-DOM text measurement engine that computes per-character positions using pure arithmetic over the browser's font metrics, without triggering reflow. Kinetic Text feeds the measured positions into a character renderer that builds a 4-layer DOM tree:

.kt-unit (outer, continuous effects) → .kt-oneshot (middle, one-shot effects) → .kt-glyph (inner, reveal animation). A fourth layer, .kt-word, wraps word groups and carries secondary harmonic motion for effects like drift, wave, and float. Each layer runs its own CSS animation independently — swapping or clearing one layer never interrupts the others.

A seeded PRNG generates unique CSS custom properties per character (--kt-dx, --kt-dy, --kt-rotate, --kt-scale, --kt-skew, --kt-opacity-min). Parametric @keyframes read these variables, so a single animation definition produces different motion on every glyph. The seed is deterministic — same text, same effect, same visual every time.

Pretext is MIT-licensed open source. Kinetic Text bundles it as a direct dependency.

Per-Character Effects

Effects operate on already-revealed text. Continuous effects (21) are ambient loops that set the emotional tone of a scene — they run on the outer .kt-unit layer and persist until explicitly changed. Some carry a secondary harmonic on the .kt-word wrapper for richer compound motion. One-shot effects (16) are discrete events that fire once and clean up — they run on the middle .kt-oneshot layer, triggered by the cue system or an imperative counter. For TTS-driven narrative, one-shots pair naturally with speech events — fire a glitch when the voice falters, a surge when tension peaks.

Technical Details

Continuous effects set animation on .kt-unit with infinite iteration. Seven effects (drift, breathe, wave, float, pulse, tremble, haunt) also set a secondary animation on the .kt-word wrapper — a slower harmonic that modulates the entire word group for compound motion. Changing activeEffect clears the current animation and applies the new one; other layers are untouched.

One-shot effects set animation on .kt-oneshot with a single iteration. Each character gets a stagger delay (phase * baseDelay + jitter) and a duration multiplier (0.85 – 1.15) for organic timing. The animation cleans up per-character on animationend — distributed teardown, no global timer. Effects only animate already-visible characters and skip any still mid-reveal.

Physics adaptation: glass adds motion blur (--physics-blur) on displacement-heavy effects and uses spring easing; flat uses clean ease-out curves; retro forces steps() timing and limits scramble charsets to uppercase + digits.

One-Shot Effects

Punctuation moments. Hover a card to fire the effect, or click the button to replay.

Continuous Effects

Sustained atmosphere loops. Each character animates independently with unique parameters. Pause any effect to compare.

Reference

One-Shot Effects

Fire once after text is fully revealed. Use for punctuation moments.

shake — Physical Impact: Rapid horizontal jitter, decaying to rest. Door slams, collisions, nearby explosions, heavy objects crashing.
quake — Massive Force: Violent two-axis displacement with a rolling settle. Building collapses, close detonations, structural failure, the ground splitting open.
jolt — Sudden Shock: Single sharp displacement with an elastic snap-back. Jump scares, sudden grabs, betrayals revealed, waking from nightmares.
glitch — Digital Corruption: Choppy skewed displacement with stepped timing. Simulation malfunctions, memory rewrites, hacking, signal failure, reality fractures.
surge — Power Activation: Ascending scale with brightness flash. Magic cast, transformation, divine intervention, power activation, epiphany.
warp — Spatial Distortion: Horizontal scaleX oscillation with subtle skew. Teleportation, portal entry, dimensional shift, time warp, gravity anomaly.
explode — Radial Blast: Characters fly outward from center with full rotation and scale-to-zero, then reassemble. Detonations, supernovae, catastrophic failure.
collapse — Gravity Fall: Characters fall downward with tumbling rotation, then spring back. Building demolition, cave-ins, structural failure.
scatter — Gentle Dispersal: Characters drift apart in random directions with slow rotation and fade. Wind dispersal, memory fragmenting, ash drifting.
spin — Full Rotation: Each character does a full 360° rotation with scale pulse. Staggered domino wave. Vertigo, mechanical activation.
bounce — Elastic Impact: Characters drop, hit a floor, and bounce with decreasing amplitude. Landing impacts, playful energy, ground pounds.
flash — Brightness Burst: Quick scale-up pulse with brightness burst rippling across characters. Lightning, camera flash, energy discharge.
shatter — Fragmentation: Sharp angular displacement with skew, like broken glass pieces. Glass breaking, reality cracking, shield failure.
vortex — Spiral Collapse: Characters spiral inward with accelerating rotation and scale-down. Black holes, whirlpools, summoning rituals.
ripple — Traveling Wave: Vertical wave propagating left-to-right through text. Shockwaves, water surfaces, sonic booms.
slam — Heavy Impact: Characters scale up huge then slam to normal with overshoot. Heavy impacts, dramatic entrances, boss landings.

Continuous Effects

Loop from the moment the step starts, sustaining atmosphere throughout.

drift — Weightlessness: Slow vertical sine wave. Underwater scenes, dreaming, zero gravity, fog, meditative calm after intense action.
flicker — Unstable Environment: Irregular opacity drops with hard cuts. Failing lights, unstable power, haunted spaces, fading transmissions, phasing presence.
breathe — Held Tension: Slow rhythmic scale pulse. Suspense, centering before action, emotional weight (grief, awe), meditation, charged stillness.
tremble — Fragile Vulnerability: Fast micro-vibration, deliberately small. Freezing cold, bodily fear, physical fragility, suppressed emotion about to overflow.
pulse — Building Pressure: Heartbeat-tempo scale with sharp attack. Audible heartbeat, ritual energy charging, countdowns, approaching something powerful.
whisper — Fading Presence: Opacity and scale recede together. Ghosts speaking, fading memories, telepathy, secrets shared in near-silence, dying words.
fade — Consciousness Dissolve: Gradual opacity drift to half visibility. Losing consciousness, drugged, time skip, memory dissolving, falling asleep.
freeze — Cold Stillness: Micro scale contraction with brightness reduction. Ice magic, paralysis, time freeze, petrification, stasis.
burn — Heat Distortion: Vertical micro-wobble with skew at fast rhythm. Fire scenes, desert heat, rage, fever, volcanic environments.
static — Signal Noise: Rapid micro-jitter layered with opacity flicker. Radio transmission, broken comms, digital interference, corrupted data.
distort — Woozy Perception: Subtle rotation with asymmetric scale oscillation. Drunk, poisoned, hallucinating, vertigo, psychic influence, concussion.
sway — Lateral Oscillation: Horizontal sine wave. Ship travel, storms, unstable footing, earthquake aftermath, rope bridges, moving vehicles.
glow — Luminous Emission: Brightness emission cycle. Enchantment, bioluminescence, divine presence, energy radiation, rune activation.
wave — Propagating Motion: Y sine wave with scale swell and secondary harmonic. Ocean, crowd motion, musical rhythm, energy propagation.
float — Weightless Suspension: Dual-axis drift with micro rotation and secondary harmonic. Zero gravity, levitation, underwater, astral projection.
wobble — Playful Instability: Micro rotation oscillation. Instability, jelly physics, cartoon impact, uncertain footing, balancing acts.
sparkle — Light Twinkle: Opacity twinkle with randomized phase per character. Magic particles, starlight, treasure glint, fairy dust.
drip — Gravity Pull: Downward Y drift with slow reset. Rain, melting, decay, liquid surfaces, cave dripping, candle wax.
stretch — Vertical Distortion: Scale Y elongation cycle. Distortion fields, elastic matter, body horror, spatial warping, funhouse mirrors.
vibrate — High-Frequency Energy: Rapid positional jitter, faster and tighter than tremble. Machinery, engines, electrical charge, intense energy.
haunt — Ghostly Presence: Ghostly drift with deep opacity cycling and secondary harmonic. Ghosts, afterimages, fading memories, echoes.

Most steps should have no effect. Effects are seasoning — contrast and restraint make them land.

Reveal Styles

Reveal styles control the visual entrance animation — how each character physically arrives at its target position. While reveal mode sets granularity (word vs character), reveal style sets the motion: characters can scramble in from random positions, rise from below, drop with gravity, pop into place, or appear in shuffled order. Every style generates unique per-character parameters so no two letters move identically.

Technical Details

Reveal animations run on the innermost .kt-glyph layer. Each character transitions through three states: hidden → revealing → visible, driven by data-kt-state. The revealing state triggers a CSS keyframe that reads per-character variables (--kt-dx, --kt-dy, --kt-rotate, --kt-scale) as starting transforms and animates to identity. Spring easing controls overshoot — scramble and drop have heavy bounce, blur and scale settle cleanly.

Styles differ in which parameters they use: pop sets random XY offsets, scramble adds wide radius + heavy rotation, rise/drop constrain to vertical axis with directional bias, scale uses only the scale channel, and blur uses only filter. The instant style skips the animation entirely.

Physics presets adapt automatically: glass adds blur trails on rise/drop and uses cubic-bezier spring curves, flat uses ease-out, retro skips blur entirely and uses steps() timing. Default style is pop — set revealStyle to override.

Reveal Modes

Reveal mode sets the granularity of how text enters the viewport. Word mode is the default — it reveals whole words at a time and is the mode used with all narrative effects. Character mode reveals one letter at a time for a classic typewriter feel, with Decode as a character-level variant where all glyphs appear immediately as scrambled noise and resolve left-to-right.

Technical Details

The reveal timeline is a RAF loop that marks characters as revealing according to the mode's granularity. Char advances one character per tick at the stagger interval. Word advances one word per tick at the speed interval, with an internal per-character stagger set by charSpeed — so each word appears as a fast burst rather than a single frame. Decode makes all characters visible from frame zero with scrambled content, then resolves them left-to-right through configurable scramblePasses (default 4) — each pass swaps the glyph to a random character from a physics-dependent charset before settling on the real one.

The speed prop controls inter-word delay (word mode) or is ignored (char/decode mode, which use stagger instead). Speed presets bundle both values for convenience. Retro physics uses a limited charset for scramble passes: uppercase letters and digits only, matching the CRT terminal aesthetic.

Speed