Getting started / 01
Make a little noise.
One install. One element. Suddenly your headline has an entrance. Here's the short path from static type to motion.
01 / The tiny first step
Install the package.
Drop it into your project. There are no runtime animation dependencies tagging along.
npm install words-in-motionHTMLElement. Importing the package is safe during server rendering; call effects after the element exists in the browser.02 / Your first entrance
Pixels first. Words second.
pixelResolve turns coarse blocks into crisp type. Give it a headline, then let the returned handle tell you when the show is over.
import { pixelResolve } from "words-in-motion/intro";
const handle = pixelResolve("#headline", {
pixelSize: 16,
steps: 8,
duration: 1600,
});
await handle.finished;
// Call handle.cancel() if the element leaves before it finishes.The target can be "#headline" or the element itself. For pixelResolve, wait until web fonts are ready so the canvas version lines up with the final text.
03 / In a component
Mount. Move. Clean up.
Wait for fonts, guard against unmounting while they load, and cancel the animation in the effect cleanup. React StrictMode can mount effects twice in development, so cleanup matters.
import { useEffect, useRef } from "react";
import { pixelResolve } from "words-in-motion/intro";
export function AnimatedHeadline() {
const textRef = useRef<HTMLHeadingElement>(null);
useEffect(() => {
let mounted = true;
let handle: ReturnType<typeof pixelResolve> | undefined;
document.fonts.ready.then(() => {
if (!mounted || !textRef.current) return;
handle = pixelResolve(textRef.current, { duration: 1600 });
});
return () => {
mounted = false;
handle?.cancel();
};
}, []);
return <h1 ref={textRef}>Hello, motion.</h1>;
}Cursor effects are long-running interactions. Their cleanup uses destroy():
import { useEffect, useRef } from "react";
import { pull } from "words-in-motion/interact";
export function MagneticTitle() {
const textRef = useRef<HTMLHeadingElement>(null);
useEffect(() => {
let mounted = true;
let interaction: ReturnType<typeof pull> | undefined;
document.fonts.ready.then(() => {
if (!mounted || !textRef.current) return;
interaction = pull(textRef.current, { pointerArea: "target" });
});
return () => {
mounted = false;
interaction?.destroy();
};
}, []);
return <h2 ref={textRef}>Come a little closer.</h2>;
}04 / The off switch
Every effect leaves a handle.
finishedA promise for intros, loops, outros and scroll triggers. It resolves when the work finishes or is canceled.
cancel()Stops an intro, loop or outro. A scroll trigger also has cancel() for its active animation.
destroy()Tears down an interact or scroll effect and restores the text and listeners.
pause() and resume(). A scroll trigger has both cancel() and destroy(); use destroy() on unmount.05 / A few useful edges
Keep the text happy.
- Server rendering: imports are safe in Next.js, Nuxt, Remix and SvelteKit. Start effects in client-side lifecycle code.
- Tree-shaking: import from category paths such as
words-in-motion/introorwords-in-motion/interact. - Outros: they hide the target when finished by default. Pass
keep: trueto restore visibility after the exit. - Text updates: cancel or destroy the current effect before changing its text, then start it again.
- Reduced motion: the package checks the user's preference and resolves effects safely when motion is reduced.