Image Trail Card
游標移動時沿路徑留下淡出圖片殘影軌跡的互動卡片，支援原地淡出與飄移兩款動畫。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
120
60
0.9
8
<ImageTrailCard />
安裝
npx shadcn@latest add https://webberui.com/r/image-trail-card.json或在 components.json 設定 registries 後，改用 @webberui/image-trail-card 安裝。
安裝依賴後，從 registry JSON（/r/image-trail-card.json 的 files[0].content）複製 image-trail-card.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge使用
import { ImageTrailCard } from "@/components/ui/image-trail-card";
<ImageTrailCard
images={[
"/gallery/01.jpg",
"/gallery/02.jpg",
"/gallery/03.jpg",
{ src: "/gallery/04.jpg", alt: "作品四" },
]}
className="aspect-[3/2] w-full max-w-md"
>
<p className="text-sm text-neutral-500">移動游標</p>
</ImageTrailCard>images 可傳字串網址，或帶 alt 的物件。清單會依游標位移循環取用，數量不足時自動重複補齊，因此少量圖片也能形成連續軌跡。
款式
fade（預設）：殘影在原地淡出並輕微縮放。drift：殘影淡出時額外向上飄移，軌跡更有流動感。
<ImageTrailCard images={images} variant="drift" />Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
images | Array<string | { src: string; alt?: string }> | — | 殘影圖片來源清單，游標移動時依序循環取用 |
variant | "fade" | "drift" | "fade" | 殘影款式：原地淡出或淡出時向上飄移 |
imageSize | number | 120 | 單張殘影的邊長（px） |
threshold | number | 60 | 生成下一張殘影所需的最小游標位移（px），越小軌跡越密 |
lifetime | number | 0.9 | 單張殘影從出現到消失的存活時間（秒） |
rotate | number | 8 | 每張殘影隨機旋轉的最大角度（deg），設 0 則不旋轉 |
children | React.ReactNode | — | 置於殘影層下方的基礎內容（標題、提示文字等） |
className | string | — | 附加到最外層容器的 class（建議在此設定尺寸與長寬比） |
其餘 <div> 屬性（如 aria-label、style）會透傳到最外層容器；onPointerMove、onPointerLeave 會在內部處理後續呼叫。
細節
- 殘影以固定節點池搭配 Motion 的命令式
animate驅動，游標移動期間直接寫入 DOM 座標與 transform，不觸發 React re-render，高頻移動也維持流暢。 - 節點池數量會依
images長度自動補齊至至少 12、上限 30，避免殘影過早被回收或 DOM 無限增長。 - 以「累積位移超過
threshold才生成下一張」控制軌跡密度，而非每次pointermove都生成。 children位於殘影層下方作為卡片基礎內容，並設為pointer-events-none，不干擾游標追蹤。
可及性
- 使用者系統開啟「減少動態效果」時，停用殘影生成，卡片維持為靜態容器，
children內容照常顯示。 - 殘影層標記
aria-hidden、圖片預設alt=""，視為純裝飾，不會對輔助科技造成朗讀噪音。 - 元件卸載時會停止所有進行中的殘影動畫，清理計時中的動畫控制。