Docs·Image Trail

Image Trail

Venetian-blind cursor trail with staggered slice reveals and smoothed pointer tracking.

Installation

$pnpm dlx shadcn@latest add @spiderui/image-trail

Usage

API Reference

PropTypeDefault
imagesImage URLs cycled on each spawn.
string[]DEFAULT_TRAIL_IMAGES
imageLifespanHow long each frame stays visible before exiting (ms).
number1000
minDistancePointer travel in px before spawning the next frame.
number45
revealDurationSlice reveal animation duration (ms).
number450
fadeDurationOpacity fade duration on exit (ms).
number350
staggerDelayDelay between each slice animation (ms).
number30
lerpFactorPointer smoothing strength (0–1).
number0.08
maxItemsMaximum trail frames visible at once.
number8
slicesCountNumber of mask stripes per frame.
number10
blindDirectionSlice orientation for the venetian blind reveal.
"vertical" | "horizontal"vertical
itemWidthTrail frame width in pixels.
number300
itemHeightTrail frame height in pixels.
number400
desktopMinWidthMinimum viewport width before the effect runs (0 = always on).
number0
backgroundImageOptional ambient background image behind the trail.
string—
childrenOverlay content centered above the trail layer.
ReactNode—
classNameClasses on the root wrapper.
string—

Click on the icon in the top right of the example preview to view the source code for specific variants.

Keep in mind

This component is inspired by various open-source projects and patterns. Please verify licenses and implementation details before using in production.

Have any questions?
Contact on@ctrlcat0x

Move your mouse around.

import { ImageTrail } from "@/components/ui/image-trail"
const images = [
  "https://cdn.cosmos.so/your-image.webp",
  "/trail-images/2.jpg",
]

export default function Page() {
  return (
    <div className="relative h-screen w-full overflow-hidden bg-black">
      <ImageTrail images={images} />
    </div>
  )
}