Image Trail

Use Image Trail for a decorative cursor effect inside a bounded editorial or portfolio area. Images appear only while a fine pointer moves, and the trail never intercepts links or buttons beneath it.

Preview

Reduce motion:Off

Tune:Off

Inspect

Move your cursor here

Installation

Motion

npx shadcn@latest add @sona-ui/image-trail

Basic usage

gallery-trail.tsx

import ImageTrail from "@/components/ui/image-trail/image-trail";
 
export function GalleryTrail() {
return <ImageTrail images={["/one.jpg", "/two.jpg"]}>Explore</ImageTrail>;
}

Examples

Choose scale, fade, blur, rise, or tilt for the image treatment. Use maxImages and ignoreSelector to keep the effect bounded around interactive content.

Usage


const images = [
  "https://picsum.photos/id/1015/300/200",
  "https://picsum.photos/id/1025/300/200",
  "https://picsum.photos/id/1035/300/200",
  "https://picsum.photos/id/1043/300/200",
  "https://picsum.photos/id/1050/300/200",
  "https://picsum.photos/id/1062/300/200",
];
 
export default function ImageTrailExample() {
  return (
    <ImageTrail
      images={images}
      className="h-full min-h-[50vh] w-full flex items-center justify-center"
    >
      <div className="flex h-full w-full items-center justify-center">
        <h3 className="pointer-events-none text-center font-semibold text-2xl text-foreground">
          Move your cursor here
        </h3>
      </div>
    </ImageTrail>
  );
}

API

Property	Type	Default	Description
`images`	`string[]`	`required`	Image sources spawned in order as the pointer moves.
`children`	`ReactNode`	`required`	The content the effect is scoped to; the trail only spawns over this area.
`className`	`string`	`—`	Additional CSS classes for the container.
`itemClassName`	`string`	`"w-40"`	Extra classes for each trail image (use for sizing, e.g. `"w-48"`).
`threshold`	`number`	`80`	Pointer distance in pixels travelled before the next image spawns.
`maxImages`	`number`	`8`	Maximum number of images alive at once.
`lifetime`	`number`	`600`	How long an image stays before it animates out, in milliseconds.
`variant`	`"scale" \| "fade" \| "blur" \| "rise" \| "tilt"`	`"scale"`	Entrance and exit animation style.
`ignoreSelector`	`string`	`"a, button, input, [data-image-trail-ignore]"`	CSS selector for elements that suppress the effect when hovered, keeping interactive UI unobstructed.
`zIndex`	`number`	`10`	z-index of the trail layer.

Accessibility

The effect is decorative, ignores interactive elements, and runs only for a fine pointer. Reduced-motion preferences disable the trail.

Styling

Use className to define the effect area and place meaningful content in the normal document flow.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Sona UI