words-in-motion

Reference / 02

Know every move.

Five families, one small API. Pick an effect, pass a selector or element, keep its handle, and let the words do their thing.

01 / Arrive

Intro

Intros move text from an initial hidden state into its readable resting state. Import from words-in-motion/intro. All accept a target and optional settings, then return { finished, cancel }.

EffectWhat it doesKey options
directionalRevealCharacters arrive through clipped frames in an irregular order.duration, by: 'chars' | 'words'
lampFlickerA sign warming up, then holding steady.duration, flickers, by: 'all' | 'words' | 'chars'
riseText rises from below or drops from above.duration, from, distance, by, mask, fade
chunkedScrambleReveals lines or word groups through a brief typo storm.duration, revealBy, chunkSize, corruptionRate
stripRealignHorizontal text strips slide back into place.duration, strips, maxOffset, by
pixelResolveCoarse blocks sharpen into the original text.duration, pixelSize, steps
ts
import { rise } from "words-in-motion/intro";

const entrance = rise("#headline", {
  from: "ground",
  by: "words",
  duration: 800,
});

await entrance.finished;
Shared intro settings include duration, delay, easing, stagger, trigger, start and once. The default trigger is immediate.

02 / Stay awhile

Loop

Loops repeat until you call cancel(). Their finished promise resolves on cancellation, reduced motion or an empty target.

EffectWhat it doesKey options
waveA continuous traveling vertical wave.duration, intensity, by, stagger
floatSlow elliptical drift with a quiet return.duration, intensity, by, stagger
breatheA gentle expansion, exhale and rest.duration, intensity, by, stagger
shimmerA light sweep that keeps the text color.duration, intensity, by, stagger
pendulumSoftly phased letter tilts.duration, intensity, by, stagger
ts
import { wave } from "words-in-motion/loop";

const loop = wave(".headline", {
  by: "chars",
  intensity: 1,
  duration: 2400,
});

// When this view unmounts:
loop.cancel();
duration controls one cycle. intensity is a multiplier from 0 to 4; by accepts "chars" or "words".

03 / Exit gracefully

Outro

Outros begin with visible text and hide it when they finish. Pass keep: true when you want the original text visible again afterward. Calling cancel() restores the original content and opacity.

EffectWhat it doesKey options
blackHoleLetters spiral into the center.duration, by, keep
paperCutHorizontal slices slide apart.duration, strips, maxOffset, keep
breakAndFadeA reading-order fracture and fade.duration, sweepDuration, keep
hingeDropCharacters pivot and fall out of line.duration, distance, keep
blurAwayWords lift, defocus and dissolve.duration, blur, distance, keep
windScatterA gust carries letters away.duration, direction, distance, keep
ts
import { blurAway } from "words-in-motion/outro";

const exit = blurAway("#message", {
  blur: 10,
  duration: 1100,
  keep: true,
});

await exit.finished;
All outros also accept shared animation settings such as delay, duration, easing and stagger.

04 / Follow the pointer

Interact

Interactions stay active while mounted. Their handles provide pause(), resume() and destroy(). Multiple cursor effects can share one target.

EffectWhat it doesKey options
pullA soft attraction toward the pointer.radius, strength, touch, pointerArea
pushA soft repulsion around the pointer.radius, strength, touch, pointerArea
obstaclePushA solid cursor nudges letters on contact.cursorRadius, easing, touch, pointerArea
proximityFadeNearby letters fade, then return.radius, minOpacity, touch
proximityFlipNearby letters tilt in perspective.axis, maxAngle, touch
proximityRotateLetters turn near the pointer.maxAngle, direction, touch
proximityShakeA restrained vibration close to the pointer.maxAmplitude, radius, touch
fontWeightWeight follows the nearest word.minWeight, maxWeight, focusRadius
accentColorColor follows the pointer.accentColor, baseColor, radius
ts
import { pull } from "words-in-motion/interact";

const interaction = pull(".title", {
  radius: 170,
  pointerArea: "target",
  touch: "follow",
});

// When this view unmounts:
interaction.destroy();
Shared settings include radius, strength, easing, touch, pointerArea and respectReducedMotion. Weight changes look smoothest with a variable font.

05 / Go with the page

Scroll

Trigger mode plays an animation when an element reaches a viewport position. Scrub mode ties progress directly to scroll position. Both use viewport anchors such as "top 80%".

Trigger handles expose finished, cancel() and destroy(). Scrub handles expose pause(), resume() and destroy().

ts
import { createScrollTrigger } from "words-in-motion/scroll";
import { rise } from "words-in-motion/intro";

const trigger = createScrollTrigger(
  ".headline",
  { start: "top 80%", repeat: true },
  (element) => rise(element, { duration: 800 }),
);

// When this view unmounts:
trigger.destroy();

The ready-made scrub effects below use the same scroll position model. They follow the viewport; use the home page examples to see them at full size.

EffectWhat it doesKey options
readingLineWords gain opacity as reading progresses.start, end, by, smooth, baseOpacity
scatterReassembleScattered letters settle in reading order.start, end, by, smooth, maxScatter
waveRelayA traveling letter moves across wrapped lines.start, end, smooth, waveHeight, waveRadius, pushStrength
ts
import { readingLine } from "words-in-motion/scroll";

const scrub = readingLine(".copy", {
  start: "top 85%",
  end: "top 25%",
  by: "words",
  smooth: 0.25,
});

// When this view unmounts:
scrub.destroy();
Trigger settings include start, threshold, repeat and once. Scrub settings include start, end, threshold, by and smooth.

06 / Everyone gets the words

Accessibility

The split text keeps the original readable string in an aria-label on its container. Generated character and word spans use aria-hidden="true", so assistive technology does not announce the animation one letter at a time.

The package respects prefers-reduced-motion: entrances and exits resolve safely, loops stop, cursor displacement is disabled, and scroll effects settle to a readable state.

Cursor effects support touch: "follow", "tap" or "none". Choose the interaction that makes sense for the surface, and keep ordinary text selectable at rest.

The browser still needs real text in the element. Let the package split it; do not pre-split the letters yourself.