gust

gust is a zero-added-dependency text animation for React. When a label changes, outgoing characters lift away and incoming ones settle in on a staggered draft — the shared prefix never moves, so only the difference animates. It's driven by the Web Animations API, respects reduced motion, and adds no animation runtime.

$ bunx shadcn@latest add maniktherana/gust/gust

Usage

import { Gust } from "@/components/ui/gust";

// cycle a list of words
<Gust words={["a gust of wind", "a gust of words"]} />

// or drive it yourself — every change animates
<Gust text={copied ? "Copied" : "Copy"} />

Props

Prop	Default	Description
words	["a gust of…"]	Words to cycle through.
text	—	Controlled mode — every change animates.
className	—	CSS or Tailwind classes for typography, color, and spacing.
index	—	Pin a specific word, disables the cycle.
interval	1600	Hold per word, ms.
duration	440	Enter duration per character, ms.
exitDuration	360	Exit duration per character, ms.
stagger	12	Delay between characters, ms.
entranceHeight	8	Overshoot above the baseline.
entranceScale	1.1	Peak scale mid-entrance.
exitHeight	90	Upward exit travel, % of line height.
exitScale	0.4	Scale characters shrink to on exit.
blur	true	Blur in and out.
scale	true	Scale in and out.
preservePrefix	true	Keep the shared prefix still.

Best practices

Use gust for:

Button labels that confirm an action — Save, Saving…, Saved.
Prices, counts and totals where only some digits change.
Statuses: deploys, uploads, presence, build pipelines.
Short headlines cycling through a few words.

Avoid gust for:

Paragraphs or long sentences — it animates characters, not prose.
Text that changes many times a second; the hold is clamped so updates queue up.
Anything the user is in the middle of reading or editing.

exit

a gust of wliftinshrinkdblur

enter

a gust of wsettleoovershootrdsrise