Getting started
ghost-cursor plays back a recording of someone using your component, in the page, with real DOM events. The component doesn’t know it’s being replayed. When a reader moves into the box, the ghost fades out and the component is theirs.
Three steps get you from install to your first take. If you’re an agent, read For agents or /llms.txt instead: it has the exact steps for recording a take and for mounting the record toolbar.
Step 1: Install the package
npm installs Motion alongside it as a peer dependency. Motion drives the cursor’s spring. You need React 18 or later.
npm i @imuratalpay/ghost-cursorThen load the stylesheet once. With Tailwind CSS v4, import it into the components layer, so classes you pass to the box override its defaults.
@import "tailwindcss";
@import "@imuratalpay/ghost-cursor/styles.css" layer(components);Without Tailwind, import @imuratalpay/ghost-cursor/styles.css in your root layout.
Step 2: Wrap a component
Put the component inside <GhostCursor> and give the box a height. Add data-ghost-id to every element the cursor clicks. The recording finds elements by that name, so it keeps working when the markup around them changes.
import { GhostCursor } from "@imuratalpay/ghost-cursor";
import recording from "./sort-menu.json";
export function Demo() {
return (
<GhostCursor recording={recording} className="h-[300px]">
<SortMenu />
</GhostCursor>
);
}
// inside SortMenu
<button data-ghost-id="sort-trigger">Sort</button>A script can’t switch on :hover, so the ghost sets data-ghost-hover on whatever it points at and data-ghost-active while it presses. Style both next to the real states.
.menu-item:hover,
.menu-item[data-ghost-hover] {
background: #f4f4f4;
}With Tailwind, override the variants once and keep writing hover:. The API page has the snippet.
- Springs, not curves1,240 reads
- The cost of a hover3,810 reads
- Ghosts in the DOM2,275 reads
- A menu, slowly960 reads
pointermove. Space pauses while you point at the controls.Step 3: Record a take
Run your dev server and open the page with ?record at the end of the URL. Every <GhostCursor> on the page becomes a recorder. Press Record, use the component, then press Stop. Copy recording puts the JSON on your clipboard. Paste it into the file you import.
The recorder only exists in development builds. In production, ?record does nothing.