Skip to content
/ghost-cursor

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-cursor

Then load the stylesheet once. With Tailwind CSS v4, import it into the components layer, so classes you pass to the box override its defaults.

app/globals.css
@import "tailwindcss";
@import "@imuratalpay/ghost-cursor/styles.css" layer(components);

Without Tailwind, import @imuratalpay/ghost-cursor/styles.css in your root layout.

npm i @imuratalpay/ghost-cursor
0.0s
The ghost copies the install command. Move into the box to press the button yourself.

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.

Writing
  • Springs, not curves1,240 reads
  • The cost of a hover3,810 reads
  • Ghosts in the DOM2,275 reads
  • A menu, slowly960 reads
0.0s
The wrapped menu. The highlight follows the ghost because the menu listens for 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.

Press Record, then use the component in the box.
0.0s
The real recorder, replaying a take of itself. The ghost presses Record, likes, presses Stop, then copies. The event count comes from the ghost’s own events.