Image Trail

1// author: Khoa Phan <https://www.pldkhoa.dev>
2 
3"use client"
4 
5import React, { ElementType, HTMLAttributes, useEffect, useMemo } from "react"
6import type { DOMKeyframesDefinition, AnimationOptions } from "motion"
7import { useAnimate } from "motion/react"
8 
9import { cn } from "@/lib/utils"
10 
11interface ImageTrailProps extends HTMLAttributes<HTMLDivElement> {
12  /**
13   * The content to be displayed
14   */
15  children: React.ReactNode
16 
17  /**
18   * HTML Tag
19   */
20  as?: ElementType
21 
22  /**
23   * How much distance in pixels the mouse has to travel to trigger of an element to appear.
24   */
25  threshold?: number
26 
27  /**
28   * The intensity for the momentum movement after showing the element. The value will be clamped > 0 and <= 1.0. Defaults to 0.3.
29   */
30  intensity?: number
31 
32  /**
33   * Animation Keyframes for defining the animation sequence. Example: { scale: [0, 1, 1, 0] }
34   */
35  keyframes?: DOMKeyframesDefinition
36 
37  /**
38   * Options for the animation/keyframes. Example: { duration: 1, times: [0, 0.1, 0.9, 1] }
39   */
40  keyframesOptions?: AnimationOptions
41 
42  /**
43   * Animation keyframes for the x and y positions after showing the element. Describes how the element should try to arrive at the mouse position.
44   */
45  trailElementAnimationKeyframes?: {
46    x?: AnimationOptions
47    y?: AnimationOptions
48  }
49 
50  /**
51   * The number of times the children will be repeated. Defaults to 3.
52   */
53  repeatChildren?: number
54 
55  /**
56   * The base zIndex for all elements. Defaults to 0.
57   */
58  baseZIndex?: number
59 
60  /**
61   * Controls stacking order behavior.
62   * - "new-on-top": newer elements stack above older ones (default)
63   * - "old-on-top": older elements stay visually on top
64   */
65  zIndexDirection?: "new-on-top" | "old-on-top"
66}
67 
68interface ImageTrailItemProps extends HTMLAttributes<HTMLDivElement> {
69  /**
70   * HTML Tag
71   */
72  as?: ElementType
73 
74  /**
75   * The content to be displayed
76   */
77  children: React.ReactNode
78}
79 
80/**
81 * Helper functions
82 */
83const MathUtils = {
84  // linear interpolation
85  lerp: (a: number, b: number, n: number) => (1 - n) * a + n * b,
86  // distance between two points
87  distance: (x1: number, y1: number, x2: number, y2: number) =>
88    Math.hypot(x2 - x1, y2 - y1),
89}
90 
91const ImageTrail = ({
92  className,
93  as = "div",
94  children,
95  threshold = 100,
96  intensity = 0.3,
97  keyframes,
98  keyframesOptions,
99  repeatChildren = 3,
100  trailElementAnimationKeyframes = {
101    x: { duration: 1, type: "tween", ease: "easeOut" },
102// … truncated