# Image trail (goodtabs UI)

Small images appear behind a moving pointer and fade out, from a fixed recycled pool.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/image-trail.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/image-trail`

## Usage

```tsx
import { ImageTrail } from "@/components/ui/image-trail"

<ImageTrail images={["/work/one.jpg", "/work/two.jpg"]} className="h-dvh">
  <h1>Selected work</h1>
</ImageTrail>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| images | `string[]` |  | Image URLs. The pool cycles through them, and the static row shows the first five. Required. |
| spacing | `number` | `96` | Pointer travel between two images, in px. |

## When to use

- A portfolio or studio hero with plenty of imagery to show
- A closing section that rewards moving around the page
- Once on a page, as the part people play with

## When not to use

- Behind text people need to read for long: the images pass under it
- Images that carry meaning, because they are hidden from screen readers
- Dense pages, where the trail fights the content

## Notes for agents

- GSAP installs from npm under GSAP's own licence. No GSAP code ships in this registry
- The whole image layer is aria-hidden and pointer-events none. Put the real content in children
- Give it a height with className. It clips to its own box and listens only inside it
- Touch and reduced motion get the static row from CSS, so no script runs and nothing flashes

## The maths

- An image lives for 1.1s, so a pool of 16 can spawn every 1100 / 16 = 69ms and never recycle a visible slot.
- Each image starts at the last spawn point and glides to the pointer, so the trail reads as one path.

Docs: https://ui.goodtabs.co/components/image-trail