# Cursor Trail Effect
> A portable editorial cursor with dot-and-ring lag, velocity afterimages, elastic target labels, color morphs, and touch previews.
Canonical: https://gsapvault.com/effects/cursor-trail
Live demo: https://gsapvault.com/demos/cursor-trail/index.html
| Property | Value |
|----------|-------|
| Type | effect |
| Tier | paid |
| Price | £5 |
| Difficulty | intermediate |
| Plugins | Core GSAP only |
| Techniques | cursor-effects, hover-effect, velocity-trail, micro-interaction |
| Uses Lenis | No |
## Overview
A responsive custom cursor effect that turns ordinary portfolio and editorial links into tactile interaction moments. A precise dot and delayed ring follow the pointer while fast movement releases fading rings and dots; targets expand the ring into contextual VIEW, PLAY, or OPEN labels. Coarse pointers receive a tap-positioned label pulse instead of a dead hover state.
## Features
- Independent dot and ring tracking with smooth, elastic, and snappy presets
- Velocity-responsive afterimage trail made from reusable dots and rings
- Context labels driven by data-cursor-text on any hover target
- Per-target accent changes with data-cursor-color
- Elastic size and shape morphs with click feedback
- Tap label pulses for coarse-pointer devices
- Optional spotlight mask, sizing controls, and blend mode
- Keyboard focus mirroring, reduced-motion fallback, refresh, and full cleanup
## Use Cases
- Editorial portfolios with contextual project actions
- Creative studio sites with expressive selected-work grids
- Film and motion showcases with PLAY cursor labels
- Agency case-study indexes with per-project accent colors
- Campaign landing pages needing branded pointer feedback
## Vibe-Code Ready Setup
This effect includes `START-HERE-AI.md`, a product-specific copy-paste setup prompt for Cursor, Claude Code, ChatGPT, GitHub Copilot, Windsurf, and other coding assistants. It tells the assistant to inspect the existing stack, integrate the supplied files, preserve the design, scope selectors, retain accessibility and responsive behaviour, add framework-appropriate GSAP cleanup, and report what it tested.
[How AI-assisted setup works](https://gsapvault.com/vibe-coding)
## How It Works
A single CursorTrail instance discovers documented data hooks and creates its visual layers outside the buyer's content. A GSAP ticker interpolates the dot and ring at separate rates, measures pointer velocity, and recycles a small afterimage pool only when movement crosses the speed threshold. Hover and focus events tween ring dimensions, shape, color, and text, while coarse-pointer taps create a short-lived label pulse at the contact point. gsap.context(), gsap.matchMedia(), a listener Map, and the public destroy() and refresh() methods provide predictable lifecycle cleanup.
## Integration Preview
How this effect integrates into a page. The full documentation (examples, events, programmatic API, customization guide) ships with the download.
### Quick Start
**1. Add to your HTML ``:**
```html
```
**2. Add your container and targets to ``:**
```html
Selected work
```
**3. Add before the closing `` tag:**
```html
```
### Options
#### Container options
| Attribute | Values | Default | Description |
|---|---|---:|---|
| `data-cursor-trail` | Boolean | — | Initializes the effect within this container |
| `data-cursor-dot` | Pixel number | `8` | Dot diameter |
| `data-cursor-ring` | Pixel number | `40` | Resting ring diameter |
| `data-cursor-ring-hover` | Pixel number | `60` | Target ring diameter; text labels use at least `76` |
| `data-cursor-color` | Any CSS color | `#2f2bff` | Base cursor and trail color |
| `data-cursor-ease` | `smooth`, `elastic`, `snappy` | `smooth` | Tracking and settle character |
| `data-no-blend` | Boolean | — | Disables `mix-blend-mode: difference` |
| `data-spotlight` | Boolean | — | Adds a radial spotlight mask |
| `data-spotlight-size` | Pixel number | `100` | Spotlight radius |
#### Target options
| Attribute | Values | Default | Description |
|---|---|---:|---|
| `data-cursor-hover` | Boolean | — | Enables hover, focus, and coarse-pointer feedback |
| `data-cursor-text` | Text | Empty | Morphs the ring into a contextual label |
| `data-cursor-color` | Any CSS color | Container color | Changes the cursor and afterimage accent over this target |
### Accessibility
- Pointer targets should be semantic `` or `