Getting Started
Components
TweenCommand Palette
Search for a command to run...
TweenSearch for a command to run...
import { ImageTrailCursor } from "@/registry/tween/image-trail-cursor"
export function ImageTrailCursorDemo() {
return (
<ImageTrailCursor
className="flex items-center justify-center bg-[#fcfcfc] text-[#1e1e1e]"
style={{ height: "var(--preview-h, 100vh)" }}
>
<h1 className="px-6 text-center text-[clamp(2rem,5cqi,4rem)] leading-[0.95] font-medium tracking-tight select-none">
Move your cursor.
</h1>
</ImageTrailCursor>
)
}
import { ImageTrailCursor } from "@/components/ui/image-trail-cursor"<ImageTrailCursor
className="flex h-[600px] items-center justify-center bg-white"
images={["/a.jpg", "/b.jpg", "/c.jpg"]}
>
<h1>Move your cursor.</h1>
</ImageTrailCursor>As the pointer moves across the container, the component samples its travel
distance and spawns a new image from the images array once it exceeds
mouseThreshold. Each spawned image scales in, holds at full size for
imageLifespan milliseconds, then scales back out and is removed, producing
a continuous trail that follows the cursor. While the pointer sits idle
inside the container, images keep spawning on idleInterval so the effect
never freezes, and scroll movement is throttled by scrollThreshold so the
trail stays smooth during fast scrolling. Children render above the trail
layer, so headings and links stay fully interactive.
| Prop | Type | Default | Description |
|---|---|---|---|
images | string[] | 20 defaults | Image URLs to randomise from. |
imageLifespan | number | 750 | How long each trail image stays at full scale (ms). |
mouseThreshold | number | 100 | Minimum pointer travel before a new image is spawned (px). |
idleInterval | number | 300 | Spawn interval while the pointer is idle inside the container (ms). |
scrollThreshold | number | 50 | Minimum delay between scroll-triggered spawns (ms). |
imageSize | number | 200 | Width/height of each trail image (px). |
inDuration | number | 750 | Scale-in transition duration (ms). |
outDuration | number | 1000 | Scale-out transition duration (ms). |
inEasing | string | cubic-bezier | CSS easing for scale-in. |
outEasing | string | cubic-bezier | CSS easing for scale-out. |
scroller | HTMLElement | string | null | — | Optional scroll target; defaults to the ambient preview scroller. |
children | ReactNode | — | Content rendered inside the wrapped area (sits above the trail layer). |
className | string | — | Extra classes on the outer container. |