API
Three components and one JSON format. <GhostCursor> plays a recording, and records too when you open the page with ?record in development. <DevRecorder> shows the record toolbar in development only. <Recorder> records in every environment.
GhostCursor
Use it for every demo you publish. You never need a second component to make a take. GhostReplay is the same component under another name; the agent skill’s snippets use it.
| Prop | Type | Default | Description |
|---|---|---|---|
recording required | Recording | The take to replay. Import it from the JSON file the recorder produced. | |
children required | ReactNode | The component. It renders as usual and stays usable for the reader. | |
className | string | Classes for the box the ghost moves in. The box is at least 240px tall. Set its height here. | |
style | CSSProperties | Inline styles for the box. | |
loopDelay | number | 1600 | How long the final state stays on screen before the take starts over, in ms. |
DevRecorder
The record toolbar around children in next dev, and children alone in a production build, so you don’t need a NODE_ENV check. It takes the same props as <Recorder>.
import { DevRecorder } from "@imuratalpay/ghost-cursor";
<DevRecorder style={{ height: 320 }}>
<LikeButton />
</DevRecorder>Recorder
Use it when recording has to work outside development, for example on an authoring page or in a demo of the recorder itself. For published demos, use <GhostCursor>.
| Prop | Type | Default | Description |
|---|---|---|---|
children required | ReactNode | The component to record. | |
className | string | Classes for the box. | |
style | CSSProperties | Inline styles for the box. | |
onRecord | (recording) => void | Called when Stop ends a take that has at least one event. | |
captureSynthetic | boolean | false | Also record events that scripts dispatch. Turn it on only when a GhostCursor replays a demo of the recorder. |
Attributes
You set data-ghost-id. The ghost sets the other three on the elements it touches and removes them when it moves on, because a script can’t switch on the real CSS states.
| Attribute | Set by | Meaning |
|---|---|---|
data-ghost-id | You | A name for the recorder to use instead of a CSS path. Put one on every element a take clicks or types into. |
data-ghost-hover | Ghost | Mirrors :hover on the element under the ghost and its ancestors. |
data-ghost-active | Ghost | Mirrors :active while the ghost holds a press. |
data-ghost-focus | Ghost | Marks the element a real press would have focused. Real focus never moves during a replay. |
With Tailwind CSS v4, override the variants in your stylesheet and your components need no changes.
@custom-variant hover {
@media (hover: hover) and (pointer: fine) {
&:hover { @slot; }
}
&[data-ghost-hover] { @slot; }
}
@custom-variant active {
&:active { @slot; }
&[data-ghost-active] { @slot; }
}
@custom-variant focus {
&:focus { @slot; }
&[data-ghost-focus] { @slot; }
}Colors
Every color in the stylesheet is a variable on .gc-root, and the defaults are a light theme. Map them to your own tokens to follow your color scheme.
.gc-root {
--gc-fg: var(--fg-1); /* buttons and icons */
--gc-muted: var(--fg-3); /* time, hints */
--gc-stage: var(--stage); /* the box */
--gc-surface: var(--surface);
--gc-line: var(--line);
}Behavior
| When | The player |
|---|---|
| The reader’s mouse enters the box | Fades the ghost out and stops the playhead. The component is the reader’s. |
| The reader leaves without clicking or typing | Fades the ghost back in after 420ms and continues from where it stopped. |
| The reader leaves after clicking or typing | Remounts the component to its first frame and starts the take over. |
| The reader tabs into the box | Steps aside the same way, until focus leaves the box. |
| The box scrolls out of view, or the tab is hidden | Pauses. |
| The reader prefers reduced motion | Doesn’t autoplay. It shows the first frame and a Play button that runs the take once. |
| The take ends | Holds the final state for loopDelay. If the DOM changed, it cross-fades back to the first frame. |
Clicks wait for the cursor. The drawn arrow trails the recorded path because it runs through a spring, so the playhead holds each press until the tip is within 3px of its target.
Keyboard
| Key | Where | Action |
|---|---|---|
| Space | Pointer over the demo, or focus in its controls | Pause or resume |
| ← → | Scrubber | Seek 250ms, or 1s with Shift |
| Home End | Scrubber | Jump to the start or the end |
Inside the box, every key goes to the component.
Recording format
One JSON object per take. Coordinates run from 0 to 1 across the box. Each press also stores where it landed inside its target, so a take recorded at one width still hits its targets at another.
type Recording = {
v: 1;
size: [width: number, height: number]; // box size while recording, in px
targets: string[]; // "@name", or a CSS path from the content root
events: (
| [t: number, "m", x: number, y: number] // move
| [t: number, "d" | "u" | "c", x: number, y: number,
target?: number, offsetX?: number, offsetY?: number] // down, up, click
| [t: number, "k", key: string, target?: number, mods?: number] // key press
)[];
};Limits
The ghost dispatches events. It isn’t a browser. A component that calls setPointerCapture during a replay throws, because the synthetic pointer isn’t active. Recorded Tab presses don’t move focus. Enter and Space activate buttons and checkboxes the way a browser would, and typing works in text inputs and textareas.