Cursor Image Trail

A trail of images that follows the cursor with fade, scale, and rotation animations powered by Motion.

Installation

File Structure

cursor-image-trail.tsx

Usage

import { CursorImageTrail } from "@/components/unlumen-ui/cursor-image-trail";

const IMAGES = [
  "https://example.com/photo-1.jpg",
  "https://example.com/photo-2.jpg",
  "https://example.com/photo-3.jpg",
];

<CursorImageTrail images={IMAGES} className="h-[480px] w-full bg-neutral-950">
  <p className="text-white/30 select-none">Move your cursor</p>
</CursorImageTrail>;

API Reference

CursorImageTrail

Prop	Type	Default
`images`	`string[]`	-
`imageSize?`	`number`	`120`
`trailLength?`	`number`	`8`
`spawnDistance?`	`number`	`80`
`rotationRange?`	`number`	`20`
`containerRef?`	`React.RefObject<HTMLElement>`	-
`className?`	`string`	-
`children?`	`React.ReactNode`	-

Notes

Images are cycled in order from the images array, wrapping back to the start.
Each image is centered on the spawn point using CSS transform: translate(-50%, -50%).
Older trail images are progressively smaller and more transparent — the newest image is always fully opaque at full scale.
Add cursor-none to the container className to hide the default OS cursor for full effect.
Pass containerRef to confine tracking to a specific element rather than the whole window.

Credits

Built by Unlumen UI.