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 }.
| Effect | What it does | Key options |
|---|---|---|
| directionalReveal | Characters arrive through clipped frames in an irregular order. | duration, by: 'chars' | 'words' |
| lampFlicker | A sign warming up, then holding steady. | duration, flickers, by: 'all' | 'words' | 'chars' |
| rise | Text rises from below or drops from above. | duration, from, distance, by, mask, fade |
| chunkedScramble | Reveals lines or word groups through a brief typo storm. | duration, revealBy, chunkSize, corruptionRate |
| stripRealign | Horizontal text strips slide back into place. | duration, strips, maxOffset, by |
| pixelResolve | Coarse blocks sharpen into the original text. | duration, pixelSize, steps |
import { rise } from "words-in-motion/intro";
const entrance = rise("#headline", {
from: "ground",
by: "words",
duration: 800,
});
await entrance.finished;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.
| Effect | What it does | Key options |
|---|---|---|
| wave | A continuous traveling vertical wave. | duration, intensity, by, stagger |
| float | Slow elliptical drift with a quiet return. | duration, intensity, by, stagger |
| breathe | A gentle expansion, exhale and rest. | duration, intensity, by, stagger |
| shimmer | A light sweep that keeps the text color. | duration, intensity, by, stagger |
| pendulum | Softly phased letter tilts. | duration, intensity, by, stagger |
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.
| Effect | What it does | Key options |
|---|---|---|
| blackHole | Letters spiral into the center. | duration, by, keep |
| paperCut | Horizontal slices slide apart. | duration, strips, maxOffset, keep |
| breakAndFade | A reading-order fracture and fade. | duration, sweepDuration, keep |
| hingeDrop | Characters pivot and fall out of line. | duration, distance, keep |
| blurAway | Words lift, defocus and dissolve. | duration, blur, distance, keep |
| windScatter | A gust carries letters away. | duration, direction, distance, keep |
import { blurAway } from "words-in-motion/outro";
const exit = blurAway("#message", {
blur: 10,
duration: 1100,
keep: true,
});
await exit.finished;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.
| Effect | What it does | Key options |
|---|---|---|
| pull | A soft attraction toward the pointer. | radius, strength, touch, pointerArea |
| push | A soft repulsion around the pointer. | radius, strength, touch, pointerArea |
| obstaclePush | A solid cursor nudges letters on contact. | cursorRadius, easing, touch, pointerArea |
| proximityFade | Nearby letters fade, then return. | radius, minOpacity, touch |
| proximityFlip | Nearby letters tilt in perspective. | axis, maxAngle, touch |
| proximityRotate | Letters turn near the pointer. | maxAngle, direction, touch |
| proximityShake | A restrained vibration close to the pointer. | maxAmplitude, radius, touch |
| fontWeight | Weight follows the nearest word. | minWeight, maxWeight, focusRadius |
| accentColor | Color follows the pointer. | accentColor, baseColor, radius |
import { pull } from "words-in-motion/interact";
const interaction = pull(".title", {
radius: 170,
pointerArea: "target",
touch: "follow",
});
// When this view unmounts:
interaction.destroy();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().
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.
| Effect | What it does | Key options |
|---|---|---|
| readingLine | Words gain opacity as reading progresses. | start, end, by, smooth, baseOpacity |
| scatterReassemble | Scattered letters settle in reading order. | start, end, by, smooth, maxScatter |
| waveRelay | A traveling letter moves across wrapped lines. | start, end, smooth, waveHeight, waveRadius, pushStrength |
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();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.