Media / COMPONENT

Image Trail

A pointer-driven trail of floating image cards, staggered and faded with Motion.

Live preview
Move or tap to explore
View the Image Trail source on GitHub

How it works

Move or tap over the canvas to place image cards. New cards are throttled, drift slightly as they fade, and are removed after their animation completes.

Accessibility

The canvas has an accessible label and supports pointer and touch input. Decorative trail images are hidden from assistive technology, and the effect is disabled for users who prefer reduced motion.

Limitations

The component renders the supplied image URLs directly. Keep the images array stable, provide useful alt text for the source data, and ensure the image host permits embedding.

Features

  • Cycles through the supplied images as the pointer moves or the canvas is tapped.
  • Throttles image creation to keep the interaction smooth.
  • Adds a small rotation and drift as each image fades away.
  • Limits the number of active trail cards.
  • Supports custom container and image classes.
  • Respects reduced-motion preferences.

Installation

Choose the CLI command or install the component manually.

Package manager
$ npx @istmx/ui add image-trail

Copies the install command for your selected package manager.

Dependencies

ReactMotionTailwind CSSclsxtailwind-merge

Usage

Import the component from the file you copied it to, then use it like any other React component.

Usage
import ImageTrail from '@/components/ui/image-trail'
 
const images = [
  { src: '/images/one.jpg', alt: 'Mountain lake' },
  { src: '/images/two.jpg', alt: 'Coastal cliffs' },
]
 
<ImageTrail
  images={images}
  throttle={160}
  maxTrailItems={5}
  className="h-[30rem]"
  imageClassName="rounded-2xl"
/>

Composition

Composition
ImageTrail
├── Interactive canvas
├── Pointer and touch input
└── Animated image trail

API reference

imagesImageTrailItem[]

Required image list. Each item contains src and alt.

className?string

Classes for the canvas container.

imageClassName?string

Classes applied to each trail image.

throttle?number

Minimum interval between image spawns in milliseconds. Defaults to 160.

maxTrailItems?number

Maximum number of trail images active at once. Defaults to 5.

The listed props match the current component implementation.

Data attributes

Image Trail does not expose custom data attributes.

Examples

Move the pointer across the canvas or tap to place image cards. Lower throttle values create a denser trail; maxTrailItems controls how many cards remain active together.

Credits & inspiration

Created by Aryan (istmX) for ISTMX. The source-first, copy-and-own philosophy is inspired by shadcn/ui. About the creator