Image Trail Following Cursor

Live Preview

Documentation

Webflow

Code

Setup: External Scripts

HTML

Copy

<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.7/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.7/dist/ScrollTrigger.min.js"></script>

Step 1: Copy structure to Webflow

Copy to Webflow

Webflow structure is not required for this resource.

Step 1: Add HTML

HTML

Copy

<div data-trail="wrapper" class="trail-section">
  <h1 class="trail-heading">Cursor Image Trail</h1>
  <div class="trail-wrap">
    <div class="trail-list">
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f69cd4f5ebc0676bf_cursor-trail-1.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f5d1c4cf365a233ea_cursor-trail-2.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f41234aeca6122868_cursor-trail-3.avif" alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f26b40ce34b76bd14_cursor-trail-4.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9ff0e9944f7a772a8c_cursor-trail-5.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f0bd979d3d6280fc8_cursor-trail-6.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9ff0cb7ef9ce6d4b4a_cursor-trail-7.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f7bf12612bbb66235_cursor-trail-8.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9f916943fe31e14fe7_cursor-trail-9.avif"  alt="" class="trail-item__img"></div>
      <div data-trail="item" class="trail-item"><img src="https://cdn.prod.website-files.com/679b7e7de9b9ad0339d5524e/679b8e9fcba222367b58fd97_cursor-trail-10.avif"  alt="" class="trail-item__img"></div>
    </div>
  </div>
</div>

HTML structure is not required for this resource.

Step 2: Add CSS

CSS

Copy

.trail-section {
  justify-content: center;
  align-items: center;
  width: 100%;
  height: 100vh;
  display: flex;
  position: relative;
}

.trail-heading {
  font-size: 3em;
  font-weight: 500;
  line-height: 1;
}

.trail-wrap {
  z-index: 5;
  width: 100%;
  height: 100%;
  position: absolute;
  inset: 0%;
}

.trail-list {
  width: 100%;
  height: 100%;
  position: relative;
}

.trail-item {
  opacity: 0;
  border-radius: .3125em;
  width: 15em;
  height: 20em;
  position: absolute;
  overflow: hidden;
}

.trail-item__img {
  object-fit: cover;
  width: 100%;
  height: 100%;
}

Step 2: Add custom Javascript

Step 2: Add Javascript

Step 3: Add Javascript

Javascript

Copy

function initImageTrail(config = {}) {

  // config + defaults
  const options = {
    minWidth: config.minWidth ?? 992,
    moveDistance: config.moveDistance ?? 15,
    stopDuration: config.stopDuration ?? 300,
    trailLength: config.trailLength ?? 5
  };

  const wrapper = document.querySelector('[data-trail="wrapper"]');
  
  if (!wrapper || window.innerWidth < options.minWidth) {
    return;
  }
  
  // State management
  const state = {
    trailInterval: null,
    globalIndex: 0,
    last: { x: 0, y: 0 },
    trailImageTimestamps: new Map(),
    trailImages: Array.from(document.querySelectorAll('[data-trail="item"]')),
    isActive: false
  };

  // Utility functions
  const MathUtils = {
    lerp: (a, b, n) => (1 - n) * a + n * b,
    distance: (x1, y1, x2, y2) => Math.hypot(x2 - x1, y2 - y1)
  };

  function getRelativeCoordinates(e, rect) {
    return {
      x: e.clientX - rect.left,
      y: e.clientY - rect.top
    };
  }

  function activate(trailImage, x, y) {
    if (!trailImage) return;

    const rect = trailImage.getBoundingClientRect();
    const styles = {
      left: `${x - rect.width / 2}px`,
      top: `${y - rect.height / 2}px`,
      zIndex: state.globalIndex,
      display: 'block'
    };

    Object.assign(trailImage.style, styles);
    state.trailImageTimestamps.set(trailImage, Date.now());

	// Here, animate how the images will appear!
    gsap.fromTo(
      trailImage,
      { autoAlpha: 0, scale: 0.8 },
      {
        scale: 1,
        autoAlpha: 1,
        duration: 0.2,
        overwrite: true
      }
    );

    state.last = { x, y };
  }

  function fadeOutTrailImage(trailImage) {
    if (!trailImage) return;
		
    // Here, animate how the images will disappear!
    gsap.to(trailImage, {
      opacity: 0,
      scale: 0.2,
      duration: 0.8,
      ease: "expo.out",
      onComplete: () => {
        gsap.set(trailImage, { autoAlpha: 0 });
      }
    });
  }

  function handleOnMove(e) {
    if (!state.isActive) return;

    const rectWrapper = wrapper.getBoundingClientRect();
    const { x: relativeX, y: relativeY } = getRelativeCoordinates(e, rectWrapper);
    
    const distanceFromLast = MathUtils.distance(
      relativeX, 
      relativeY, 
      state.last.x, 
      state.last.y
    );

    if (distanceFromLast > window.innerWidth / options.moveDistance) {
      const lead = state.trailImages[state.globalIndex % state.trailImages.length];
      const tail = state.trailImages[(state.globalIndex - options.trailLength) % state.trailImages.length];

      activate(lead, relativeX, relativeY);
      fadeOutTrailImage(tail);
      state.globalIndex++;
    }
  }

  function cleanupTrailImages() {
    const currentTime = Date.now();
    for (const [trailImage, timestamp] of state.trailImageTimestamps.entries()) {
      if (currentTime - timestamp > options.stopDuration) {
        fadeOutTrailImage(trailImage);
        state.trailImageTimestamps.delete(trailImage);
      }
    }
  }

  function startTrail() {
    if (state.isActive) return;
    
    state.isActive = true;
    wrapper.addEventListener("mousemove", handleOnMove);
    state.trailInterval = setInterval(cleanupTrailImages, 100);
  }

  function stopTrail() {
    if (!state.isActive) return;
    
    state.isActive = false;
    wrapper.removeEventListener("mousemove", handleOnMove);
    clearInterval(state.trailInterval);
    state.trailInterval = null;
    
    // Clean up remaining trail images
    state.trailImages.forEach(fadeOutTrailImage);
    state.trailImageTimestamps.clear();
  }

  // Initialize ScrollTrigger
  ScrollTrigger.create({
    trigger: wrapper,
    start: "top bottom",
    end: "bottom top",
    onEnter: startTrail,
    onEnterBack: startTrail,
    onLeave: stopTrail,
    onLeaveBack: stopTrail
  });

  // Clean up on window resize
  const handleResize = () => {
    if (window.innerWidth < options.minWidth && state.isActive) {
      stopTrail();
    } else if (window.innerWidth >= options.minWidth && !state.isActive) {
      startTrail();
    }
  };

  window.addEventListener('resize', handleResize);

  return () => {
    stopTrail();
    window.removeEventListener('resize', handleResize);
  };
}

document.addEventListener("DOMContentLoaded", () => {
  const imageTrail = initImageTrail({
    minWidth: 992,
    moveDistance: 15,
    stopDuration: 350,
    trailLength: 8
  });
});

Step 3: Add custom CSS

Step 2: Add custom CSS

CSS

Copy

Application

The code will look for an element with data-trail="wrapper" on it. This is most likely a specific section or element in which you want to show the trail. Make sure that inside, there's a list of images, each with a data-trail="item" attribute. A cool feature is that event listeners for mouse movement are only added to the wrapper once it's in view. So there's no unnecessary code being ran if the trail section is not even in view. The code offers the ability to init the trail with some config options, which are explained below!

Customization

The trail effect can be initialized with custom options:

initFooterTrail({
  minWidth: 992,    // Breakpoint in pixels - below this width, the effect is disabled
  moveDistance: 15,  // Controls how fast images appear (lower = more frequent)
  stopDuration: 300, // Time in ms before images start fading when mouse stops
  trailLength: 5     // Number of images visible before they start fading out
});

Cleanup

The function returns a cleanup method that can be stored to manually remove the effect when needed:

const removeFooterTrail = initFooterTrail({...});

// Later, to clean up:
removeFooterTrail(); // Removes all event listeners and stops animations

This is useful when you need to:

Disable the trail effect programmatically
Clean up before page transitions in SPAs
Recreate the trail with different settings

Live Preview

Resource Details

Last updated
February 3, 2025
Type
The Vault
Category
Cursor Animations
Need help?
Join Slack

Advanced

Animation

Cursor

Scrolltrigger

Smooth

Transform

Original source

Ilja van Eck

Image Trail Following Cursor

Documentation

External Scripts in Webflow

Copy structure to Webflow

Custom Javascript in Webflow

Custom CSS in Webflow

Application

Customization

Cleanup

Creator Credits

Welcome to the Vault 👋

GSAP Discount Code

Osmo Slack Community

Need help?

Image Trail Following Cursor

Documentation

External Scripts in Webflow

Copy structure to Webflow

Custom Javascript in Webflow

Custom CSS in Webflow

Application

Customization

Cleanup

Creator Credits